@pugi/cli 0.1.0-beta.24 → 0.1.0-beta.26

package/dist/core/dispatch/cache-handoff.js

@@ -0,0 +1,295 @@
+/**
+ * Fork-subagent prompt-cache inheritance (Leak L10 — 2026-05-27).
+ *
+ * Claude Code's leaked sub-agent spawn pattern: when a parent agent
+ * dispatches a child via the Task tool, the child boots with the parent's
+ * prompt cache REFERENCE inherited — not the conversation transcript
+ * verbatim, but a provider-native cache handle that lets the child reuse
+ * the parent's system prompt + cached tool definitions without re-paying
+ * the prompt-prefix tokens on the first turn.
+ *
+ * Anthropic's `cache_control` block in their messages API exposes this
+ * directly via cache breakpoints. OpenAI / xAI / Gemini have similar
+ * primitives at different granularities; the wire payload our Anvil
+ * proxy speaks is provider-agnostic, so we forward a generic
+ * `parent_cache_id` hint and Anvil routes it onto the underlying
+ * provider's cache primitive (or silently drops it if the provider
+ * doesn't support cache inheritance — graceful degrade).
+ *
+ * What this module does:
+ *
+ *   1. `inheritCacheContext(parentSessionId, childAgentId)` —
+ *      synthesises a cache handle for a child dispatch. Persists the
+ *      handle to `.pugi/cache-refs/<child-agent-id>.json` so:
+ *
+ *        a. The child's own boot path can read it (e.g. a child engine
+ *           loop running in a worktree subshell where the in-memory
+ *           DispatcherContext isn't reachable).
+ *        b. `pugi dispatch list-cache-refs` can surface active refs
+ *           for debugging "why is my cache hit rate so low".
+ *        c. `pugi dispatch clear-cache-refs --older-than 1h` can
+ *           garbage-collect stale refs from crashed/killed children.
+ *
+ *   2. `readCacheRef(workspaceRoot, childAgentId)` — child-side read.
+ *      Returns the persisted handle so the child's first engine loop
+ *      turn can include the parent_cache_id hint in its request.
+ *
+ *   3. `cacheHandoffHookForRequest(handle)` — produces the wire payload
+ *      shape that the Anvil bridge can splice into the
+ *      `engineLoopServerRequest` body. Lives here (not in the bridge)
+ *      so the cache-control schema is in one place.
+ *
+ * What this module does NOT do:
+ *
+ *   - It does not replay the parent's conversation transcript into the
+ *     child. That would defeat the cyber-zoo isolation contract
+ *     (`shared_fs_readonly` etc.). The child gets a CACHE HINT — the
+ *     provider may use it to skip re-tokenising shared prompt prefix,
+ *     but the LOGICAL conversation always starts fresh from the child's
+ *     own system prompt + brief.
+ *
+ *   - It does not assume any provider honours the hint. Cache-miss is
+ *     the default path. If Anvil routes the request to a model whose
+ *     provider doesn't expose cache inheritance, the request still
+ *     succeeds — just at full prompt-prefix cost.
+ *
+ *   - It does not rotate or invalidate the parent's cache on the
+ *     parent's side. Parent cache lifecycle is owned by the parent
+ *     engine loop; the child holds a read-only reference.
+ *
+ * Cross-reference:
+ *   - apps/pugi-cli/src/core/subagents/dispatcher-real.ts — where the
+ *     child engine loop is driven; the cache_id from this module is
+ *     forwarded onto Anvil via the `extensions` field of the engine
+ *     loop server request (β2 forward-compat slot).
+ *   - packages/pugi-sdk/src/engine-loop.ts — engineLoopServerRequest
+ *     schema; cache-handoff field is OPTIONAL and additive.
+ *
+ * Leak research §L10 (Claude Code sub-agent spawn fork pattern):
+ * docs/research/2026-05-27-leak-parity-sprint.md (research memo).
+ */
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+/* ------------------------------------------------------------------ */
+/* Types + schema                                                     */
+/* ------------------------------------------------------------------ */
+/**
+ * Persisted cache reference. The shape is intentionally minimal —
+ * provider-specific cache tokens are opaque strings so the file format
+ * does not couple to any one provider's API.
+ *
+ *   - `cacheId`         — opaque provider hint forwarded to Anvil.
+ *                         Synthesized client-side as `pugi-cache-<uuid>`
+ *                         so the server has a stable correlation key
+ *                         even when the underlying provider's cache
+ *                         object is not yet provisioned.
+ *   - `contextRef`      — logical reference key the parent uses to tag
+ *                         which prompt segments to re-use. Same value
+ *                         as cacheId for the v1 wire (single breakpoint
+ *                         per parent); reserved for future multi-breakpoint
+ *                         schemes (split system + tools + first-user
+ *                         segments).
+ *   - `parentSessionId` — debugging / GC scoping. `list-cache-refs`
+ *                         can group by parent session.
+ *   - `childAgentId`    — the dispatch this ref is scoped to.
+ *   - `createdAt`       — ISO timestamp for `--older-than` cleanup.
+ *   - `schemaVersion`   — pinned to 1; bumped on breaking shape change.
+ */
+export const cacheRefSchema = z.object({
+    schemaVersion: z.literal(1),
+    cacheId: z.string().min(1).max(256),
+    contextRef: z.string().min(1).max(256),
+    parentSessionId: z.string().min(1).max(256),
+    childAgentId: z.string().min(1).max(256),
+    createdAt: z.string().min(1),
+});
+/* ------------------------------------------------------------------ */
+/* Path resolution                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Resolve the directory under `.pugi/` where cache refs live. The
+ * directory is created on first write — readers tolerate its absence
+ * (no refs = empty list, not an error).
+ */
+export function cacheRefDir(workspaceRoot) {
+    return resolvePath(workspaceRoot, '.pugi', 'cache-refs');
+}
+function cacheRefPath(workspaceRoot, childAgentId) {
+    // Sanitise the child id — directory traversal via crafted child id
+    // would let a dispatch target write outside the cache-refs dir. The
+    // child id format is owned by spawn.ts (`subagent-<uuid>`) but we
+    // defend in depth.
+    const safe = childAgentId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 200);
+    return join(cacheRefDir(workspaceRoot), `${safe}.json`);
+}
+/**
+ * Synthesize a cache handle for a child dispatch and persist it to
+ * `.pugi/cache-refs/<childAgentId>.json`. Returns the in-memory handle
+ * the dispatcher feeds into the Anvil wire request.
+ *
+ * Idempotent: calling twice with the same `childAgentId` overwrites
+ * the existing ref. The dispatcher's `taskId` is a UUID per dispatch,
+ * so collisions are not expected, but the overwrite semantic is safer
+ * than failing — a stale ref from a previous run (e.g. process killed
+ * between spawn and run) should not block a fresh dispatch.
+ */
+export function inheritCacheContext(parentSessionId, childAgentId, options) {
+    if (!parentSessionId) {
+        throw new Error('inheritCacheContext: parentSessionId must be non-empty');
+    }
+    if (!childAgentId) {
+        throw new Error('inheritCacheContext: childAgentId must be non-empty');
+    }
+    const now = options.now ?? defaultNow;
+    const cacheIdFactory = options.cacheIdFactory ?? defaultCacheId;
+    const cacheId = cacheIdFactory();
+    const ref = {
+        schemaVersion: 1,
+        cacheId,
+        contextRef: cacheId,
+        parentSessionId,
+        childAgentId,
+        createdAt: now(),
+    };
+    const dir = cacheRefDir(options.workspaceRoot);
+    mkdirSync(dir, { recursive: true });
+    const path = cacheRefPath(options.workspaceRoot, childAgentId);
+    writeFileSync(path, JSON.stringify(ref, null, 2), 'utf8');
+    return {
+        cacheId: ref.cacheId,
+        contextRef: ref.contextRef,
+        persistedPath: path,
+    };
+}
+/**
+ * Child-side read. Returns null when the ref is missing or malformed
+ * (the child boots without cache inheritance — degrade is silent so a
+ * corrupted ref does not block a dispatch).
+ *
+ * Malformed ref files are NOT auto-deleted by this read path — that's
+ * the cleanup command's job. A failed parse here just returns null so
+ * the dispatch proceeds at full prompt-prefix cost.
+ */
+export function readCacheRef(workspaceRoot, childAgentId) {
+    const path = cacheRefPath(workspaceRoot, childAgentId);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const validated = cacheRefSchema.safeParse(parsed);
+    if (!validated.success)
+        return null;
+    return validated.data;
+}
+/**
+ * List every persisted cache ref under `.pugi/cache-refs/`. Used by
+ * `pugi dispatch list-cache-refs` and by GC sweeps in
+ * `cache-cleanup.ts`. Returns refs in deterministic
+ * (filename-ascending) order so the CLI output is stable.
+ *
+ * Malformed ref files are silently skipped — the cleanup command can
+ * surface them via a separate `--show-corrupt` flag if needed.
+ */
+export function listCacheRefs(workspaceRoot) {
+    const dir = cacheRefDir(workspaceRoot);
+    let entries;
+    try {
+        entries = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+    const refs = [];
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        let raw;
+        try {
+            raw = readFileSync(full, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const validated = cacheRefSchema.safeParse(parsed);
+        if (!validated.success)
+            continue;
+        refs.push(validated.data);
+    }
+    return refs;
+}
+/* ------------------------------------------------------------------ */
+/* Wire-format hook                                                   */
+/* ------------------------------------------------------------------ */
+/**
+ * Project the in-memory handle (or persisted ref) onto the wire-format
+ * hint object that the Anvil bridge merges into the engine-loop
+ * request body. Pulled out so callers (dispatcher-real, future bridge
+ * adapters) all speak the same shape.
+ */
+export function cacheHandoffHookForRequest(source) {
+    return {
+        parent_cache_id: source.cacheId,
+        cache_context_ref: source.contextRef,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Internals                                                          */
+/* ------------------------------------------------------------------ */
+function defaultNow() {
+    return new Date().toISOString();
+}
+function defaultCacheId() {
+    return `pugi-cache-${randomUUID()}`;
+}
+/* ------------------------------------------------------------------ */
+/* Stat helper (used by cache-cleanup.ts)                             */
+/* ------------------------------------------------------------------ */
+/**
+ * Exposed for cache-cleanup.ts so the GC sweep can read mtime without
+ * re-implementing the path-resolution logic. Returns null when the
+ * file is gone (a concurrent cleanup may have raced us — silent miss).
+ */
+export function cacheRefMtime(workspaceRoot, childAgentId) {
+    try {
+        const stat = statSync(cacheRefPath(workspaceRoot, childAgentId));
+        return stat.mtime;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a single cache ref. Returns true when the file existed and
+ * was removed, false when it was already gone. Used by both the
+ * `clear-cache-refs` CLI and by post-dispatch cleanup (a successful
+ * subagent run does not need the cache ref to outlive its dispatch).
+ */
+export function deleteCacheRef(workspaceRoot, childAgentId) {
+    const path = cacheRefPath(workspaceRoot, childAgentId);
+    try {
+        rmSync(path, { force: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=cache-handoff.js.map

package/dist/core/engine/native-pugi.js

@@ -260,6 +260,47 @@ export class NativePugiEngineAdapter {
                     ambientContextBlock = '';
                 }
             }
+            // Leak L28 (2026-05-27): AST-light repo-map injection. We build a
+            // compact `## Repo map` block (capped at the formatter's default
+            // 8 KB ≈ 2K tokens) from the workspace source tree + splice it
+            // onto the system prompt alongside the ambient PUGI.md block.
+            // `--bare` skips this exactly like the PUGI.md walk — the engine
+            // sees nothing the operator did not explicitly hand it. The build
+            // is deferred к `setImmediate` semantics by being a sync call
+            // AFTER the boot probes; the cost is one stat per source file
+            // (the cache catches mtime-unchanged files и skips re-extraction).
+            // Failures are swallowed: repo-map is enrichment, never a gate.
+            let repoMapBlock = '';
+            if (!isBareMode()) {
+                try {
+                    const { buildAndFormatRepoMap } = await import('../repo-map/build.js');
+                    const verdict = buildAndFormatRepoMap({
+                        root,
+                        // Boot path is best-effort: never refresh during engine boot
+                        // (the operator can `pugi repo-map --refresh` manually). The
+                        // cache freshness check catches every realistic edit pattern
+                        // and avoids walking the tree on every engine invocation.
+                        refresh: false,
+                        // Persist the cache so the next boot reuses extracts. Engine
+                        // boot runs on every command, so missing the persist would
+                        // hot-loop the extractor on each invocation.
+                        writeCache: true,
+                        // Omit the formatter's section header — the system prompt
+                        // already structures the ambient blocks, и a second `##`
+                        // would fragment the prompt cache на a model-by-model basis.
+                        omitHeader: false,
+                    });
+                    if (verdict.build.ok && verdict.format && verdict.format.bytes > 0) {
+                        repoMapBlock = verdict.format.text;
+                    }
+                }
+                catch {
+                    // Any failure in the repo-map pipeline drops the block. The
+                    // engine continues without enrichment — the failure mode is
+                    // identical to the cold-boot path before L28 landed.
+                    repoMapBlock = '';
+                }
+            }
             let traverseResult;
             // Leak L22 (2026-05-27): `--bare` skips the parent-dir PUGI.md /
             // AGENTS.md / CLAUDE.md / GEMINI.md walk-up. The engine sees only
@@ -579,9 +620,17 @@ export class NativePugiEngineAdapter {
                         // nothing OR bare mode is on, `ambientContextBlock === ''`
                         // and the system prompt is unchanged — no leading blank
                         // line, no empty wrapper tag.
-                        systemPrompt: ambientContextBlock
-                            ? `${ambientContextBlock}\n\n${systemPromptFor(kind)}`
-                            : systemPromptFor(kind),
+                        //
+                        // Leak L28 (2026-05-27): the `repoMapBlock` is splice'd
+                        // between the ambient PUGI.md and the persona prompt so
+                        // the model sees the workspace structure WITH the operator's
+                        // ambient guidance fronting it. Empty blocks drop cleanly:
+                        // `composeSystemPrompt` filters falsy entries before joining.
+                        systemPrompt: composeSystemPrompt([
+                            ambientContextBlock,
+                            repoMapBlock,
+                            systemPromptFor(kind),
+                        ]),
                         // β5a R5+R6+P1: per-turn `<context>` prefix + intent marker
                         // applied above. Falls back to verbatim `task.prompt` when
                         // both the prefix block is empty AND the intent classifier
@@ -949,4 +998,19 @@ function relativeOrAbsolute(workspaceRoot, cwd) {
     const rel = absCwd.startsWith(absRoot + '/') ? absCwd.slice(absRoot.length + 1) : null;
     return rel ?? absCwd;
 }
+/**
+ * Leak L28 helper — splice multiple ambient blocks onto a persona
+ * system prompt, dropping empty entries cleanly. The join character
+ * is `\n\n` so each block renders as a discrete paragraph the model
+ * can attend к without bleeding into its neighbour.
+ *
+ * Empty blocks return the base prompt unchanged — no leading
+ * separators, no trailing whitespace. Mirrors the original
+ * `ambientContextBlock ? ... : ...` shape so the single-block path
+ * before L28 stays byte-identical (prompt cache friendliness).
+ */
+export function composeSystemPrompt(blocks) {
+    const nonEmpty = blocks.map((b) => b.trim()).filter((b) => b.length > 0);
+    return nonEmpty.join('\n\n');
+}
 //# sourceMappingURL=native-pugi.js.map

package/dist/core/engine/tool-bridge.js

@@ -14,6 +14,7 @@ import { buildDenialContext, DENIAL_REMINDER_THRESHOLD, } from '../denial-tracki
 import { stripInternalFields } from './strip-internal-fields.js';
 import { applyAskAnswer, gate as permissionGate, getToolClass, PermissionDenied, } from '../permissions/index.js';
 import { RetryBudget, RetryBudgetExhausted, hashArgs } from '../retry-budget/index.js';
+import { runPostEditDiagnostics, } from '../lsp/post-edit-diagnostics.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -516,7 +517,7 @@ function requireString(obj, key) {
     throw new Error(`tool argument "${key}" must be a string`);
 }
 export function buildExecutor(input) {
-    const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry, permissionMode, permissionAlwaysCache, permissionAsk, } = input;
+    const { kind, ctx, hooks, mvpHooksConfig, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry, permissionMode, permissionAlwaysCache, permissionAsk, } = input;
     // Leak L31: per-cycle budget. Default to a fresh instance scoped to
     // this executor's closure lifetime; tests pass their own.
     const retryBudget = input.retryBudget ?? new RetryBudget();
@@ -687,6 +688,33 @@ export function buildExecutor(input) {
                 }
             }
         }
+        // Leak L12 MVP: fire `hooks-mvp.json` PreToolUse hooks. Distinct
+        // config file from the legacy `hooks.json` system so operator
+        // configs do not collide. Same blocking semantics — a non-zero
+        // exit from a hook declared `blocking: true` refuses the dispatch
+        // with `HOOK_BLOCKED:` sentinel. Bypass mode skips this surface
+        // identically to the legacy hooks block above.
+        if (mvpHooksConfig && sessionId && !hooksBypassed && !mvpHooksConfig.isEmpty()) {
+            const { fireHooks } = await import('../hooks/index.js');
+            const outcome = await fireHooks({
+                config: mvpHooksConfig,
+                event: 'PreToolUse',
+                payload: {
+                    event: 'PreToolUse',
+                    sessionId,
+                    toolName: name,
+                    toolInputSummary: hashArgs(argsRaw),
+                },
+                toolName: name,
+                workspaceRoot: ctx.root,
+            });
+            if (outcome.anyBlocked) {
+                const blocking = outcome.results.find((r) => r.blocked);
+                const sentinel = blocking?.blockSentinel ??
+                    `HOOK_BLOCKED: PreToolUse MVP-hook refused ${name}`;
+                throw recordDenial(name, argsForTracking, sentinel);
+            }
+        }
         // β4 M1/M3: MCP dispatch deferred to the `dispatch` closure below so
         // PostToolUse / PostToolUseFailure hooks observe MCP calls just like
         // native calls. The dispatcher does its own argument parsing — MCP
@@ -756,6 +784,14 @@ export function buildExecutor(input) {
         };
         try {
             const result = await dispatch();
+            // Leak L15 (2026-05-27): post-edit LSP diagnostics. After a
+            // successful `edit` / `write` / `multi_edit`, ask the cached
+            // language server for diagnostics on the touched file(s) and
+            // append the result to the tool envelope so the model can
+            // self-correct in the same turn. Silent skip when the language
+            // is unsupported, no server is installed, or the request times
+            // out — agent throughput beats diagnostic recall.
+            const augmented = await appendPostEditDiagnostics(name, args, ctx, result);
             if (hooks && sessionId && !hooksBypassed) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
@@ -763,10 +799,10 @@ export function buildExecutor(input) {
                     event: 'PostToolUse',
                     tool: name,
                     path,
-                    payload: { tool: name, arguments: argsRaw, ok: true, result: result.slice(0, 1024) },
+                    payload: { tool: name, arguments: argsRaw, ok: true, result: augmented.slice(0, 1024) },
                 });
             }
-            return result;
+            return augmented;
         }
         catch (error) {
             // Leak L6 — surface the PermissionDenied sentinel as a model-
@@ -1161,4 +1197,88 @@ function dispatchMultiEdit(args, ctx) {
     const result = multiEdit(ctx, edits);
     return JSON.stringify(result);
 }
+/* ---------------------------- Leak L15 hook ---------------------------- */
+/**
+ * Tool names that mutate workspace files. After a successful dispatch
+ * of any of these, the L15 post-edit diagnostics hook fires. The set
+ * is intentionally tight — `task_*` / `todo_write` write to ledger
+ * files (not workspace source) so they stay out, and `bash` is too
+ * coarse (a `bash` call can write any path, and we'd need to parse
+ * the command to know which — out of scope for L15).
+ */
+const POST_EDIT_TOOLS = new Set(['edit', 'write', 'multi_edit']);
+/**
+ * Append LSP diagnostics to the tool envelope after a successful
+ * edit / write / multi_edit. Silent skip is the default — missing
+ * binary, unsupported language, request timeout, and "no diagnostics"
+ * all leave the envelope unchanged.
+ *
+ * Opt-in via `.pugi/settings.json::lsp.postEditDiagnostics = true`
+ * OR `PUGI_LSP_POST_EDIT=1`. Off by default until dogfood validates
+ * the cold-start cost vs the model-loop benefit (Leak L15).
+ */
+async function appendPostEditDiagnostics(name, args, ctx, result) {
+    if (!POST_EDIT_TOOLS.has(name))
+        return result;
+    if (!isPostEditEnabled(ctx))
+        return result;
+    const paths = extractEditedPaths(name, args);
+    if (paths.length === 0)
+        return result;
+    const tails = [];
+    for (const filePath of paths) {
+        const opts = {
+            cwd: ctx.root,
+            ...(ctx.settings.lsp ? { lspSettings: ctx.settings.lsp } : {}),
+        };
+        try {
+            const diag = await runPostEditDiagnostics(filePath, opts);
+            if (!diag.skip) {
+                tails.push(diag.tail);
+            }
+        }
+        catch {
+            // Belt-and-suspenders: any unexpected throw from the hook is
+            // swallowed. The model never blocks on LSP.
+        }
+    }
+    if (tails.length === 0)
+        return result;
+    return `${result}\n${tails.join('\n')}`;
+}
+function isPostEditEnabled(ctx) {
+    const envFlag = process.env.PUGI_LSP_POST_EDIT;
+    if (envFlag === '1' || envFlag === 'true')
+        return true;
+    if (envFlag === '0' || envFlag === 'false')
+        return false;
+    return ctx.settings.lsp?.postEditDiagnostics === true;
+}
+/**
+ * Pull the workspace-relative file path(s) the tool just touched.
+ * Each branch mirrors the args shape its `dispatch*` handler reads;
+ * a deformed args object yields an empty list so the hook silently
+ * skips instead of throwing inside the augmentation layer.
+ */
+function extractEditedPaths(name, args) {
+    if (name === 'edit' || name === 'write') {
+        const path = args['path'];
+        return typeof path === 'string' && path.length > 0 ? [path] : [];
+    }
+    if (name === 'multi_edit') {
+        const edits = args['edits'];
+        if (!Array.isArray(edits))
+            return [];
+        const seen = new Set();
+        for (const entry of edits) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const file = entry['file'];
+            if (typeof file === 'string' && file.length > 0)
+                seen.add(file);
+        }
+        return Array.from(seen);
+    }
+    return [];
+}
 //# sourceMappingURL=tool-bridge.js.map

package/dist/core/hooks/events.js

@@ -0,0 +1,44 @@
+/**
+ * Pugi hooks MVP — typed event payloads (Leak L12).
+ *
+ * This module ships the MINIMAL FIRST PASS of the user-config hook
+ * matrix. Two lifecycle events out of the eventual 8 land here:
+ *
+ *   - `SessionStart`  — fired once when the REPL boots (`session.ts`).
+ *   - `PreToolUse`    — fired before each tool dispatch
+ *                       (`engine/tool-bridge.ts`). Non-zero exit from a
+ *                       hook with `blocking: true` aborts the dispatch.
+ *
+ * The remaining 6 events (`PostToolUse`, `UserPromptSubmit`, `Stop`,
+ * `SubagentStop`, `PreCompact`, `Notification`) are deferred to a
+ * fast-follow PR. The pattern established here — discriminated union
+ * payloads + registry-driven dispatch — is the reusable template.
+ *
+ * Design note (parallel surface): an older surface lives at
+ * `apps/pugi-cli/src/core/hooks.ts` and uses a flat-array `hooks: [{
+ * event, match, run }]` config shape with per-hook events. THIS module
+ * adopts the Claude Code-style nested `hooks: { EventName: [{ matcher,
+ * command }] }` config shape. The two surfaces co-exist intentionally
+ * for the MVP — they read different files (`~/.pugi/hooks.json` vs.
+ * `~/.pugi/hooks-mvp.json`) so operator configs do not collide. The
+ * fast-follow PR consolidates the two readers.
+ *
+ * Brand voice: ASCII only, no emoji, no em-dashes, no marketing prose.
+ */
+/** Events the MVP actually fires. The 6 deferred events live in the */
+/** type but no integration point emits them yet. */
+export const MVP_HOOK_EVENTS = [
+    'SessionStart',
+    'PreToolUse',
+];
+export const ALL_HOOK_EVENTS_V2 = [
+    'SessionStart',
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'Stop',
+    'SubagentStop',
+    'PreCompact',
+    'Notification',
+];
+//# sourceMappingURL=events.js.map

package/dist/core/hooks/index.js

@@ -0,0 +1,15 @@
+/**
+ * Public surface of the MVP hooks module (Leak L12).
+ *
+ * Re-exports the registry, runner, and event types so callers can do
+ *
+ *   import { loadHooksConfig, fireHooks } from '../core/hooks/index.js';
+ *
+ * without reaching into individual files. See `events.ts` for the
+ * scope note explaining why this MVP module co-exists with the older
+ * `src/core/hooks.ts` surface.
+ */
+export { DEFAULT_HOOK_TIMEOUT_MS, HooksConfig, MAX_HOOK_TIMEOUT_MS, defaultHooksMvpPath, isToolEvent, loadHooksConfig, matchesTool, } from './registry.js';
+export { fireHooks } from './runner.js';
+export { ALL_HOOK_EVENTS_V2, MVP_HOOK_EVENTS, } from './events.js';
+//# sourceMappingURL=index.js.map