@chances-ai/engine 24.0.0

package/dist/core/engine.js

@@ -0,0 +1,767 @@
+import { AppError, ErrorCode, ModelSelection, createId, runWithCwd, } from "@chances-ai/runtime";
+import { refreshActiveMarker } from "./worktree/index.js";
+import { classifyProviderError, defaultRetryConfig, estimateCost, } from "../ai/index.js";
+import { ASK_USER_QUESTION_TOOL_NAME, READONLY_CATEGORIES } from "../tools/index.js";
+/**
+ * (3.5 — codex Round-1 SHOULD-FIX #4) Anthropic-only overflow
+ * detection. Three patterns from pi's overflow catalogue
+ * (`pi/packages/ai/src/utils/overflow.ts:11`). The other 10
+ * providers we ship stay deferred until real-world telemetry shows
+ * a hit; their error shapes are less stable and a wrong regex would
+ * surface as silent overflow loops.
+ */
+function isAnthropicOverflowError(adapterId, message) {
+    if (adapterId !== "anthropic")
+        return false;
+    return (/prompt is too long/i.test(message) ||
+        /request_too_large/i.test(message) ||
+        /maximum.*context.*length/i.test(message));
+}
+/** Engine default when no caller-supplied or config-supplied value applies. */
+export const DEFAULT_MAX_TURNS = 12;
+/** Default base prompt the engine uses when no `systemBaseOverride` is set.
+ * Exported so tests can assert "is this the default or an agent override?" and
+ * so the doc + plugin authors can read the exact text. */
+export const DEFAULT_BASE_PROMPT = [
+    "You are chances, a terminal coding agent. Use the provided tools to inspect and modify the workspace. Be concise.",
+    "",
+    "Persistent memory:",
+    "- Use memory_save to remember facts that will still matter in *future* conversations: user role/preferences (type: user), corrections you should not need twice (type: feedback), ongoing project context not derivable from code (type: project), or pointers to external systems (type: reference).",
+    "- Use scope 'global' for cross-project facts about the user; use 'project' for this-repo context.",
+    "- Before saving, check the indexes below (or call memory_list) — if a related entry already exists, update it rather than creating a duplicate. Duplicates waste context budget.",
+    "- Use memory_delete to remove outdated entries.",
+    "- Do NOT save: code patterns, file paths, git history, debugging recipes, or task-specific scratch — those are derivable from the repo.",
+].join("\n");
+/**
+ * Mediator over ai/session/tools/memory. Depends only on interfaces (ports), so
+ * any ProviderAdapter or Tool plugs in unchanged. Communicates outward purely by
+ * emitting events on the bus — it never imports the TUI.
+ */
+export class AgentEngine {
+    opts;
+    selection;
+    constructor(opts) {
+        this.opts = opts;
+        // Prefer the caller-supplied selection so they retain a handle for
+        // mid-session mutation; fall back to the deprecated scalars for back-compat.
+        this.selection =
+            opts.selection ??
+                new ModelSelection({ provider: opts.preferredProvider, model: opts.preferredModel });
+    }
+    /**
+     * Exposes the mutable selection so callers — typically slash commands like
+     * `/model` — can update it between turns. Returning the live instance (not a
+     * copy) is intentional: writes must propagate back.
+     */
+    getSelection() {
+        return this.selection;
+    }
+    /** Bus-emit wrapper. Three responsibilities (3.4):
+     *  1. Suppress lifecycle frames (`turn:*`, `error`) when the engine is a
+     *     child (`suppressLifecycleEvents=true`). Codex Round-1 MUST-FIX #2.
+     *  2. Stamp `agentId/agentName` on tagged event variants when an
+     *     `agentContext` was supplied. Skipped silently when undefined.
+     *  3. Forward to `bus.emit` otherwise — fully transparent for parent engines.
+     */
+    emit(event) {
+        if (this.opts.suppressLifecycleEvents &&
+            (event.type === "turn:start" || event.type === "turn:end" || event.type === "error")) {
+            return;
+        }
+        const ctx = this.opts.agentContext;
+        if (ctx) {
+            switch (event.type) {
+                case "assistant:delta":
+                case "assistant:message":
+                case "assistant:reset":
+                case "tool:call":
+                case "tool:permission":
+                case "tool:result":
+                case "usage":
+                    // Conditional spread on agentId so sync subagents (which have
+                    // no registry-issued id — see `agentContext` doc above) emit
+                    // events without an `agentId: undefined` own-property. Cleaner
+                    // for subscribers like the 3.6 OTel exporter that introspect
+                    // keys to decide whether to stamp an attribute.
+                    this.opts.bus.emit({
+                        ...event,
+                        ...(ctx.agentId !== undefined ? { agentId: ctx.agentId } : {}),
+                        agentName: ctx.agentName,
+                    });
+                    return;
+                default:
+                    break;
+            }
+        }
+        this.opts.bus.emit(event);
+    }
+    async runTurn(prompt, token, opts = {}) {
+        // (4.1) Isolated subagents: every descendant `await` inside this
+        // turn sees `worktreeCwd` as its ambient cwd. Tools resolve
+        // `safePath` against it, bash spawns inside it. The outer body
+        // delegates straight into the existing implementation; nothing
+        // about the rest of `runTurn` needs to know about isolation
+        // beyond the `worktreeCwd` peek in `runTool`.
+        if (this.opts.worktreeCwd !== undefined) {
+            const cwd = this.opts.worktreeCwd;
+            void refreshActiveMarker(cwd).catch(() => {
+                /* heartbeat is best-effort; failure means the marker was
+                 * already removed (e.g. parent torn down the worktree) which
+                 * we surface through the regular tool-error path on the next
+                 * fs call. */
+            });
+            return runWithCwd(cwd, () => this.runTurnImpl(prompt, token, opts.expandMentions !== false));
+        }
+        return this.runTurnImpl(prompt, token, opts.expandMentions !== false);
+    }
+    async runTurnImpl(prompt, token, expandMentions) {
+        const { router, tools, gate, session, plugins, backgroundTasks } = this.opts;
+        const turnId = createId("turn");
+        // (3.6) Carry the active session id on `turn:start` so the OTel
+        // exporter can stamp `chances.gen_ai.session.id` correctly across
+        // `/resume` (which swaps SessionManager instances mid-process).
+        // Subscribers that don't care about session correlation ignore the
+        // field (it's optional in the event union).
+        this.emit({ type: "turn:start", turnId, prompt, sessionId: session.id });
+        await plugins?.runHook("beforePrompt", { prompt });
+        const toolDefs = tools.list().map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+        }));
+        const system = this.composeSystem();
+        // 3.4: peek pending background task notifications BEFORE composing the
+        // turn messages. Each notification becomes part of a single synthetic
+        // user-role message prepended to the user's actual prompt so the model
+        // sees them at the start of this turn. FIFO ordering. Notifications
+        // queued during this turn's stream go to the NEXT turn (deliberate:
+        // never inject mid-stream).
+        //
+        // Codex Round-2 MUST-FIX #3: we PEEK rather than DRAIN here. If the
+        // turn cancels / throws before `session.appendTurn` below, the queue
+        // is preserved and the next turn re-delivers — the model never sees
+        // the notification twice because the prior cancelled turn was not
+        // persisted to `session.messages()`. Acknowledgement (queue removal)
+        // happens immediately after `session.appendTurn(turnMessages)`
+        // succeeds.
+        const notifications = backgroundTasks?.peekPendingNotifications() ?? [];
+        const notificationIds = notifications.map((n) => n.taskId);
+        const turnMessages = [];
+        if (notifications.length > 0) {
+            const xml = notifications.map(renderTaskNotificationXml).join("\n");
+            turnMessages.push({
+                role: "user",
+                content: [{ type: "text", text: xml }],
+            });
+        }
+        // (5.4) Expand `@<server>:<uri>` mentions in directly-typed user input into
+        // a synthetic resource message before the prompt. Skipped for submitted /
+        // prompt-command text (`expandMentions === false`, codex R1 M3 — that text
+        // can be untrusted MCP-server output and must not drive ungated reads). The
+        // resolver only resolves exact cached resources (R1 S2) and never throws on
+        // a bad ref. Cancellation still propagates (it rethrows AppError(Cancelled)).
+        if (expandMentions && this.opts.resolveMcpMentions) {
+            const resolved = await this.opts.resolveMcpMentions(prompt, token.signal);
+            const xml = renderMcpResourcesXml(resolved);
+            if (xml)
+                turnMessages.push({ role: "user", content: [{ type: "text", text: xml }] });
+        }
+        turnMessages.push({ role: "user", content: [{ type: "text", text: prompt }] });
+        const result = { text: "", inputTokens: 0, outputTokens: 0, costUsd: 0 };
+        const maxTurns = this.opts.maxTurns ?? this.opts.maxIterations ?? DEFAULT_MAX_TURNS;
+        let resolved = false;
+        // (3.5 — codex Round-1 MUST-FIX #1) `result.inputTokens` aggregates
+        // every `usage` event across the multi-step tool loop. The compactor's
+        // threshold check needs the LAST stream's input only — that's what
+        // the provider will count for the NEXT request, plus the new user
+        // prompt. Tracked separately here; emitted via `usage:turn`.
+        let lastRequestInputTokens = 0;
+        // (3.5 — codex Round-1 SHOULD-FIX #4) Per-turn flag. Anthropic
+        // overflow recovery fires AT MOST ONCE per turn — a second 413 after
+        // we already compacted is an actual ceiling we can't paper over.
+        let recoveredFromOverflow = false;
+        // (3.5) Tracked at the outer scope so the post-turn compaction check
+        // can read `route.model`. The for-loop reuses the variable across
+        // iterations; we just need the most recent value to query the model
+        // descriptor for `contextWindow`.
+        let lastRoute;
+        for (let i = 0; i < maxTurns; i++) {
+            token.throwIfCancelled();
+            // Re-read selection per turn so a `/model` switch between turns lands on
+            // the next request without rebuilding the engine.
+            const choice = this.selection.get();
+            const route = router.pick({
+                preferredModel: choice.model,
+                preferredProvider: choice.provider,
+                needsTools: toolDefs.length > 0,
+            });
+            lastRoute = route;
+            const retry = this.opts.retry ?? defaultRetryConfig;
+            let textBuffer = "";
+            let calls = [];
+            let attempt = 0;
+            while (true) {
+                token.throwIfCancelled();
+                textBuffer = "";
+                calls = [];
+                // (3.5) Reset per attempt — only the LAST successful stream's
+                // last `usage.inputTokens` carries forward into the post-turn
+                // compactor check.
+                let attemptLastInputTokens = 0;
+                // (6.5b review) Stage usage in attempt-local accumulators instead of
+                // folding it straight into the turn-level `result`. A retryable
+                // mid-stream error (e.g. ECONNRESET after a partial stream) discards
+                // the attempt and restreams; folding here would double-count tokens
+                // and double-emit `usage`. We only merge into `result` + emit once
+                // the stream completes (`streamError === null`, below).
+                let attemptInputTokens = 0;
+                let attemptOutputTokens = 0;
+                let attemptCostUsd = 0;
+                let streamError = null;
+                const stream = route.adapter.stream({ model: route.model.id, system, messages: [...session.messages(), ...turnMessages], tools: toolDefs }, token.signal);
+                for await (const event of stream) {
+                    // Enforce cancellation per-event so a provider that ignores or
+                    // queues past the AbortSignal can't keep dripping text/tool-calls
+                    // into a turn the user already abandoned. Particularly important
+                    // for subagents: the parent's abort must stop the child instantly,
+                    // not wait until the child stream naturally ends.
+                    token.throwIfCancelled();
+                    switch (event.type) {
+                        case "text-delta":
+                            textBuffer += event.text;
+                            this.emit({ type: "assistant:delta", turnId, text: event.text });
+                            break;
+                        case "tool-call":
+                            // Defer the `tool:call` bus emit until the execution loop
+                            // below — pairs each emit atomically with its matching
+                            // `tool:result`. Emitting here would leave orphan call frames
+                            // on the bus whenever the turn aborts between stream-end and
+                            // tool execution (Ctrl-C) or a retry attempt discards the
+                            // collected calls and tries again on attempt N+1.
+                            calls.push(event.call);
+                            break;
+                        case "usage": {
+                            const costUsd = estimateCost(route.model, event.usage);
+                            // (6.5b review) Accumulate into attempt-local totals; the merge
+                            // into `result` + the `usage` emit happen once the stream
+                            // succeeds, so a discarded retry attempt can't double-count.
+                            attemptInputTokens += event.usage.inputTokens;
+                            attemptOutputTokens += event.usage.outputTokens;
+                            attemptCostUsd += costUsd;
+                            // (3.5) Track most recent stream's last input count for the
+                            // post-turn compaction threshold check. NOT the aggregate.
+                            attemptLastInputTokens = event.usage.inputTokens;
+                            break;
+                        }
+                        case "error":
+                            // Defer the bus emit until after cancellation check — if the
+                            // user just hit Ctrl-C, the SDK's abort path surfaces as a
+                            // stream error and we shouldn't shout "PROVIDER" at them.
+                            streamError = event.message;
+                            break;
+                        case "done":
+                            break;
+                    }
+                    if (streamError !== null)
+                        break;
+                }
+                if (streamError === null) {
+                    // Stream completed successfully — NOW fold this attempt's usage
+                    // into the turn-level `result` and emit the (aggregated) `usage`
+                    // frame. Deferred to here so a discarded retry attempt's partial
+                    // usage never double-counts (6.5b review).
+                    result.inputTokens += attemptInputTokens;
+                    result.outputTokens += attemptOutputTokens;
+                    result.costUsd += attemptCostUsd;
+                    if (attemptInputTokens > 0 || attemptOutputTokens > 0 || attemptCostUsd > 0) {
+                        this.emit({
+                            type: "usage",
+                            model: route.model.id,
+                            inputTokens: attemptInputTokens,
+                            outputTokens: attemptOutputTokens,
+                            costUsd: attemptCostUsd,
+                        });
+                    }
+                    // Persist this attempt's last input-token count for the post-turn
+                    // compaction check.
+                    lastRequestInputTokens = attemptLastInputTokens;
+                    break;
+                }
+                // If the abort signal fired during the stream, the error we just
+                // captured is the SDK reacting to the cancellation — treat it as
+                // Cancelled rather than misclassifying as a provider error.
+                token.throwIfCancelled();
+                const decision = classifyProviderError(streamError);
+                const terminal = !decision.retryable || attempt >= retry.delaysMs.length;
+                if (terminal) {
+                    // (3.5 — codex Round-1 SHOULD-FIX #4) Anthropic-only reactive
+                    // overflow recovery. Catches the 413 BEFORE the terminal throw,
+                    // runs compaction with `reason: "overflow"` (bypasses circuit
+                    // breaker), and retries the stream once with the compacted
+                    // history. Wider 10-provider catalogue stays deferred until
+                    // telemetry shows a real-world miss.
+                    if (this.opts.compactor &&
+                        !recoveredFromOverflow &&
+                        isAnthropicOverflowError(route.adapter.id, streamError)) {
+                        recoveredFromOverflow = true;
+                        try {
+                            const recovery = await this.opts.compactor.compact("overflow", token.signal);
+                            if (recovery.ok) {
+                                // Reset the attempt counter so we get the full retry
+                                // budget against the now-smaller request, AND clear the
+                                // accumulated message buffer that the failed attempt
+                                // wrote into `turnMessages`. The retry rebuilds from
+                                // `session.messages()` (which now reflects compaction)
+                                // plus this turn's prepended user/notification messages.
+                                // (6.5b follow-up) Mirror the normal retry path's partial-undo:
+                                // if this attempt streamed partial text before the overflow, drop
+                                // it so the post-compaction restream doesn't append onto a stale
+                                // partial. A 413 usually precedes any delta, so this is typically
+                                // a no-op — emitted only when text was actually shown.
+                                if (textBuffer.length > 0) {
+                                    this.emit({ type: "assistant:reset", turnId });
+                                }
+                                attempt = 0;
+                                continue;
+                            }
+                        }
+                        catch (e) {
+                            // Compactor.compact never throws by contract, but be defensive:
+                            // a malformed Compactor implementation shouldn't break the
+                            // original error path.
+                            this.emit({
+                                type: "log",
+                                level: "warn",
+                                message: `overflow compaction unexpectedly threw: ${e.message ?? e}`,
+                            });
+                        }
+                    }
+                    // Emit the bus `error` ONLY when we're about to throw. Emitting on
+                    // every retry attempt would cause `runPrompt`'s `lastError`
+                    // listener to record a transient failure as the turn's exit code
+                    // even after a later attempt succeeded (codex re-review finding).
+                    // Subagent engines suppress this emit — see `suppressTerminalErrors`.
+                    if (!this.opts.suppressTerminalErrors) {
+                        this.emit({ type: "error", code: "PROVIDER", message: streamError });
+                    }
+                    throw new AppError(ErrorCode.Provider, `Provider error (${decision.reason}): ${streamError}`);
+                }
+                const delayMs = retry.delaysMs[attempt] ?? 0;
+                this.emit({
+                    type: "log",
+                    level: "warn",
+                    message: `provider stream errored (${decision.reason}); retry ${attempt + 1}/${retry.delaysMs.length} after ${delayMs}ms; original: ${streamError}`,
+                });
+                // (6.5b review) If this attempt already streamed partial assistant text
+                // to the bus, the upcoming restream would APPEND a fresh copy on top
+                // (consumers don't replace) — duplicating it on screen. Tell consumers
+                // to drop the in-flight partial first. `usage`/`tool-call` are deferred
+                // (not yet on the bus), so only `textBuffer` needs undoing.
+                if (textBuffer.length > 0) {
+                    this.emit({ type: "assistant:reset", turnId });
+                }
+                attempt += 1;
+                await sleepCancellable(delayMs, token);
+            }
+            if (calls.length === 0) {
+                const content = [{ type: "text", text: textBuffer }];
+                turnMessages.push({ role: "assistant", content });
+                result.text = textBuffer;
+                this.emit({ type: "assistant:message", turnId, text: textBuffer });
+                await safeRunHook(plugins, "afterResponse", { text: textBuffer }, this.opts.bus);
+                resolved = true;
+                break;
+            }
+            // Record the assistant message that requested the tools.
+            const assistantContent = [];
+            if (textBuffer)
+                assistantContent.push({ type: "text", text: textBuffer });
+            for (const call of calls) {
+                assistantContent.push({ type: "tool-call", callId: call.callId, name: call.name, args: call.args });
+            }
+            turnMessages.push({ role: "assistant", content: assistantContent });
+            // Execute each tool through the permission gate, then feed results back.
+            for (const call of calls) {
+                // Check cancellation before each tool — a long batch of tool-calls
+                // from one model turn shouldn't keep running after the user aborts.
+                token.throwIfCancelled();
+                // Emit `tool:call` here (not in the stream loop) so each call is
+                // paired with its `tool:result` from runTool — keeps the bus
+                // observably balanced for subscribers (TUI, NDJSON, telemetry).
+                this.emit({ type: "tool:call", callId: call.callId, name: call.name, args: call.args });
+                const outcome = await this.runTool(call, token);
+                turnMessages.push({
+                    role: "tool",
+                    content: [{ type: "tool-result", callId: call.callId, name: call.name, output: outcome.output, ok: outcome.ok }],
+                });
+                // Round 3 codex SHOULD-FIX: check cancellation AFTER each tool
+                // result too. A tool that catches cancellation internally and
+                // returns `ok:false` (e.g. `bash` returning `(cancelled)`) does
+                // NOT re-throw, so without this check the loop would continue
+                // to the next turn and could exhaust `maxTurns`, surfacing as
+                // a misleading `PROVIDER: Reached maximum number of turns`
+                // instead of the user's actual `Cancelled` intent.
+                token.throwIfCancelled();
+            }
+        }
+        session.appendTurn(turnMessages);
+        // Codex Round-2 MUST-FIX #3: ack notifications AFTER appendTurn so a
+        // cancellation between peek and persist leaves the queue intact.
+        if (notificationIds.length > 0) {
+            backgroundTasks?.acknowledgeNotifications(notificationIds);
+        }
+        // (3.5) Per-turn aggregate event. Lifecycle suppression honored —
+        // child engines (with `suppressLifecycleEvents`) skip this too.
+        // `lastRequestInputTokens` feeds the post-turn compaction check
+        // (codex Round-1 MUST-FIX #1) AND 3.6 OTel one-span-per-turn.
+        if (!this.opts.suppressLifecycleEvents) {
+            this.opts.bus.emit({
+                type: "usage:turn",
+                turnId,
+                inputTokens: result.inputTokens,
+                outputTokens: result.outputTokens,
+                costUsd: result.costUsd,
+                lastRequestInputTokens,
+            });
+        }
+        // (3.5 — codex Round-1 MUST-FIX #4) Threshold-triggered compaction.
+        // Runs BEFORE `turn:end` so TUI subscribers don't see the turn as
+        // "over" while session is still mutating. Compaction emits its own
+        // `compaction:start` / `compaction:end` frames inside this await.
+        // The compactor itself swallows all failures into ok:false (never
+        // throws by contract); `Cancelled` propagates as `cancelled` reason.
+        if (this.opts.compactor && resolved && lastRoute) {
+            const should = this.opts.compactor.shouldCompact({
+                lastRequestInputTokens,
+                model: lastRoute.model,
+            });
+            if (should) {
+                await this.opts.compactor.compact("threshold", token.signal);
+                // (codex Round-2 MUST-FIX #2) The compactor swallows all
+                // failures into `ok:false`, including a `cancelled` reason
+                // when `signal.aborted` fired during summarization. Without
+                // a `throwIfCancelled` here the cancelled compaction would
+                // be invisible — the engine would emit `turn:end` and
+                // return normally, defeating the user's Ctrl-C. Re-checking
+                // the token after the await propagates Cancelled to the
+                // caller exactly like an in-stream cancellation would.
+                token.throwIfCancelled();
+            }
+            else {
+                // Reset the compactor's "compacted-recently" latch so the
+                // NEXT turn's threshold check can re-evaluate.
+                this.opts.compactor.noteNonCompactionTurn();
+            }
+        }
+        this.emit({ type: "turn:end", turnId });
+        if (!resolved) {
+            // Loop exhausted the turn budget without the model returning a final
+            // answer. Match claude-code's terminal-error pattern (`QueryEngine.ts:914`)
+            // — emit a bus error and throw so the caller sees a concrete signal
+            // instead of an empty result. The turn is still persisted above so
+            // `/resume` can pick up the partial work.
+            // Subagent engines suppress this emit — see `suppressTerminalErrors`.
+            const message = `Reached maximum number of turns (${maxTurns})`;
+            if (!this.opts.suppressTerminalErrors) {
+                this.emit({ type: "error", code: "PROVIDER", message });
+            }
+            throw new AppError(ErrorCode.Provider, message);
+        }
+        return result;
+    }
+    async runTool(call, token) {
+        const { bus, tools, gate, plugins, workspaceRoot } = this.opts;
+        const tool = tools.get(call.name);
+        if (!tool) {
+            const output = `Unknown tool: ${call.name}`;
+            this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: false, output });
+            return { ok: false, output };
+        }
+        // (4.1) Inside an isolated subagent's `runTurn`, `runWithCwd` has
+        // pushed `worktreeCwd` onto AsyncLocalStorage. Both `workspaceRoot`
+        // and `cwd` must flip together so `safePath` resolves against the
+        // worktree tree, not the parent's. When no override is active, the
+        // value is `undefined` and we fall back to the parent's
+        // `workspaceRoot` (unchanged 3.x behaviour).
+        //
+        // `parentWorkspaceRoot` (Round-2 SHOULD-FIX #4) carries the
+        // non-isolated workspace through so artifact persistence paths
+        // (`bash` oversized-output dump, etc.) land in the parent's
+        // `.chances/` rather than the worktree's — otherwise a
+        // clean-removed worktree would invalidate the path the tool just
+        // surfaced to the model.
+        const effectiveRoot = this.opts.worktreeCwd ?? workspaceRoot;
+        const ctx = {
+            workspaceRoot: effectiveRoot,
+            cwd: effectiveRoot,
+            signal: token.signal,
+            parentWorkspaceRoot: workspaceRoot,
+            lsp: this.opts.lsp, // (4.2) codex Round-1 MUST-FIX #1
+            callId: call.callId, // (5.7) artifact correlation — see ToolContext.callId
+        };
+        try {
+            await plugins?.runHook("beforeToolCall", { name: call.name, args: call.args });
+            // (5.3 codex Round-1 MUST-FIX #1) Session mode-block (plan's read-only
+            // floor) is enforced at the CATEGORY level here, BEFORE the per-op
+            // `permission()` hook. This is the only place that catches an op which
+            // returns `null` to bypass the gate (e.g. `pty.read`): without this,
+            // plan mode could be silently bypassed by such ops. Auto-approve /
+            // deny-floor / prompt all stay inside `gate.evaluate()` below.
+            const modeBlock = gate.blockByMode(tool.category);
+            if (modeBlock) {
+                this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: false, output: modeBlock.reason });
+                await safeRunHook(plugins, "afterToolCall", { name: call.name, ok: false, output: modeBlock.reason }, bus);
+                return { ok: false, output: modeBlock.reason };
+            }
+            // (5.1 codex Round-2 MUST-FIX #1) — per-op permission hook. When
+            // a tool implements `permission()`, it can:
+            //   - return `null` to bypass the gate entirely (e.g. `pty.read` /
+            //     `pty.resize` / `pty.list` — already approved at session
+            //     start),
+            //   - return a `PermissionRequest` whose `cacheKey` scopes the
+            //     positive-decision cache below `tool.name` (e.g.
+            //     `pty.kill.SIGTERM/<sid>` so approving SIGTERM doesn't
+            //     pre-approve SIGKILL).
+            // When unimplemented (the legacy path used by all 10 v5.0
+            // builtins), fall back to the original {name, category,
+            // summarize(args)} shape.
+            const decision = tool.permission ? tool.permission(call.args, ctx) : undefined;
+            if (decision === null) {
+                // Explicit bypass — skip the `tool:permission` event AND the
+                // gate. Subscribers (TUI, OTel) still see `tool:call` →
+                // `tool:result` for the op; only the permission frame is
+                // suppressed because there isn't one.
+                const outcome = await tool.execute(call.args, ctx);
+                this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: outcome.ok, output: outcome.output });
+                await safeRunHook(plugins, "afterToolCall", { name: call.name, ok: outcome.ok, output: outcome.output }, bus);
+                return outcome;
+            }
+            // (5.10b) QUESTION channel — fail-closed. A tool's `permission()` may emit
+            // a `question` request (the `ask_user_question` tool does), which skips
+            // `gate.evaluate()`'s allow/deny precedence. That bypass is safe ONLY for
+            // the dedicated read-only asker; any OTHER tool reaching here with a
+            // question request would be escaping authorization, so we refuse WITHOUT
+            // executing (codex R1 MUST-FIX #1). Double-guard: exact name + read-only
+            // category.
+            if (decision?.kind === "question") {
+                if (tool.name !== ASK_USER_QUESTION_TOOL_NAME || !READONLY_CATEGORIES.has(tool.category)) {
+                    const output = "refused: the question channel is reserved for the read-only ask tool";
+                    this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: false, output });
+                    await safeRunHook(plugins, "afterToolCall", { name: call.name, ok: false, output }, bus);
+                    return { ok: false, output };
+                }
+                this.emit({
+                    type: "tool:permission",
+                    callId: call.callId,
+                    name: call.name,
+                    summary: `${decision.questions.length} question(s)`,
+                });
+                // The answers come back through the resolver and ride into `execute` on
+                // the ctx (never serialized by the engine — the tool owns the wording).
+                const questionDecision = await gate.ask({ ...decision, callId: call.callId });
+                const outcome = await tool.execute(call.args, { ...ctx, questionDecision });
+                this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: outcome.ok, output: outcome.output });
+                await safeRunHook(plugins, "afterToolCall", { name: call.name, ok: outcome.ok, output: outcome.output }, bus);
+                return outcome;
+            }
+            const summary = decision?.summary ?? tool.summarize(call.args, ctx);
+            this.emit({ type: "tool:permission", callId: call.callId, name: call.name, summary });
+            // (5.2 codex Round-1 MUST-FIX #3) Stamp the call id onto the request
+            // so an out-of-process resolver (RPC / ACP host) can ship a
+            // self-contained `request_permission` frame the client joins to the
+            // preceding `tool_call.callId`. In-process resolvers ignore it.
+            const req = {
+                ...(decision ?? {
+                    name: tool.name,
+                    category: tool.category,
+                    summary,
+                    args: call.args,
+                }),
+                callId: call.callId,
+            };
+            // (5.3) `evaluate()` (not `check()`) so a denial can carry the user's
+            // deny-with-feedback text or a policy/mode reason into the tool result —
+            // the model then adapts instead of blindly retrying.
+            const evaluation = await gate.evaluate(req);
+            if (!evaluation.allow) {
+                const output = evaluation.feedback
+                    ? `Permission denied by user. User feedback: ${evaluation.feedback}`
+                    : (evaluation.reason ?? "Permission denied by policy/user");
+                this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: false, output });
+                await safeRunHook(plugins, "afterToolCall", { name: call.name, ok: false, output }, bus);
+                return { ok: false, output };
+            }
+            const outcome = await tool.execute(call.args, ctx);
+            this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: outcome.ok, output: outcome.output });
+            await safeRunHook(plugins, "afterToolCall", { name: call.name, ok: outcome.ok, output: outcome.output }, bus);
+            return outcome;
+        }
+        catch (e) {
+            // Cancellation must terminate the whole turn — never swallow it as a tool
+            // error. But we DO emit a synthetic `tool:result` so the bus stays paired
+            // (every `tool:call` event has its matching result, even on Ctrl-C).
+            if (e instanceof AppError && e.code === ErrorCode.Cancelled) {
+                this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: false, output: "Cancelled" });
+                throw e;
+            }
+            if (token.isCancelled) {
+                this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: false, output: "Cancelled" });
+                throw new AppError(ErrorCode.Cancelled, "Operation cancelled");
+            }
+            const output = formatToolError(e);
+            this.emit({ type: "tool:result", callId: call.callId, name: call.name, ok: false, output });
+            this.emit({ type: "log", level: "warn", message: `tool ${call.name} failed: ${output}` });
+            await safeRunHook(plugins, "afterToolCall", { name: call.name, ok: false, output }, bus);
+            return { ok: false, output };
+        }
+    }
+    composeSystem() {
+        const base = this.opts.systemBaseOverride ?? DEFAULT_BASE_PROMPT;
+        const memoryContext = this.opts.memory?.asSystemContext();
+        const isolation = this.opts.worktreeCwd ? ISOLATED_WORKTREE_NOTICE : undefined;
+        // (5.3) Plan mode is read-only — without this notice the model would keep
+        // attempting mutations and hitting denials. Read per-turn so toggling plan
+        // on/off (Shift+Tab) lands on the next turn, mirroring model selection.
+        const plan = this.opts.getApprovalMode?.() === "plan" ? PLAN_MODE_NOTICE : undefined;
+        const parts = [base];
+        if (memoryContext)
+            parts.push(memoryContext);
+        if (isolation)
+            parts.push(isolation);
+        if (plan)
+            parts.push(plan);
+        return parts.join("\n\n");
+    }
+}
+/** (5.3) Inserted into the system prompt while the session approval mode is
+ * `plan`. Tells the model it is read-only and should produce a plan instead of
+ * editing — the same posture claude-code's plan mode enforces. */
+export const PLAN_MODE_NOTICE = [
+    "Approval mode: PLAN (read-only).",
+    "- You may read files, search, and inspect, but file writes, shell commands, MCP tools, and network fetches are BLOCKED and will be denied.",
+    "- Do not attempt mutating tools. Investigate, then present a concise, actionable plan for the user to review.",
+    "- The user exits plan mode with Shift+Tab (or /approval) when ready to execute.",
+].join("\n");
+/** (4.1) Inserted at the END of the child engine's system prompt when
+ * `worktreeCwd` is set. Tells the model two load-bearing facts: the
+ * worktree starts from HEAD (parent's uncommitted state is invisible),
+ * and writes are sandboxed (parent sees them as a diff after the task
+ * completes, not live). Round-1 SHOULD-FIX #2 wording. */
+export const ISOLATED_WORKTREE_NOTICE = [
+    "Isolation: you are running in an isolated git worktree.",
+    "- This worktree starts from the parent agent's current HEAD; any uncommitted edits in the parent's working tree are NOT visible here.",
+    "- Files you write/edit/bash-modify here are sandboxed and not visible to the parent until your task completes; the parent will see your final diff once you return.",
+].join("\n");
+function formatToolError(e) {
+    if (e instanceof AppError)
+        return `${e.code}: ${e.message}`;
+    if (e instanceof Error)
+        return e.message || e.name || "Error";
+    return String(e);
+}
+/** Maximum bytes of `result` text included verbatim in an injected
+ * notification XML block. Beyond this, we truncate and tell the model the
+ * full result is still in the registry by id. Counted in UTF-16 code
+ * units rather than bytes — close enough for a 16 KiB-ish budget, and
+ * cheap to compute without a separate encoder pass. */
+const NOTIFICATION_RESULT_BUDGET = 16 * 1024;
+/** Control characters to strip from any text we inject. Keeps the XML
+ * payload terminal-safe and matches the C0+DEL strip used in
+ * `@chances-ai/agents`'s `renderCatalogForToolDescription`. */
+const NOTIFICATION_CONTROL_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+/** Renders one `<task-notification>` XML block, fully entity-escaped so
+ * `result`/`summary` text containing `<`, `>`, `&`, `"`, `'` can't break
+ * the surrounding tag structure or impersonate a different role.
+ *
+ * This is the format the model receives at the top of its next turn
+ * after a background subagent completes. The shape matches the one we
+ * (chances-cli's own host) observe receiving from background research
+ * subagents — claude-code's `<task_notification>` convention, with our
+ * hyphen-separated tag style.
+ */
+export function renderTaskNotificationXml(n) {
+    let result = n.result.replace(NOTIFICATION_CONTROL_RE, "");
+    let resultSuffix = "";
+    if (result.length > NOTIFICATION_RESULT_BUDGET) {
+        result = result.slice(0, NOTIFICATION_RESULT_BUDGET);
+        resultSuffix = `\n[…truncated, full result still in registry at task_id=${n.taskId}]`;
+    }
+    const summary = n.summary.replace(NOTIFICATION_CONTROL_RE, "");
+    return [
+        "<task-notification>",
+        `  <task-id>${xmlEscape(n.taskId)}</task-id>`,
+        `  <name>${xmlEscape(n.name)}</name>`,
+        `  <status>${xmlEscape(n.status)}</status>`,
+        `  <summary>${xmlEscape(summary)}</summary>`,
+        `  <result>${xmlEscape(result)}${xmlEscape(resultSuffix)}</result>`,
+        `  <duration-ms>${n.durationMs.toString()}</duration-ms>`,
+        "</task-notification>",
+    ].join("\n");
+}
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * (5.4) Build the synthetic resource message for `@<server>:<uri>` mentions.
+ * EVERY inserted field — server, uri, body, note — is XML-escaped (codex R1 M5:
+ * a malicious resource could otherwise close the tag and inject instructions),
+ * exactly like `renderTaskNotificationXml`. The resolver already stripped
+ * controls + redacted the body. Returns "" when nothing resolved (the caller
+ * skips the message entirely).
+ */
+export function renderMcpResourcesXml(resolved) {
+    if (resolved.length === 0)
+        return "";
+    const blocks = resolved.map((r) => {
+        const attrs = `server="${xmlEscape(r.server)}" uri="${xmlEscape(r.uri)}"`;
+        const body = r.text !== undefined ? xmlEscape(r.text) : `[${xmlEscape(r.note ?? "unavailable")}]`;
+        return `  <mcp-resource ${attrs}>\n${body}\n  </mcp-resource>`;
+    });
+    return ["<mcp-resources>", ...blocks, "</mcp-resources>"].join("\n");
+}
+async function sleepCancellable(ms, token) {
+    if (ms <= 0) {
+        token.throwIfCancelled();
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        let timer;
+        const abort = () => {
+            clearTimeout(timer);
+            token.signal.removeEventListener("abort", abort);
+            reject(new AppError(ErrorCode.Cancelled, "Operation cancelled"));
+        };
+        timer = setTimeout(() => {
+            token.signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        if (token.signal.aborted)
+            abort();
+        else
+            token.signal.addEventListener("abort", abort);
+    });
+}
+/**
+ * Runs a plugin hook without letting plugin bugs derail the agent. Failures are
+ * logged on the bus and swallowed — plugins must use their hook return semantics
+ * (e.g. throw from beforeToolCall) to block; once a tool has run, an afterHook
+ * crash should never undo it.
+ */
+async function safeRunHook(plugins, name, input, bus) {
+    if (!plugins)
+        return;
+    try {
+        await plugins.runHook(name, input);
+    }
+    catch (e) {
+        if (e instanceof AppError && e.code === ErrorCode.Cancelled)
+            throw e;
+        bus.emit({ type: "log", level: "warn", message: `plugin hook ${String(name)} threw: ${formatToolError(e)}` });
+    }
+}
+//# sourceMappingURL=engine.js.map