@pugi/cli 0.1.0-beta.23 → 0.1.0-beta.25

package/dist/core/engine/compaction-hook.js

@@ -0,0 +1,154 @@
+/**
+ * Engine loop integration point for the six-tier compaction engine.
+ *
+ * `maybeCompactAfterTool` is the single function the engine loop calls
+ * after each tool result has been appended to the transcript. It:
+ *
+ *   1. Estimates current context-window pressure (transcript bytes
+ *      against the model's budget, plus the static blocks).
+ *   2. Calls `selectTier` on the snapshot.
+ *   3. Runs the tier. Microcompact / cached_microcompact are sync;
+ *      reactive_summary / session_memory / full_compaction / reset
+ *      are async-shaped (the call returns before commit when run
+ *      against a long transcript) but currently run inline — the
+ *      engine loop is single-threaded today, so true backgrounding
+ *      waits for the SSE consumer refactor in α5.7.
+ *   4. Runs invariant checks against the result. On any violation,
+ *      emits `compaction.invariant_violated` and returns the
+ *      pre-compaction transcript untouched.
+ *   5. On success, emits `compaction.completed` with reclaim numbers
+ *      and returns the new transcript for the caller to adopt.
+ *   6. On no-op, emits `compaction.skipped` and returns the original.
+ *
+ * Why a separate file (not inlined into `native-pugi.ts`):
+ *
+ *   Sprint α5.3 (feat/pugi-cli-hooks-lifecycle-m1-gap-c) is in flight
+ *   and already modifies session.ts + tool-bridge + permission. Editing
+ *   native-pugi.ts in this PR risks a merge conflict against α5.3's
+ *   landing PR. Keeping the wiring as an exported helper means the
+ *   one-line callsite in native-pugi.ts can be added in a tiny
+ *   follow-up after both α5.3 and α5.5 have landed.
+ *
+ * Expected callsite in `apps/pugi-cli/src/core/engine/native-pugi.ts`,
+ * inside `onToolResult`:
+ *
+ *   ```ts
+ *   const compactionOutcome = await maybeCompactAfterTool({
+ *     session,
+ *     transcript: currentTranscript,
+ *     toolOutputs: recentToolOutputs,
+ *     contextBudgetUsed: estimatedTokens,
+ *     contextBudgetMax: budget.maxTokens,
+ *     workspaceRoot: root,
+ *     contextStaticHash: {
+ *       instructionsHash,
+ *       toolSchemaHash,
+ *     },
+ *   });
+ *   if (compactionOutcome.committed) {
+ *     currentTranscript = compactionOutcome.newTranscript;
+ *   }
+ *   ```
+ */
+import { runCompaction, selectTier, } from '../context/compaction.js';
+import { checkInvariants } from '../context/invariants.js';
+import { emitCompactionCompleted, emitCompactionInvariantViolated, emitCompactionSkipped, emitCompactionStarted, } from '../context/compaction-events.js';
+/**
+ * Engine-loop callback. See file header for the expected callsite shape.
+ *
+ * Contract:
+ *   - Never throws. All errors degrade to `committed: false` with the
+ *     original transcript and an event record.
+ *   - On `committed: true`, the caller MUST adopt `newTranscript` as
+ *     the live working transcript for the next model turn.
+ *   - On `committed: false`, the caller MUST keep the input transcript
+ *     and try again on the next tool turn (compaction will retry once
+ *     pressure stays above threshold).
+ */
+export async function maybeCompactAfterTool(input) {
+    const compactionInput = {
+        sessionId: input.session.id,
+        contextBudgetUsed: input.contextBudgetUsed,
+        contextBudgetMax: input.contextBudgetMax,
+        toolOutputs: input.toolOutputs,
+        transcript: input.transcript,
+        workspaceRoot: input.workspaceRoot,
+    };
+    const tier = selectTier(compactionInput);
+    emitCompactionStarted(input.session, tier, {
+        budgetUsed: input.contextBudgetUsed,
+        budgetMax: input.contextBudgetMax,
+    });
+    let result;
+    try {
+        result = await runCompaction(compactionInput, tier);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        emitCompactionSkipped(input.session, tier, `compaction crashed: ${reason}`);
+        return {
+            committed: false,
+            tier,
+            newTranscript: input.transcript,
+            bytesReclaimed: 0,
+            newContextSize: byteSize(input.transcript),
+            violations: [],
+            skipped: true,
+            skipReason: `crashed: ${reason}`,
+        };
+    }
+    if (result.skipped) {
+        emitCompactionSkipped(input.session, tier, result.skipReason || 'no work');
+        return {
+            committed: false,
+            tier,
+            newTranscript: input.transcript,
+            bytesReclaimed: 0,
+            newContextSize: byteSize(input.transcript),
+            violations: [],
+            skipped: true,
+            skipReason: result.skipReason,
+        };
+    }
+    // Invariant gate: static-hash-unchanged is enforced by passing the
+    // same hashes in for `before` and `after` — compaction never touches
+    // static blocks, so the hashes are equal by construction. We pass
+    // both so the contract is explicit; if a future tier introduces a
+    // bug that overwrites static state, the check still catches it.
+    const violations = checkInvariants({
+        before: compactionInput,
+        after: result,
+        summaryText: result.summaryText,
+        staticHashBefore: input.contextStaticHash,
+        staticHashAfter: input.contextStaticHash,
+    });
+    if (violations.length > 0) {
+        for (const v of violations)
+            emitCompactionInvariantViolated(input.session, v);
+        return {
+            committed: false,
+            tier,
+            newTranscript: input.transcript,
+            bytesReclaimed: 0,
+            newContextSize: byteSize(input.transcript),
+            violations,
+            skipped: false,
+            skipReason: '',
+        };
+    }
+    emitCompactionCompleted(input.session, tier, result.bytesReclaimed, result.newContextSize, result.artifactsCreated);
+    return {
+        committed: true,
+        tier,
+        newTranscript: result.newTranscript,
+        bytesReclaimed: result.bytesReclaimed,
+        newContextSize: result.newContextSize,
+        violations: [],
+        skipped: false,
+        skipReason: '',
+    };
+}
+function byteSize(transcript) {
+    return transcript.reduce((sum, t) => sum + Buffer.byteLength(t.content, 'utf8'), 0);
+}
+//# sourceMappingURL=compaction-hook.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

package/dist/core/hooks/registry.js

@@ -0,0 +1,213 @@
+/**
+ * Pugi hooks MVP — registry (Leak L12, first pass).
+ *
+ * Reads `<home>/hooks-mvp.json` and validates its shape with Zod. The
+ * file uses the Claude Code-style nested config:
+ *
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [{ "command": "echo session-start" }],
+ *       "PreToolUse":   [{ "matcher": "bash", "command": "echo bash-pre", "blocking": true }]
+ *     }
+ *   }
+ *
+ * Schema constraints:
+ *   - Each hook entry MUST have a `command` (non-empty string).
+ *   - `matcher` is optional. Defaults to `*` (any tool / any payload).
+ *     For tool events, `matcher` is compared against the tool name.
+ *     For non-tool events (SessionStart), `matcher` is ignored.
+ *   - `timeoutMs` is optional. Defaults to 30 000 ms (per task spec).
+ *     Capped at 60 000 ms to prevent operator-defined deadlocks.
+ *   - `blocking` is optional. When true AND the hook exits non-zero,
+ *     the registry surfaces an `anyBlocked: true` outcome so the
+ *     caller can refuse the originating action. Only honoured for
+ *     `PreToolUse` in the MVP — other events log but do not block.
+ *
+ * Failure modes:
+ *   - File missing -> the registry is `empty()`. `list()` returns []
+ *     and `fire()` is a no-op. This matches the Claude Code default
+ *     (hooks are opt-in).
+ *   - File present but invalid JSON / fails schema -> `load()` throws.
+ *     The CLI surface (`pugi hooks doctor`) reports the error
+ *     verbatim so the operator can fix the config.
+ *
+ * Brand voice: ASCII only, no emoji, no em-dashes.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { ALL_HOOK_EVENTS_V2 } from './events.js';
+/** Default per-hook timeout when the operator does not set `timeoutMs`. */
+export const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
+/** Hard upper bound on `timeoutMs`. Prevents config-defined deadlocks. */
+export const MAX_HOOK_TIMEOUT_MS = 60_000;
+const hookEntrySchema = z
+    .object({
+    /**
+     * Tool-name matcher. `*` matches any tool. Plain strings match
+     * exactly (no glob in the MVP — fast-follow widens to glob). Ignored
+     * for non-tool events such as `SessionStart`.
+     */
+    matcher: z.string().min(1).optional(),
+    /** Shell command. Spawned via `/bin/sh -c <command>`. */
+    command: z.string().min(1),
+    /** Per-hook timeout override. Defaults to 30 000 ms. */
+    timeoutMs: z.number().int().positive().max(MAX_HOOK_TIMEOUT_MS).optional(),
+    /**
+     * When true, a non-zero exit code from this hook blocks the
+     * originating action (currently `PreToolUse` only). Other events
+     * log the exit but do not block.
+     */
+    blocking: z.boolean().optional(),
+})
+    .strict();
+const hookEventEnum = z.enum([
+    'SessionStart',
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'Stop',
+    'SubagentStop',
+    'PreCompact',
+    'Notification',
+]);
+const hooksFileSchema = z
+    .object({
+    hooks: z.record(hookEventEnum, z.array(hookEntrySchema)).default({}),
+})
+    .strict();
+/** Default config file location — `~/.pugi/hooks-mvp.json`. */
+export function defaultHooksMvpPath(home) {
+    const root = home ?? process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(root, 'hooks-mvp.json');
+}
+/**
+ * In-memory snapshot of the operator's `hooks-mvp.json`. Construct
+ * via `loadHooksConfig(path)` — `new HooksConfig()` is intentionally
+ * not exported so all production code paths go through the loader.
+ */
+export class HooksConfig {
+    path;
+    entries;
+    constructor(path, entries) {
+        this.path = path;
+        this.entries = entries;
+    }
+    /** Absolute path of the config file this snapshot was loaded from. */
+    configPath() {
+        return this.path;
+    }
+    /** All hooks declared for a given event. Returns [] when none. */
+    list(event) {
+        return this.entries[event] ?? [];
+    }
+    /**
+     * Hooks that match the (event, toolName?) tuple. For tool events
+     * (`PreToolUse`), `matcher` is compared against the tool name with
+     * `*` matching any. For non-tool events, all entries are returned
+     * regardless of `matcher`.
+     */
+    listMatching(event, toolName) {
+        const all = this.list(event);
+        if (!isToolEvent(event))
+            return all;
+        return all.filter((entry) => matchesTool(entry.matcher, toolName));
+    }
+    /** Flat list of (event, entry) pairs across every configured event. */
+    flatten() {
+        const out = [];
+        for (const event of ALL_HOOK_EVENTS_V2) {
+            for (const entry of this.list(event)) {
+                out.push({ event, entry });
+            }
+        }
+        return out;
+    }
+    /** True iff at least one hook is registered for any event. */
+    isEmpty() {
+        return this.flatten().length === 0;
+    }
+    /** A no-op snapshot used when the config file is absent. */
+    static empty(path) {
+        return new HooksConfig(path, {});
+    }
+}
+/**
+ * Load + validate `hooks-mvp.json`. Returns a no-op snapshot when the
+ * file is absent. Throws on invalid JSON or schema violations — the
+ * caller is expected to surface the error to the operator via
+ * `pugi hooks doctor`.
+ *
+ * Contract (non-null invariant): this function ALWAYS returns a
+ * `HooksConfig` instance. It never returns `null` / `undefined`. When
+ * the config file is missing, callers receive `HooksConfig.empty(path)`
+ * — a truthy snapshot for which `isEmpty()` returns `true` and `list()`
+ * returns `[]`. Callers may safely chain `.isEmpty()` without a null
+ * guard. Asserted by `registry-empty.spec.ts`.
+ */
+export function loadHooksConfig(pathOverride) {
+    const path = pathOverride ?? defaultHooksMvpPath();
+    if (!existsSync(path)) {
+        return HooksConfig.empty(path);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`pugi hooks: cannot read ${path}: ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`pugi hooks: ${path} is not valid JSON: ${error.message}`);
+    }
+    const result = hooksFileSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join('.') || '<root>'} ${issue.message}`)
+            .join('; ');
+        throw new Error(`pugi hooks: ${path} failed schema validation: ${issues}`);
+    }
+    // Zod's `z.record(enum, value)` returns `Partial<Record<...>>` shape
+    // — keys that the operator did not include are `undefined`. Coerce
+    // explicitly into the same shape `HooksConfig` expects.
+    const entries = {};
+    for (const event of ALL_HOOK_EVENTS_V2) {
+        const list = result.data.hooks[event];
+        if (list && list.length > 0) {
+            entries[event] = list;
+        }
+    }
+    return new HooksConfig(path, entries);
+}
+/**
+ * `isToolEvent(event)` -> true for events where `matcher` is compared
+ * against the tool name. SessionStart / Stop / Notification / etc. do
+ * not have an associated tool so matcher is ignored.
+ */
+export function isToolEvent(event) {
+    return event === 'PreToolUse' || event === 'PostToolUse';
+}
+/**
+ * Tool-name match grammar for the MVP. Intentionally narrow:
+ *   - matcher missing or `*` -> matches any tool name (and the
+ *     `bash`/`read`/... shape).
+ *   - matcher === toolName    -> exact match.
+ *
+ * Fast-follow widens this to glob via `picomatch` so operators can
+ * write `mcp__*` patterns. Deliberately not pulling in a glob lib for
+ * the MVP — the narrow grammar is enough to land the surface and the
+ * test matrix stays small.
+ */
+export function matchesTool(matcher, toolName) {
+    if (!matcher || matcher === '*')
+        return true;
+    if (!toolName)
+        return false;
+    return matcher === toolName;
+}
+//# sourceMappingURL=registry.js.map