@pugi/cli 0.1.0-beta.11 → 0.1.0-beta.13

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

@@ -1,12 +1,22 @@
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { resolve } from 'node:path';
-import { runEngineLoop, } from '@pugi/sdk';
+import { AsyncEventQueue, EngineEventEmitter, modelSupportsThinking, runEngineLoop, splitThinkingBlocks, } from '@pugi/sdk';
 import { FileReadCache } from '../file-cache.js';
 import { loadSettings } from '../settings.js';
 import { openSession, recordToolCall, recordToolResult } from '../session.js';
+import { prewarmRealDispatch } from '../subagents/dispatcher.js';
 import { resolveBudget } from './budgets.js';
 import { buildExecutor, buildToolsSchema } from './tool-bridge.js';
 import { personaSlugFor, systemPromptFor } from './prompts.js';
+import { CancellationToken } from '../repl/cancellation.js';
+// β5a R5+R6 + P1 (2026-05-26): per-turn `<context>` prefix + intent
+// classifier marker. Both pure functions, no fs cost at adapter init.
+// Per-dir markdown traverse fires once per `run()`; budget capped so
+// it never dominates the prompt budget.
+import { buildContextPrefix, spliceContextPrefix } from './context-prefix.js';
+import { applyIntentMarker, classifyIntent } from './intent.js';
+import { loadTraversedMarkdown } from '../context/markdown-traverse.js';
 /**
  * Real `NativePugiEngineAdapter`. Drives the Pugi CLI's tool-use loop:
  *
@@ -51,8 +61,30 @@ export class NativePugiEngineAdapter {
      * to a single `run()` invocation.
      */
     engineToolCallIds = new Map();
+    /**
+     * β3 streaming additive: optional typed event emitter that mirrors
+     * every async-queue event so external consumers (admin-api SSE
+     * controller, future cabinet WebSocket relay) can attach without
+     * holding the async iterator. The CLI itself only consumes the
+     * `AsyncIterable<EngineEvent>` returned by `run()`; the emitter is
+     * a fan-out point for additional subscribers.
+     */
+    streamEmitter = new EngineEventEmitter();
     constructor(options) {
         this.options = options;
+        // β2a r1 (Backend Architect P1, 2026-05-26): kick off the real
+        // dispatcher's module import at adapter init so the first
+        // `agent` tool call does not pay 50-200ms cold-start. We fire
+        // the promise without awaiting — by the time the engine loop
+        // runs and the model issues an `agent` call, the import has
+        // resolved. The promise is swallowed because a failed prewarm
+        // would surface again at dispatch time with the real error.
+        void prewarmRealDispatch().catch(() => {
+            // Intentional no-op: the actual dispatch call will surface
+            // the import failure (if any) with the right call stack. A
+            // prewarm-time failure is just a missed optimization, not a
+            // correctness issue.
+        });
     }
     async capabilities() {
         return {
@@ -60,7 +92,13 @@ export class NativePugiEngineAdapter {
             supportsFileEdits: true,
             supportsShell: true,
             supportsLsp: false,
-            supportsSubagents: false,
+            // β2 S2 (2026-05-26): real subagent dispatch shipped via the
+            // `agent` tool (apps/pugi-cli/src/tools/agent-tool.ts) plus the
+            // genuine `runEngineLoop`-backed dispatcher
+            // (apps/pugi-cli/src/core/subagents/dispatcher-real.ts). The
+            // capability flag flips after S1 + S3 + S4 land so cabinet UI +
+            // remote orchestrators can rely on the advertised contract.
+            supportsSubagents: true,
         };
     }
     async *run(task, ctx) {
@@ -68,274 +106,634 @@ export class NativePugiEngineAdapter {
         const root = task.workspaceRoot;
         const session = this.options.session ?? openSession(root);
         const settings = loadSettings(root);
-        const toolCtx = {
-            root,
-            settings,
-            session,
-            readCache: new FileReadCache(),
-        };
-        // β1a r1 (budget wiring, 2026-05-26): swap the legacy SDK per-
-        // command budget lookup for the Pl9 `resolveBudget()` pipeline so
-        // `.pugi/settings.json::budgets.<command>` overrides actually take
-        // effect at runtime + the HARD_MAX_* caps guard misconfigured
-        // envelopes pre-flight. Before this fix the β1 Pl9 module
-        // (`core/engine/budgets.ts`) was dead code — the adapter still
-        // read the per-command defaults from the SDK, so operators who
-        // set `budgets.code.maxTokens = 50000` in settings.json got the
-        // legacy 30k anyway and `assertBudgetWithinTier` never ran.
+        // P1 fix (deep audit 2026-05-26): wire ctx.signal (AbortSignal) into
+        // a CancellationToken so the tool-bridge cancellation gate
+        // (`ctx.cancellation?.isAborted` check at tool-bridge.ts:656 +
+        // file-tools `gateOnCancellation` calls) fires when the operator
+        // aborts mid-tool. Before this fix `toolCtx` carried no cancellation
+        // field — only the next runEngineLoop iteration via `ctx.signal`
+        // aborted at the turn boundary, so a long-running tool (a sleeping
+        // bash command, a slow grep across the repo) could not be cancelled
+        // mid-call.
         //
-        // Task-level token override (e.g. CLI `--max-tokens`) keeps
-        // precedence; tool-call ceiling falls through to the resolved
-        // budget so a careless caller cannot disable the call-count
-        // guard by setting only token count.
-        const budget = resolveBudget(kind, settings, task.budget?.tokens ? { maxTokens: task.budget.tokens } : undefined);
-        yield {
-            type: 'status',
-            message: `Pugi engine starting: kind=${kind} budget=${budget.maxToolCalls} calls / ${budget.maxTokens} tokens`,
-        };
-        // Buffer status events emitted from inside the loop hooks. Async
-        // generators cannot yield from synchronous callbacks, so we collect
-        // them in a queue and drain after the loop call completes. The loop
-        // is short enough (≤ ~30 turns) that latency-to-stdout is acceptable
-        // — a follow-up PR can switch to an event emitter for true streaming.
-        const buffer = [];
-        // Track files mutated by the loop. We extract the path from the JSON
-        // arguments of every successful write/edit tool call; `bash` is left
-        // out because its filesystem footprint is opaque (a single command
-        // can touch dozens of paths via `make`, `pnpm build`, etc). The
-        // per-session events.jsonl already carries every file_mutation event
-        // for replay; this set is only the headline summary the CLI prints.
-        const filesChanged = new Set();
-        // Pending lookup: call.id → path extracted from arguments. We only
-        // commit to `filesChanged` when the corresponding onToolResult fires
-        // with `ok: true`, so a refused or failed edit does not surface as
-        // a phantom change in the operator summary.
-        const pendingMutations = new Map();
-        // Per-session events mirror — `.pugi/sessions/<id>/events.jsonl`.
-        // The existing global log at `.pugi/events.jsonl` is preserved as
-        // the audit-replay source of truth; this mirror is the easy-to-find
-        // per-run log for operators and the cabinet UI (Sprint 2B).
-        const sessionEventsPath = openSessionMirror(root, session.id);
-        const hooks = {
-            onTurnStart: (turnIndex, messageCount) => {
-                const msg = `turn ${turnIndex + 1}: requesting model (transcript=${messageCount} messages)`;
-                buffer.push({ type: 'status', message: msg });
-                appendSessionMirror(sessionEventsPath, { type: 'turn_start', turn: turnIndex + 1, transcript: messageCount });
-            },
-            onTurnComplete: (turnIndex, response) => {
-                if (response.stop === 'tool_use') {
-                    const calls = response.assistantMessage.toolCalls ?? [];
-                    buffer.push({
+        // The token is wired one-way: ctx.signal -> token. Aborting the
+        // token directly does NOT propagate back to the AbortSignal; the
+        // engine's own cancellation already lives upstream via the signal
+        // so the back-edge is unnecessary.
+        //
+        // r2 fix (triple-review 2026-05-26 P1): the abort listener was
+        // registered with `{ once: true }` — on actual abort it auto-detaches
+        // and disappears, but on the (common) NON-abort path where `run()`
+        // completes cleanly the listener stays attached to `ctx.signal`
+        // forever. Over a long REPL session (one shared AbortController per
+        // session, many run() invocations) listeners accumulate one per
+        // run, leaking memory and CPU on `dispatchEvent`. We now track the
+        // detach handle and call it unconditionally in the run()'s finally
+        // block so cleanup happens on both the success and abort paths.
+        const cancellation = new CancellationToken();
+        let detachAbortListener;
+        if (ctx.signal) {
+            if (ctx.signal.aborted) {
+                cancellation.abort();
+            }
+            else {
+                const handler = () => cancellation.abort();
+                ctx.signal.addEventListener('abort', handler, { once: true });
+                detachAbortListener = () => {
+                    ctx.signal.removeEventListener('abort', handler);
+                };
+            }
+        }
+        // r2 (triple-review 2026-05-26 P1): everything below runs inside a
+        // try/finally so the AbortSignal listener detaches on BOTH the
+        // success and abort paths. Without this wrap a long REPL session
+        // (one persistent AbortController, many run() invocations) leaked
+        // one abort listener per non-aborted run.
+        try {
+            const toolCtx = {
+                root,
+                settings,
+                session,
+                readCache: new FileReadCache(),
+                cancellation,
+            };
+            // β1a r1 (budget wiring, 2026-05-26): swap the legacy SDK per-
+            // command budget lookup for the Pl9 `resolveBudget()` pipeline so
+            // `.pugi/settings.json::budgets.<command>` overrides actually take
+            // effect at runtime + the HARD_MAX_* caps guard misconfigured
+            // envelopes pre-flight. Before this fix the β1 Pl9 module
+            // (`core/engine/budgets.ts`) was dead code — the adapter still
+            // read the per-command defaults from the SDK, so operators who
+            // set `budgets.code.maxTokens = 50000` in settings.json got the
+            // legacy 30k anyway and `assertBudgetWithinTier` never ran.
+            //
+            // Task-level token override (e.g. CLI `--max-tokens`) keeps
+            // precedence; tool-call ceiling falls through to the resolved
+            // budget so a careless caller cannot disable the call-count
+            // guard by setting only token count.
+            const budget = resolveBudget(kind, settings, task.budget?.tokens ? { maxTokens: task.budget.tokens } : undefined);
+            // β3 streaming: pre-build the typed stream event queue so the hook
+            // callbacks below can push live events that this async generator
+            // yields IMMEDIATELY (instead of buffering until `runEngineLoop`
+            // completes). Operator now sees the first `tool.start` within
+            // ~tens of ms of the model emitting it, not 30+ s after the loop
+            // settles.
+            const streamQueue = new AsyncEventQueue();
+            const emitter = this.streamEmitter;
+            const supportsThinking = modelSupportsThinking(this.options.model);
+            /**
+             * Push one typed stream event into BOTH the per-run async queue
+             * (the CLI's iterator) and the long-lived emitter (the multiplex
+             * fan-out for admin-api SSE / cabinet WebSocket subscribers).
+             * The function stamps `timestamp` once so both consumers see the
+             * same wall clock.
+             */
+            const emitStream = (event) => {
+                const stamped = {
+                    ...event,
+                    timestamp: new Date().toISOString(),
+                };
+                streamQueue.push(stamped);
+                emitter.emit('event', stamped);
+            };
+            // r1 fix per triple-review Backend Architect P1: unify yield path via
+            // emitStream + streamQueue drain so the iterator consumer does NOT
+            // see this status frame twice. Pre-fix did both bare yield + emitStream
+            // → iterator got 2 copies, emitter got 1.
+            emitStream({
+                type: 'status',
+                message: `Pugi engine starting: kind=${kind} budget=${budget.maxToolCalls} calls / ${budget.maxTokens} tokens`,
+            });
+            // β5a R1+R4+R5+R6+P1 (2026-05-26): build the per-turn `<context>`
+            // prefix and apply the intent marker so the model sees:
+            //   1. cwd + open-files + per-dir-conventions block (R5+R6)
+            //   2. a `<intent kind="definitional">` wrapper when the operator
+            //      asked a knowledge question (P1) — fixes the "What is grep?
+            //      → bash man grep" loss mode flagged by the α7.X eval.
+            //
+            // All caps enforced inside the builders (5 KB block + 50 entries
+            // + top-3 markdown). Worst-case prompt growth is ~5 KB, well
+            // inside any per-command token budget.
+            //
+            // cwd is sourced from `process.cwd()` — the operator's shell pwd
+            // when they invoked `pugi`. For non-REPL CLI paths this is
+            // accurate; the REPL session retains the launch cwd for the
+            // lifetime of the session which is what the operator expects.
+            const cwdForTraverse = process.cwd();
+            let traverseResult;
+            try {
+                traverseResult = await loadTraversedMarkdown({
+                    cwd: cwdForTraverse,
+                    workspaceRoot: root,
+                });
+            }
+            catch {
+                // Per-dir markdown is a NICE-TO-HAVE; a fs error here must
+                // never break the engine loop. Fall back to an empty result
+                // so the prefix block still surfaces cwd + working set.
+                traverseResult = { loaded: [], warnings: [], totalBytes: 0 };
+            }
+            const intentClassification = classifyIntent(task.prompt);
+            const intentHint = intentClassification.intent !== 'ambiguous' ? intentClassification.intent : undefined;
+            const cwdRelative = relativeOrAbsolute(root, cwdForTraverse);
+            const prefix = buildContextPrefix({
+                cwdRelative,
+                // β5a defers wiring the live WorkingSet snapshot to the REPL
+                // session integration (R5+R6 here only covers the engine-side
+                // builder). When the REPL passes its working set down, the
+                // engine surface fills in. For now the prefix carries cwd +
+                // per-dir conventions + intent which are the two biggest
+                // win-rate moves per the α7.X eval.
+                traversedMarkdown: traverseResult.loaded,
+                intentHint,
+            });
+            if (prefix.bytes > 0 || intentClassification.intent === 'definitional') {
+                emitStream({
+                    type: 'status',
+                    message: `context: cwd=${cwdRelative} per-dir-md=${prefix.counts.markdownIncluded}/${prefix.counts.markdownTotal} intent=${intentClassification.intent}`,
+                });
+            }
+            const decoratedPrompt = applyIntentMarker(task.prompt, intentClassification.intent);
+            const finalUserPrompt = spliceContextPrefix(prefix.block, decoratedPrompt);
+            // Track files mutated by the loop. We extract the path from the JSON
+            // arguments of every successful write/edit tool call; `bash` is left
+            // out because its filesystem footprint is opaque (a single command
+            // can touch dozens of paths via `make`, `pnpm build`, etc). The
+            // per-session events.jsonl already carries every file_mutation event
+            // for replay; this set is only the headline summary the CLI prints.
+            const filesChanged = new Set();
+            // Pending lookup: call.id → path extracted from arguments. We only
+            // commit to `filesChanged` when the corresponding onToolResult fires
+            // with `ok: true`, so a refused or failed edit does not surface as
+            // a phantom change in the operator summary.
+            const pendingMutations = new Map();
+            // Per-session events mirror — `.pugi/sessions/<id>/events.jsonl`.
+            // The existing global log at `.pugi/events.jsonl` is preserved as
+            // the audit-replay source of truth; this mirror is the easy-to-find
+            // per-run log for operators and the cabinet UI (Sprint 2B).
+            const sessionEventsPath = openSessionMirror(root, session.id);
+            const hooks = {
+                onTurnStart: (turnIndex, messageCount) => {
+                    const msg = `turn ${turnIndex + 1}: requesting model (transcript=${messageCount} messages)`;
+                    emitStream({ type: 'status', message: msg });
+                    appendSessionMirror(sessionEventsPath, { type: 'turn_start', turn: turnIndex + 1, transcript: messageCount });
+                },
+                onTurnComplete: (turnIndex, response) => {
+                    if (response.stop === 'tool_use') {
+                        const calls = response.assistantMessage.toolCalls ?? [];
+                        emitStream({
+                            type: 'status',
+                            message: `turn ${turnIndex + 1}: model requested ${calls.length} tool call(s)`,
+                        });
+                        appendSessionMirror(sessionEventsPath, {
+                            type: 'turn_complete',
+                            turn: turnIndex + 1,
+                            stop: 'tool_use',
+                            toolCalls: calls.length,
+                            tokensUsed: response.tokensUsed,
+                        });
+                    }
+                    else if (response.stop === 'text') {
+                        emitStream({
+                            type: 'status',
+                            message: `turn ${turnIndex + 1}: model returned final text (${response.content.length} chars)`,
+                        });
+                        appendSessionMirror(sessionEventsPath, {
+                            type: 'turn_complete',
+                            turn: turnIndex + 1,
+                            stop: 'text',
+                            contentLength: response.content.length,
+                            tokensUsed: response.tokensUsed,
+                        });
+                        // β3 E4 thinking-block surface: only Claude / Gemini families
+                        // advertise structured thinking today. The model resolver may
+                        // return a slug we don't recognise; in that case we skip the
+                        // split silently. When we DO recognise it, every `<thinking>`
+                        // / `<thought>` block becomes a separate `thinking.start`/
+                        // `thinking.delta`/`thinking.end` triplet so the TUI can
+                        // render one collapsed pane row per block. The visible text
+                        // (post-strip) flows to the regular `text.delta` channel so
+                        // the conversation pane never shows raw <thinking> markup.
+                        if (supportsThinking && response.content.length > 0) {
+                            const split = splitThinkingBlocks(response.content);
+                            for (const block of split.thinkingBlocks) {
+                                const blockId = `think-${randomUUID().slice(0, 8)}`;
+                                emitStream({ type: 'thinking.start', blockId });
+                                emitStream({ type: 'thinking.delta', blockId, chunk: block });
+                                emitStream({ type: 'thinking.end', blockId });
+                            }
+                            if (split.visibleText.length > 0) {
+                                emitStream({ type: 'text.delta', chunk: split.visibleText });
+                            }
+                        }
+                        else if (response.content.length > 0) {
+                            emitStream({ type: 'text.delta', chunk: response.content });
+                        }
+                    }
+                },
+                onToolCall: (call) => {
+                    // Record under an `engine_tool` prefix so the audit log can
+                    // distinguish loop-driven calls from direct CLI tool calls.
+                    const id = recordToolCall(session, `engine:${call.name}`, call.arguments.slice(0, 200));
+                    // Stash the audit id on the call for `onToolResult` to close.
+                    this.engineToolCallIds.set(call.id, id);
+                    // Extract a candidate path for write/edit so we can build the
+                    // filesChanged summary if (and only if) the call succeeds. Bad
+                    // JSON is harmless here — we ignore it and the executor surfaces
+                    // the actual parse error to the model.
+                    if (call.name === 'write' || call.name === 'edit') {
+                        const path = extractPathArg(call.arguments);
+                        if (path)
+                            pendingMutations.set(call.id, path);
+                    }
+                    emitStream({
+                        type: 'tool.start',
+                        callId: call.id,
+                        name: call.name,
+                        arguments: call.arguments,
+                    });
+                    emitStream({
                         type: 'status',
-                        message: `turn ${turnIndex + 1}: model requested ${calls.length} tool call(s)`,
+                        message: `tool_call: ${call.name}(${call.arguments.slice(0, 80)}${call.arguments.length > 80 ? '...' : ''})`,
                     });
                     appendSessionMirror(sessionEventsPath, {
-                        type: 'turn_complete',
-                        turn: turnIndex + 1,
-                        stop: 'tool_use',
-                        toolCalls: calls.length,
-                        tokensUsed: response.tokensUsed,
+                        type: 'tool_call',
+                        tool: call.name,
+                        callId: call.id,
+                        argsPreview: call.arguments.slice(0, 200),
                     });
-                }
-                else if (response.stop === 'text') {
-                    buffer.push({
+                },
+                onToolResult: (call, result) => {
+                    const auditId = this.engineToolCallIds.get(call.id);
+                    if (auditId) {
+                        if (result.ok) {
+                            recordToolResult(session, auditId, 'success', result.content.slice(0, 200));
+                        }
+                        else {
+                            recordToolResult(session, auditId, 'error', result.error.slice(0, 200));
+                        }
+                        this.engineToolCallIds.delete(call.id);
+                    }
+                    const pendingPath = pendingMutations.get(call.id);
+                    if (pendingPath) {
+                        if (result.ok)
+                            filesChanged.add(pendingPath);
+                        pendingMutations.delete(call.id);
+                    }
+                    emitStream({
+                        type: 'tool.end',
+                        callId: call.id,
+                        ok: result.ok,
+                        summary: result.ok
+                            ? result.content.slice(0, 200)
+                            : result.error.slice(0, 200),
+                    });
+                    emitStream({
                         type: 'status',
-                        message: `turn ${turnIndex + 1}: model returned final text (${response.content.length} chars)`,
+                        message: result.ok
+                            ? `tool_result: ${call.name} ok`
+                            : `tool_result: ${call.name} error: ${result.error.slice(0, 120)}`,
                     });
                     appendSessionMirror(sessionEventsPath, {
-                        type: 'turn_complete',
-                        turn: turnIndex + 1,
-                        stop: 'text',
-                        contentLength: response.content.length,
-                        tokensUsed: response.tokensUsed,
+                        type: 'tool_result',
+                        tool: call.name,
+                        callId: call.id,
+                        ok: result.ok,
+                        summary: result.ok ? result.content.slice(0, 200) : result.error.slice(0, 200),
+                    });
+                },
+            };
+            // β1b r1 (--allow-fetch / --allow-search wiring, 2026-05-26):
+            // compute the effective gate as OR of (a) the persisted
+            // settings.json opt-in and (b) the runtime CLI flag passed via
+            // the constructor. Before this fix the adapter only honored (a),
+            // so `pugi code --allow-fetch` against a default-privacy workspace
+            // silently fell back to "tool not advertised" even though the
+            // operator opted in for one invocation. The CLI flag was wired
+            // through to the legacy `pugi web` sub-command but not to the
+            // engine adapter — Backend Architect review (PR #425 r1) caught
+            // the gap.
+            const allowFetchEffective = this.options.allowFetch === true || settings.web?.fetch?.enabled === true;
+            const allowSearchEffective = this.options.allowSearch === true || settings.web?.search?.enabled === true;
+            // β2 S3 (2026-05-26) → β2a r1 (Backend Architect P1, 2026-05-26):
+            // expose the `agent` tool to the parent loop ONLY for non-plan
+            // commands. `buildToolsSchema` also strips the agent tool from
+            // plan-mode schemas, but a model that fabricates an `agent` call
+            // would still hit the executor with `agentDispatch` wired and
+            // could spawn a coder that mutates the workspace — breaking the
+            // plan-mode read-only contract. Hard-gate `allowAgent` on the
+            // command kind so plan mode never wires the dispatch block in
+            // the first place; tool-bridge.ts also throws ToolRefused on a
+            // fabricated `agent` call in plan mode as defense in depth.
+            //
+            // Why only the top-level parent and not children: the dispatcher-
+            // real.ts module builds the CHILD's executor without an
+            // `agentDispatch` block so children cannot recursively spawn
+            // grandchildren. The isolation-matrix capability set then refuses
+            // the `agent` tool for every non-orchestrator role anyway, but
+            // the executor-level gate is the load-bearing chokepoint.
+            const allowAgent = kind !== 'plan';
+            // β3 streaming: kick off `runEngineLoop` IN PARALLEL with the queue
+            // drain. The loop's hook callbacks push events onto `streamQueue`
+            // synchronously; this generator yields them live by awaiting the
+            // queue's iterator. When the loop settles (success or crash) we
+            // close the queue, which lets the iterator return cleanly and the
+            // generator falls through to the terminal `result` frame.
+            //
+            // Why concurrent instead of serial:
+            //
+            //   The β1 adapter awaited `runEngineLoop` to completion, then
+            //   drained an in-memory `EngineEvent[]` buffer. Operator saw
+            //   nothing for 30+ seconds (the full LLM round-trip + tool exec
+            //   wall time), then the entire log dumped at once. The TUI tool-
+            //   stream pane was a no-op because no event ever reached it
+            //   before the loop completed.
+            //
+            //   `Promise.race`-based interleaving lets us yield the next queue
+            //   event OR detect loop settlement on each tick. The settlement
+            //   flag (`loopSettled`) gates the final drain so we never miss
+            //   tail events that the hooks pushed in the same microtask as
+            //   the loop's terminal `return`.
+            // Boxed via single-element tuple so TypeScript does not narrow the
+            // outer `outcome` binding to `null` after the closure mutation.
+            // Async-closure mutations are invisible to TS control-flow analysis;
+            // wrapping in a tuple defeats the narrowing without an unsafe cast.
+            const outcomeBox = [null];
+            let loopError = null;
+            const loopPromise = (async () => {
+                try {
+                    outcomeBox[0] = await runEngineLoop({
+                        client: this.options.client,
+                        executor: buildExecutor({
+                            kind,
+                            ctx: toolCtx,
+                            sessionId: session.id,
+                            workspaceRoot: root,
+                            // P1 fix (deep audit 2026-05-26): forward optional REPL
+                            // ask-modal bridge. Default `interactive: false` preserves
+                            // backward compat — non-TTY callers (CI, pipes, scripted
+                            // CLI runs) keep the `[user_input_required]` envelope path.
+                            // The REPL layer passes `interactive: true` + a real
+                            // `askUserBridge` so model-initiated `ask_user_question`
+                            // calls round-trip to the ink modal and return the
+                            // operator's choice as a tool result.
+                            interactive: this.options.interactive === true,
+                            ...(this.options.askUserBridge
+                                ? { askUserBridge: this.options.askUserBridge }
+                                : {}),
+                            // P1 fix (deep audit 2026-05-26): forward the workspace
+                            // HookRegistry so `.pugi/hooks/` lifecycle hooks fire for
+                            // model-initiated tool calls. SECURITY: a `PreToolUse
+                            // onFailure: 'block'` hook that refuses bash containing
+                            // `rm` now applies to model dispatch — before this fix
+                            // such a hook only applied to direct CLI tool calls.
+                            ...(this.options.hooks ? { hooks: this.options.hooks } : {}),
+                            // β1a r1 (web_fetch gating) + β1b r1 (--allow-fetch wiring):
+                            // executor allowFetch matches the schema-advertise gate so a
+                            // settings.json opt-in OR a --allow-fetch flag enables the
+                            // call. Without this the model would not even see the
+                            // `web_fetch` tool. `allowSearch` covers the new T4
+                            // `web_search` tool with the same OR semantics.
+                            allowFetch: allowFetchEffective,
+                            allowSearch: allowSearchEffective,
+                            // β2 S3 → β2a r1 (2026-05-26): parent-level agentDispatch
+                            // wiring. When the model emits a `tool_call: agent(role,
+                            // brief)`, the executor forwards it to dispatcher-real.ts
+                            // which spawns a child engine loop against the same Anvil
+                            // client. Gated by `allowAgent` so plan mode does not even
+                            // wire the dispatch block — defense in depth on top of the
+                            // schema-filter and the tool-bridge plan-mode refusal.
+                            ...(allowAgent
+                                ? {
+                                    agentDispatch: {
+                                        parentSession: session,
+                                        engineClient: this.options.client,
+                                    },
+                                }
+                                : {}),
+                            // β4 M1/M3/M5: pass the loaded MCP registry through so the
+                            // executor can route `mcp__server__tool` calls + run the
+                            // first-call permission prompt before dispatching upstream.
+                            ...(this.options.mcpRegistry ? { mcpRegistry: this.options.mcpRegistry } : {}),
+                            ...(this.options.mcpPrompt ? { mcpPrompt: this.options.mcpPrompt } : {}),
+                        }),
+                        systemPrompt: 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
+                        // returned ambiguous (the splice + apply functions handle
+                        // that case as identity).
+                        userPrompt: finalUserPrompt,
+                        // β1a r1 (web_fetch gating) + β1b r1 (--allow-fetch wiring):
+                        // pass the OR of `.pugi/settings.json::web.fetch.enabled` and
+                        // the runtime `--allow-fetch` flag. When neither is true the
+                        // `web_fetch` tool is not advertised to the model at all.
+                        // `allowSearch` does the same for the new `web_search` tool.
+                        // β2 S3: allowAgent surfaces the `agent` tool in the schema
+                        // so the model sees it as a valid tool call option; the
+                        // capability-matrix layer (S4) still gates which roles can
+                        // actually USE it. Plan mode strips it via β2a r1 gate.
+                        tools: buildToolsSchema(kind, {
+                            allowFetch: allowFetchEffective,
+                            allowSearch: allowSearchEffective,
+                            allowAgent,
+                            // β4 M1/M3: same registry the executor saw. Schema +
+                            // dispatcher must agree on which MCP names are advertised
+                            // and which are dispatchable; passing identical references
+                            // makes that invariant impossible to break.
+                            ...(this.options.mcpRegistry ? { mcpRegistry: this.options.mcpRegistry } : {}),
+                        }),
+                        budget,
+                        personaSlug: personaSlugFor(kind),
+                        hooks,
+                        temperature: this.options.temperature ?? 0.2,
+                        signal: ctx.signal,
+                        // β1 (audit E2): forward CLI sub-command + α6.10 routing tag +
+                        // operator-pinned model so the runtime controller's DTO sees
+                        // all three. `tag` derives 1:1 from `command` for now
+                        // (`code → code`, `build → build_task`, etc.); future routing
+                        // changes flip the mapping table without touching the call
+                        // site. `model` is left undefined here — operator-pinned model
+                        // pinning ships in β6 with persona routing.
+                        command: kind,
+                        tag: dispatchTagFor(kind),
+                        model: this.options.model,
                     });
                 }
-            },
-            onToolCall: (call) => {
-                // Record under an `engine_tool` prefix so the audit log can
-                // distinguish loop-driven calls from direct CLI tool calls.
-                const id = recordToolCall(session, `engine:${call.name}`, call.arguments.slice(0, 200));
-                // Stash the audit id on the call for `onToolResult` to close.
-                this.engineToolCallIds.set(call.id, id);
-                // Extract a candidate path for write/edit so we can build the
-                // filesChanged summary if (and only if) the call succeeds. Bad
-                // JSON is harmless here — we ignore it and the executor surfaces
-                // the actual parse error to the model.
-                if (call.name === 'write' || call.name === 'edit') {
-                    const path = extractPathArg(call.arguments);
-                    if (path)
-                        pendingMutations.set(call.id, path);
-                }
-                buffer.push({
-                    type: 'status',
-                    message: `tool_call: ${call.name}(${call.arguments.slice(0, 80)}${call.arguments.length > 80 ? '...' : ''})`,
-                });
-                appendSessionMirror(sessionEventsPath, {
-                    type: 'tool_call',
-                    tool: call.name,
-                    callId: call.id,
-                    argsPreview: call.arguments.slice(0, 200),
-                });
-            },
-            onToolResult: (call, result) => {
-                const auditId = this.engineToolCallIds.get(call.id);
-                if (auditId) {
-                    if (result.ok) {
-                        recordToolResult(session, auditId, 'success', result.content.slice(0, 200));
-                    }
-                    else {
-                        recordToolResult(session, auditId, 'error', result.error.slice(0, 200));
-                    }
-                    this.engineToolCallIds.delete(call.id);
+                catch (err) {
+                    loopError = err;
                 }
-                const pendingPath = pendingMutations.get(call.id);
-                if (pendingPath) {
-                    if (result.ok)
-                        filesChanged.add(pendingPath);
-                    pendingMutations.delete(call.id);
+                finally {
+                    // Close the queue so the iterator below returns `done: true`.
+                    // Any tail events the hooks pushed in the same microtask still
+                    // drain because `AsyncEventQueue.close()` only resolves
+                    // PENDING awaiters — buffered items stay readable.
+                    streamQueue.close();
                 }
-                buffer.push({
-                    type: 'status',
-                    message: result.ok
-                        ? `tool_result: ${call.name} ok`
-                        : `tool_result: ${call.name} error: ${result.error.slice(0, 120)}`,
-                });
-                appendSessionMirror(sessionEventsPath, {
-                    type: 'tool_result',
-                    tool: call.name,
-                    callId: call.id,
-                    ok: result.ok,
-                    summary: result.ok ? result.content.slice(0, 200) : result.error.slice(0, 200),
-                });
-            },
-        };
-        let outcome;
-        try {
-            outcome = await runEngineLoop({
-                client: this.options.client,
-                executor: buildExecutor({
-                    kind,
-                    ctx: toolCtx,
-                    sessionId: session.id,
-                    workspaceRoot: root,
-                    // Conservatively false unless the caller explicitly opted in
-                    // via constructor. Interactive ask-modal bridge is wired by
-                    // the REPL layer in β2; for now non-TTY envelope is the path.
-                    interactive: false,
-                    // β1a r1 (web_fetch gating): executor allowFetch matches the
-                    // schema-advertise gate so a settings.json opt-in actually
-                    // enables the call. Without this the model would not even
-                    // see the `web_fetch` tool, but a `pugi web` CLI dispatch
-                    // through the executor would still be allowed because the
-                    // tool registry is independent.
-                    allowFetch: settings.web?.fetch?.enabled === true,
-                }),
-                systemPrompt: systemPromptFor(kind),
-                userPrompt: task.prompt,
-                // β1a r1 (web_fetch gating): pass the OR of
-                // `.pugi/settings.json::web.fetch.enabled` and the runtime
-                // `allowFetch` flag (today the adapter is conservative — see
-                // `buildExecutor` call below). When neither is true the
-                // `web_fetch` tool is not advertised to the model at all.
-                tools: buildToolsSchema(kind, {
-                    allowFetch: settings.web?.fetch?.enabled === true,
-                }),
-                budget,
-                personaSlug: personaSlugFor(kind),
-                hooks,
-                temperature: this.options.temperature ?? 0.2,
-                signal: ctx.signal,
-                // β1 (audit E2): forward CLI sub-command + α6.10 routing tag +
-                // operator-pinned model so the runtime controller's DTO sees
-                // all three. `tag` derives 1:1 from `command` for now
-                // (`code → code`, `build → build_task`, etc.); future routing
-                // changes flip the mapping table without touching the call
-                // site. `model` is left undefined here — operator-pinned model
-                // pinning ships in β6 with persona routing.
-                command: kind,
-                tag: dispatchTagFor(kind),
-                model: this.options.model,
+            })();
+            // Drain the queue live. Each iteration yields one EngineEvent the
+            // moment its hook fired. Operator sees `tool.start` within tens of
+            // ms of the model emitting it.
+            for await (const event of streamQueue) {
+                yield streamEventToEngineEvent(event);
+            }
+            // Loop has settled (queue closed). Surface its outcome — either an
+            // unhandled crash from the (rare) executor exception path or the
+            // structured EngineLoopOutcome.
+            await loopPromise;
+            if (loopError !== null) {
+                const message = loopError instanceof Error ? loopError.message : String(loopError);
+                yield {
+                    type: 'result',
+                    result: {
+                        status: 'failed',
+                        summary: `engine loop crashed: ${message}`,
+                        filesChanged: [],
+                        patchRefs: [],
+                        testsRun: [],
+                        risks: [`unhandled error in engine adapter: ${message}`],
+                        eventRefs: [],
+                    },
+                };
+                return;
+            }
+            const finalOutcome = outcomeBox[0];
+            if (finalOutcome === null) {
+                // Defensive — should never hit. `runEngineLoop` always either
+                // resolves with an outcome or throws (and we catch that above).
+                yield {
+                    type: 'result',
+                    result: {
+                        status: 'failed',
+                        summary: 'engine loop returned no outcome',
+                        filesChanged: [],
+                        patchRefs: [],
+                        testsRun: [],
+                        risks: ['runEngineLoop resolved without an outcome value'],
+                        eventRefs: [],
+                    },
+                };
+                return;
+            }
+            // Translate the loop outcome into an EngineResult.
+            // `aborted` (α6.9: operator cancelled mid-tool) maps to `blocked`
+            // because the operator chose the outcome, same shape as
+            // budget_exhausted / tool_refused.
+            const status = finalOutcome.status === 'completed'
+                ? 'done'
+                : finalOutcome.status === 'failed'
+                    ? 'failed'
+                    : 'blocked';
+            const summaryPrefix = finalOutcome.status === 'completed'
+                ? ''
+                : finalOutcome.status === 'budget_exhausted'
+                    ? '[budget_exhausted] '
+                    : finalOutcome.status === 'tool_refused'
+                        ? '[plan_mode_refused] '
+                        : finalOutcome.status === 'aborted'
+                            ? '[operator_aborted] '
+                            : '[failed] ';
+            const filesChangedList = Array.from(filesChanged).sort();
+            appendSessionMirror(sessionEventsPath, {
+                type: 'outcome',
+                status: finalOutcome.status,
+                toolCallCount: finalOutcome.toolCallCount,
+                turnsUsed: finalOutcome.turnsUsed,
+                tokensUsed: finalOutcome.tokensUsed,
+                filesChanged: filesChangedList,
+                reason: finalOutcome.reason,
             });
-        }
-        catch (error) {
-            // Defensive — runEngineLoop wraps errors into status: failed, so
-            // this branch is only hit if the executor or hooks themselves
-            // throw uncaught. Surface as a failed result so the CLI exits
-            // non-zero rather than hanging.
-            const message = error instanceof Error ? error.message : String(error);
             yield {
                 type: 'result',
                 result: {
-                    status: 'failed',
-                    summary: `engine loop crashed: ${message}`,
-                    filesChanged: [],
+                    status,
+                    summary: `${summaryPrefix}${finalOutcome.finalText || finalOutcome.reason || 'no answer returned'}`,
+                    filesChanged: filesChangedList,
                     patchRefs: [],
                     testsRun: [],
-                    risks: [`unhandled error in engine adapter: ${message}`],
-                    eventRefs: [],
+                    risks: finalOutcome.status === 'completed'
+                        ? []
+                        : [finalOutcome.reason ?? `outcome=${finalOutcome.status}`],
+                    eventRefs: [
+                        `tool_calls=${finalOutcome.toolCallCount}`,
+                        `turns=${finalOutcome.turnsUsed}`,
+                        `tokens=${finalOutcome.tokensUsed}`,
+                        // `outcome=<status>` is a machine-readable echo so callers
+                        // (cli.ts plan exit code, cabinet UI) can distinguish
+                        // `budget_exhausted` from `tool_refused` without parsing
+                        // the human-readable summary prefix. Code Reviewer P2
+                        // retro 2026-05-23: plan exit code previously collapsed
+                        // both blocked reasons into 0, which masked budget hits.
+                        `outcome=${finalOutcome.status}`,
+                        `session=${session.id}`,
+                        `ctx=${ctx.sessionId}`,
+                        `mirror=${sessionEventsPath}`,
+                    ],
                 },
             };
-            return;
         }
-        // Drain status buffer first so consumers see the chronological order.
-        for (const event of buffer)
-            yield event;
-        // Translate the loop outcome into an EngineResult.
-        // `aborted` (α6.9: operator cancelled mid-tool) maps to `blocked`
-        // because the operator chose the outcome, same shape as
-        // budget_exhausted / tool_refused.
-        const status = outcome.status === 'completed'
-            ? 'done'
-            : outcome.status === 'failed'
-                ? 'failed'
-                : 'blocked';
-        const summaryPrefix = outcome.status === 'completed'
-            ? ''
-            : outcome.status === 'budget_exhausted'
-                ? '[budget_exhausted] '
-                : outcome.status === 'tool_refused'
-                    ? '[plan_mode_refused] '
-                    : outcome.status === 'aborted'
-                        ? '[operator_aborted] '
-                        : '[failed] ';
-        const filesChangedList = Array.from(filesChanged).sort();
-        appendSessionMirror(sessionEventsPath, {
-            type: 'outcome',
-            status: outcome.status,
-            toolCallCount: outcome.toolCallCount,
-            turnsUsed: outcome.turnsUsed,
-            tokensUsed: outcome.tokensUsed,
-            filesChanged: filesChangedList,
-            reason: outcome.reason,
-        });
-        yield {
-            type: 'result',
-            result: {
-                status,
-                summary: `${summaryPrefix}${outcome.finalText || outcome.reason || 'no answer returned'}`,
-                filesChanged: filesChangedList,
-                patchRefs: [],
-                testsRun: [],
-                risks: outcome.status === 'completed'
-                    ? []
-                    : [outcome.reason ?? `outcome=${outcome.status}`],
-                eventRefs: [
-                    `tool_calls=${outcome.toolCallCount}`,
-                    `turns=${outcome.turnsUsed}`,
-                    `tokens=${outcome.tokensUsed}`,
-                    // `outcome=<status>` is a machine-readable echo so callers
-                    // (cli.ts plan exit code, cabinet UI) can distinguish
-                    // `budget_exhausted` from `tool_refused` without parsing
-                    // the human-readable summary prefix. Code Reviewer P2
-                    // retro 2026-05-23: plan exit code previously collapsed
-                    // both blocked reasons into 0, which masked budget hits.
-                    `outcome=${outcome.status}`,
-                    `session=${session.id}`,
-                    `ctx=${ctx.sessionId}`,
-                    `mirror=${sessionEventsPath}`,
-                ],
-            },
-        };
+        finally {
+            // r2 (triple-review 2026-05-26 P1): detach the abort listener so
+            // long REPL sessions sharing one AbortController across many
+            // run() invocations do not accumulate one listener per run on
+            // `ctx.signal`. Called on success, abort, and uncaught throw.
+            detachAbortListener?.();
+        }
+    }
+}
+/**
+ * β3 streaming: translate one typed `EngineStreamEvent` from the
+ * adapter's internal queue into the SDK's lossier `EngineEvent` shape
+ * the public adapter contract exposes. The SDK contract only declares
+ * `status | result` today; richer events (`tool.start`, `thinking.delta`,
+ * etc.) collapse to a structured `status` message until the SDK widens
+ * the discriminated union (β3b — paired with an admin-api SSE schema
+ * bump so the wire format stays stable).
+ *
+ * The full typed payload is still available to richer consumers via
+ * `adapter.streamEmitter.on('event', ...)`. The CLI's TUI tool-stream
+ * pane consumes that emitter directly; this function is the safe
+ * bridge for legacy SDK consumers that only know `EngineEvent`.
+ */
+function streamEventToEngineEvent(stream) {
+    switch (stream.type) {
+        case 'status':
+            return { type: 'status', message: stream.message };
+        case 'tool.start':
+            return {
+                type: 'status',
+                message: `tool.start ${stream.name} call=${stream.callId} args=${stream.arguments.slice(0, 80)}${stream.arguments.length > 80 ? '...' : ''}`,
+            };
+        case 'tool.delta':
+            return {
+                type: 'status',
+                message: `tool.delta call=${stream.callId} chunk=${stream.chunk.slice(0, 120)}`,
+            };
+        case 'tool.end':
+            return {
+                type: 'status',
+                message: `tool.end call=${stream.callId} ok=${stream.ok} summary=${stream.summary.slice(0, 120)}`,
+            };
+        case 'thinking.start':
+            return { type: 'status', message: `thinking.start block=${stream.blockId}` };
+        case 'thinking.delta':
+            return {
+                type: 'status',
+                message: `thinking.delta block=${stream.blockId} chunk=${stream.chunk.slice(0, 120)}`,
+            };
+        case 'thinking.end':
+            return { type: 'status', message: `thinking.end block=${stream.blockId}` };
+        case 'text.delta':
+            return {
+                type: 'status',
+                message: `text.delta chunk=${stream.chunk.slice(0, 200)}`,
+            };
+        default: {
+            // Exhaustiveness — TS catches a missing variant at compile time.
+            const exhaustive = stream;
+            void exhaustive;
+            return { type: 'status', message: 'unknown stream event' };
+        }
     }
 }
 /**
@@ -471,4 +869,20 @@ export function dispatchTagFor(kind) {
 // `NativePugiEngineAdapter` instance above — Code Reviewer P2 retro
 // 2026-05-23 lifted it off the module scope to prevent collisions
 // under parallel adapter runs (cabinet UI + CLI sharing one process).
+/**
+ * β5a R5+R6: render a cwd path as either a workspace-root-relative
+ * string (when cwd is inside the workspace) or a `.` token (when cwd
+ * equals workspaceRoot). Falls back to the absolute cwd if it lives
+ * outside the workspace — the traverse loader already refuses to
+ * read off-tree files so the abs path is purely a breadcrumb for
+ * the SSE status line.
+ */
+function relativeOrAbsolute(workspaceRoot, cwd) {
+    const absRoot = resolve(workspaceRoot);
+    const absCwd = resolve(cwd);
+    if (absCwd === absRoot)
+        return '.';
+    const rel = absCwd.startsWith(absRoot + '/') ? absCwd.slice(absRoot.length + 1) : null;
+    return rel ?? absCwd;
+}
 //# sourceMappingURL=native-pugi.js.map