@chances-ai/engine 27.0.0 → 29.0.0

package/dist/core/task-tool.js

@@ -15,6 +15,26 @@ export const TASK_TOOL_NAME = "task";
  * same well-known name. (7.5 §14.1) Exported so `buildEngine`'s isolated
  * per-session ToolRegistry can drop+re-register the stateful pty closure. */
 export const PTY_TOOL_NAME = "pty";
+/** (7.8 §3.2) The coordinator's orchestration tool names. `buildChildEngine`
+ * drops these from every child's tool surface (anti-recursion): a worker MUST
+ * NOT be able to spawn / message / stop workers — multi-level orchestration is a
+ * later EXTENSION, not v1 (north-star 3.5). Defined here (not in
+ * `coordinator-tools.ts`) so `buildChildEngine` can reference them without a
+ * cycle (coordinator-tools imports `createChildAgentRuntime` from this file). */
+export const SPAWN_WORKER_TOOL_NAME = "spawn_worker";
+export const SEND_MESSAGE_TOOL_NAME = "send_message";
+export const STOP_WORKER_TOOL_NAME = "stop_worker";
+export const DISMISS_WORKER_TOOL_NAME = "dismiss_worker";
+export const CREATE_TEAM_TOOL_NAME = "create_team";
+export const LIST_WORKERS_TOOL_NAME = "list_workers";
+export const COORDINATOR_TOOL_NAMES = new Set([
+    SPAWN_WORKER_TOOL_NAME,
+    SEND_MESSAGE_TOOL_NAME,
+    STOP_WORKER_TOOL_NAME,
+    DISMISS_WORKER_TOOL_NAME,
+    CREATE_TEAM_TOOL_NAME,
+    LIST_WORKERS_TOOL_NAME,
+]);
 /** Upper bound on the child's `maxTurns`. The parent's config-supplied value
  * is honored; this clamp only ensures a misconfigured 1 000-turn budget
  * doesn't let a single `task` invocation wedge the agent for hours. */
@@ -85,38 +105,311 @@ function strArg(args, key, required) {
     return v;
 }
 /**
- * Builds the `task` built-in: a model-callable tool that spins up a child
- * `AgentEngine` with its own ephemeral session, runs to completion, and
- * returns the child's final assistant text.
+ * (7.8 §3.2 / codex R1-§3 MUST) The SHARED child-agent build — persona
+ * resolution + tool filtering + cross-provider fork gate + worktree creation +
+ * per-subagent PTY registration + child `AgentEngine` construction. Extracted
+ * verbatim from `createTaskTool.execute` so the one-shot `task` AND the
+ * persistent `spawn_worker` build IDENTICALLY (no drift). The CALLER owns the
+ * run orchestration + WHEN to finalize: the one-shot finalizes the worktree +
+ * drains PTY right after its single run; a persistent worker defers both to
+ * terminal close (else the worktree would be torn out between messages).
  *
- * **Register per-engine, not at app boot.** This factory must be called
- * from inside `buildEngine` (per session), not once when the app starts.
- * Two reasons:
- *   1. The child engine consumes whatever tools are in the registry *at the
- *      moment the child runs* — MCP-bridged tools come and go between
- *      sessions, and the child should see the same surface the parent sees
- *      *now*, not the surface from boot.
- *   2. The closure captures the parent's `bus` / `gate` / `memory`
- *      references; rebuilds replace those references when the engine is
- *      re-created (e.g. on `/resume`). Boot-time registration would freeze
- *      stale dependencies and quietly drift across respawns.
- *
- * **Anti-recursion.** The child's tool registry excludes `task` itself —
- * a model that can call `task` recursively without depth limits will
- * fan out subagents until the process exhausts memory. v1 keeps the
- * blanket exclusion; v2+ may relax it with an explicit depth cap.
- *
- * **No `PluginHost` passthrough.** Plugins already observe the parent's
- * activity via bus events; running their hooks on every child turn would
- * either double-fire (afterToolCall for the same parent-level decision)
- * or silently confuse plugins that assume a single conversation lifecycle.
- * Revisit if a real need emerges.
- *
- * **Shared `EventBus`.** Child token usage, tool calls, assistant deltas
- * fire on the parent's bus. `chances stats` and the TUI therefore already
- * surface subagent cost without any new channels — the only signal that
- * an event came from a child is the surrounding tool-call frame.
+ * `agentIdMode` controls event-tagging identity (the one byte-level difference
+ * between callers, preserved exactly):
+ *   - `"none"`     → sync one-shot: `{agentName}` (no agentId; the parent labels
+ *                    sync children at the tool:call/result boundary).
+ *   - `"deferred"` → background one-shot: `{agentId:"", agentName}`; the caller
+ *                    sets `.agentId` to the registry task id after `launch()`.
+ *   - `{agentId}`  → persistent worker: tagged from birth.
+ */
+export async function buildChildEngine(deps, args, childMaxTurns, agentIdMode, creationSignal) {
+    const catalog = deps.agents;
+    const prompt = args.prompt;
+    const subagentType = args.subagentType;
+    let agent;
+    if (subagentType !== undefined && subagentType.length > 0) {
+        if (!catalog || catalog.size === 0) {
+            return {
+                ok: false,
+                output: `subagent_type '${subagentType}' was provided but no agent catalog is configured for this session.`,
+            };
+        }
+        agent = catalog.get(subagentType);
+        if (!agent) {
+            const available = [...catalog.keys()].sort().join(", ");
+            return { ok: false, output: `Unknown agent type '${subagentType}'. Available: ${available}` };
+        }
+    }
+    // Build the child registry from a single computed survivor list (drop `task`;
+    // intersect persona allow; subtract persona disallow — all fail-closed).
+    const parentNames = new Set();
+    const parentByName = new Map();
+    for (const t of deps.parentTools.list()) {
+        // Drop `task` (recursion) AND the coordinator orchestration tools — a child
+        // must not spawn/message/stop workers (anti-recursion, 7.8 §3.2).
+        if (t.name === TASK_TOOL_NAME || COORDINATOR_TOOL_NAMES.has(t.name))
+            continue;
+        parentNames.add(t.name);
+        parentByName.set(t.name, t);
+    }
+    if (agent) {
+        if (agent.tools !== "*") {
+            const unknown = agent.tools.filter((n) => !parentNames.has(n));
+            if (unknown.length > 0) {
+                const available = [...parentNames].sort().join(", ");
+                return {
+                    ok: false,
+                    output: `Agent '${agent.name}' references unknown tool(s) in 'tools': ${unknown.join(", ")}. Available tools: ${available}`,
+                };
+            }
+        }
+        const unknownDisallowed = agent.disallowedTools.filter((n) => !parentNames.has(n));
+        if (unknownDisallowed.length > 0) {
+            const available = [...parentNames].sort().join(", ");
+            return {
+                ok: false,
+                output: `Agent '${agent.name}' references unknown tool(s) in 'disallowedTools': ${unknownDisallowed.join(", ")}. Available tools: ${available}`,
+            };
+        }
+    }
+    const allowSet = agent && agent.tools !== "*" ? new Set(agent.tools) : parentNames;
+    const denySet = new Set(agent?.disallowedTools ?? []);
+    // Resolve effective isolation (input override > frontmatter > none).
+    const inputIsolation = args.isolation;
+    let isolationMode = "none";
+    if (inputIsolation !== undefined) {
+        if (inputIsolation !== "worktree" && inputIsolation !== "none") {
+            return {
+                ok: false,
+                output: `Invalid 'isolation' value '${inputIsolation}'. Expected 'worktree' or 'none'.`,
+            };
+        }
+        isolationMode = inputIsolation;
+    }
+    else if (agent?.isolation === "worktree") {
+        isolationMode = "worktree";
+    }
+    const childTools = new ToolRegistry();
+    const mcpFilterActive = isolationMode === "worktree" && !agent?.unsafeAllowMutatingMcp;
+    let mcpToolsFiltered = 0;
+    for (const t of parentByName.values()) {
+        if (!allowSet.has(t.name))
+            continue;
+        if (denySet.has(t.name))
+            continue;
+        if (t.name === PTY_TOOL_NAME)
+            continue;
+        if (mcpFilterActive && isMcpToolName(t.name) && !isReadOnlyMcpCategory(t.category)) {
+            mcpToolsFiltered++;
+            continue;
+        }
+        childTools.register(t);
+    }
+    // Resolve model override (persona model MUST resolve through the registry).
+    let childSelection;
+    if (agent?.model) {
+        if (!deps.registry) {
+            return {
+                ok: false,
+                output: `Agent '${agent.name}' specifies model '${agent.model}' but the task tool was wired without a ModelRegistry; cannot validate.`,
+            };
+        }
+        const resolved = deps.registry.get(agent.model);
+        if (!resolved) {
+            return {
+                ok: false,
+                output: `Agent '${agent.name}' specifies model '${agent.model}' which is not in the registry. Run 'chances doctor' to see configured providers and known models.`,
+            };
+        }
+        childSelection = new ModelSelection({ model: agent.model });
+    }
+    const childTurnsBudget = agent?.maxTurns
+        ? Math.min(Math.max(1, agent.maxTurns), CHILD_MAX_TURNS_CEILING)
+        : childMaxTurns;
+    // fork-from-parent resolution (BEFORE worktree, so a gate refusal returns
+    // cleanly with nothing to tear down).
+    const inputContext = args.context;
+    if (inputContext !== undefined && inputContext !== "fork" && inputContext !== "fresh") {
+        return {
+            ok: false,
+            output: `Invalid 'context' value '${inputContext}'. Expected 'fork' or 'fresh'.`,
+        };
+    }
+    const forkRequested = inputContext === "fork";
+    let effectiveSelection = childSelection;
+    let forkedChildSession;
+    let firstPrompt = prompt;
+    if (forkRequested) {
+        if (!deps.parentSession) {
+            return {
+                ok: false,
+                output: "context:'fork' was requested but the task tool was wired without a parent session; fork is unavailable. Use a fresh subagent with a self-contained prompt.",
+            };
+        }
+        const parentChoice = deps.parentSelection?.get() ?? {};
+        const parentModel = deps.router.pick({
+            preferredModel: parentChoice.model,
+            preferredProvider: parentChoice.provider,
+            needsTools: true,
+        }).model;
+        if (!effectiveSelection) {
+            effectiveSelection = new ModelSelection({
+                provider: parentChoice.provider,
+                model: parentChoice.model,
+            });
+        }
+        const childChoice = effectiveSelection.get();
+        const childModel = deps.router.pick({
+            preferredModel: childChoice.model,
+            preferredProvider: childChoice.provider,
+            needsTools: true,
+        }).model;
+        if (childModel.provider !== parentModel.provider && !deps.allowCrossProviderFork) {
+            return {
+                ok: false,
+                output: `context:'fork' would send the full conversation transcript to provider '${childModel.provider}' (model ${childModel.id}), which differs from this session's provider '${parentModel.provider}'. Set config.agent.allowCrossProviderFork=true to permit cross-provider forks, or drop the persona model override.`,
+            };
+        }
+        forkedChildSession = SessionManager.forkFrom(deps.parentSession, "subagent");
+        firstPrompt = buildForkDirective(prompt, isolationMode === "worktree");
+        const inheritedText = forkedChildSession.messages().map(messageToText).join("\n");
+        const toolDefsText = childTools
+            .list()
+            .map((t) => `${t.name}\n${t.description}\n${JSON.stringify(t.parameters)}`)
+            .join("\n");
+        const systemText = deps.memory?.asSystemContext() ?? "";
+        const estimate = estimateTokens(`${systemText}\n${toolDefsText}\n${inheritedText}\n${firstPrompt}`) +
+            SYSTEM_BASE_RESERVE_TOKENS;
+        const budget = deps.forkMaxContextTokens ??
+            (childModel.contextWindow
+                ? Math.floor(childModel.contextWindow * FORK_WINDOW_FRACTION)
+                : CONSERVATIVE_FORK_DEFAULT);
+        if (estimate > budget) {
+            return {
+                ok: false,
+                output: `Fork context (~${estimate} tokens, incl. tools + system) exceeds the budget (${budget} tokens) for model ${childModel.id}. Spawn a fresh subagent with an explicit prompt, /compact the conversation first, or raise config.agent.forkMaxContextTokens.`,
+            };
+        }
+    }
+    // Create the worktree (cancellation flows in via `creationSignal`).
+    let worktreeHandle;
+    if (isolationMode === "worktree") {
+        try {
+            worktreeHandle = await createAgentWorktree(deps.workspaceRoot, { signal: creationSignal });
+        }
+        catch (e) {
+            if (e instanceof WorktreeError) {
+                return {
+                    ok: false,
+                    output: `Isolation worktree could not be created (${e.code}): ${e.message}. Hint: ensure the workspace is a git repository and 'git' is on PATH.`,
+                };
+            }
+            throw e;
+        }
+    }
+    const worktreeCwd = worktreeHandle?.path;
+    const agentName = agent?.name ?? "default";
+    const agentContext = agentIdMode === "none"
+        ? { agentName }
+        : agentIdMode === "deferred"
+            ? { agentId: "", agentName }
+            : { agentId: agentIdMode.agentId, agentName };
+    // Per-subagent PTY instance scoped to a fresh agentId.
+    const childPtyAgentId = createId("sub");
+    if (deps.ptySessions && deps.nativeCreatePtySession) {
+        childTools.register(createPtyTool({
+            registry: deps.ptySessions,
+            agentId: childPtyAgentId,
+            agentName,
+            workspaceRoot: deps.workspaceRoot,
+            defaultCwd: worktreeCwd ?? deps.workspaceRoot,
+            worktreeCwd,
+            createHandle: deps.nativeCreatePtySession,
+        }));
+    }
+    const childSession = forkedChildSession ?? SessionManager.create("subagent");
+    const engine = new AgentEngine({
+        bus: deps.bus,
+        router: deps.router,
+        tools: childTools,
+        gate: deps.gate,
+        getApprovalMode: deps.getApprovalMode,
+        resolveMcpMentions: deps.resolveMcpMentions,
+        session: childSession,
+        memory: deps.memory,
+        workspaceRoot: deps.workspaceRoot,
+        maxTurns: childTurnsBudget,
+        // A subagent is non-interactive — a max-turns ceiling must FAIL (so the
+        // parent's task result surfaces it), not pause for a "continue?".
+        pauseOnMaxTurns: false,
+        suppressTerminalErrors: true,
+        suppressLifecycleEvents: true,
+        agentContext,
+        systemBaseOverride: agent?.systemPrompt,
+        selection: effectiveSelection,
+        worktreeCwd,
+    });
+    return {
+        ok: true,
+        engine,
+        agentName,
+        agentContext,
+        firstPrompt,
+        worktreeHandle,
+        childPtyAgentId,
+        mcpToolsFiltered,
+    };
+}
+/**
+ * (7.8 §3.2) Wrap a built child engine into a {@link ChildAgentRuntime} for the
+ * persistent-worker `WorkerRegistry` — `runMessage` runs one message against the
+ * persistent child session (context accumulates across messages), and
+ * `finalize`/`drainPty` defer the worktree retention + PTY drain to terminal
+ * close. Returns the fork-wrapped `firstPrompt` for the registry's first mailbox
+ * entry. The minted `agentId` tags the worker's events from birth.
  */
+export async function createChildAgentRuntime(deps, args, childMaxTurns, creationSignal) {
+    const agentId = createId("worker");
+    const built = await buildChildEngine(deps, args, childMaxTurns, { agentId }, creationSignal);
+    if (!built.ok)
+        return built;
+    const { engine, agentName, worktreeHandle, childPtyAgentId, mcpToolsFiltered } = built;
+    const drain = makeDrainChildPty(deps, childPtyAgentId);
+    const runtime = {
+        agentId,
+        agentName,
+        runMessage: async (prompt, signal) => {
+            const startedAt = Date.now();
+            try {
+                const result = await engine.runTurn(prompt, tokenFromSignal(signal), {
+                    expandMentions: false,
+                });
+                return {
+                    ok: true,
+                    text: result.text.trim() || "(worker finished without producing any text)",
+                    durationMs: Date.now() - startedAt,
+                    tokens: { input: result.inputTokens, output: result.outputTokens },
+                };
+            }
+            catch (e) {
+                if (signal.aborted || (e instanceof AppError && e.code === ErrorCode.Cancelled)) {
+                    return { ok: false, text: "Worker message cancelled", durationMs: Date.now() - startedAt };
+                }
+                const msg = e instanceof AppError
+                    ? `Worker failed (${e.code}): ${e.message}`
+                    : `Worker failed: ${e.message || String(e)}`;
+                return { ok: false, text: msg, durationMs: Date.now() - startedAt };
+            }
+        },
+        finalize: async () => {
+            // Probe + cleanup ONCE at terminal close. Returns the retention banner
+            // (or mcp-filter notice) to surface, or undefined when nothing was kept.
+            return finalizeWorktreeBanner(worktreeHandle, deps.workspaceRoot, mcpToolsFiltered);
+        },
+        drainPty: drain,
+    };
+    return { ok: true, runtime, firstPrompt: built.firstPrompt };
+}
 export function createTaskTool(deps) {
     const childMaxTurns = Math.min(Math.max(1, deps.maxTurns ?? DEFAULT_MAX_TURNS), CHILD_MAX_TURNS_CEILING);
     const baseDescription = "Delegate a self-contained sub-task to a child agent. By default the child starts with a FRESH, empty conversation (it sees only your `prompt`) — use this when a task benefits from a clean context: focused file exploration, isolated refactor planning, scoped research. Set `context: \"fork\"` to instead give the child a copy of THIS conversation's completed history (everything you've already read/run), for \"continue this exact line of work\" tasks. The child has access to the same tools as you (except `task` itself — no recursion) and shares your permission gate, so session approvals carry through. The child runs to completion and returns its final assistant text as a single payload. Token usage / cost flow back to this session's telemetry.";
@@ -224,362 +517,47 @@ export function createTaskTool(deps) {
         },
         async execute(args, ctx) {
             const prompt = strArg(args, "prompt", true);
-            const subagentType = strArg(args, "subagent_type", false);
-            let agent;
-            if (subagentType !== undefined && subagentType.length > 0) {
-                if (!catalog || catalog.size === 0) {
-                    return {
-                        ok: false,
-                        output: `subagent_type '${subagentType}' was provided but no agent catalog is configured for this session.`,
-                    };
-                }
-                agent = catalog.get(subagentType);
-                if (!agent) {
-                    const available = [...catalog.keys()].sort().join(", ");
-                    return {
-                        ok: false,
-                        output: `Unknown agent type '${subagentType}'. Available: ${available}`,
-                    };
-                }
-            }
-            // Build the child registry from a single computed survivor list.
-            // 1. Snapshot parent → drop `task` (recursion still blocked in 3.3).
-            // 2. If persona has explicit `tools`, intersect (fail-closed on
-            //    unknown names — codex Round-1 #5).
-            // 3. If persona has `disallowedTools`, subtract (same fail-closed
-            //    semantics; unknown disallow name → ok:false rather than
-            //    leaving the real tool reachable).
-            // 4. Construct one ToolRegistry from the final list. ToolRegistry's
-            //    v1 surface only exposes `register` + `list`, so we never
-            //    register-then-remove — we compute survivors first, then build.
-            const parentNames = new Set();
-            const parentByName = new Map();
-            for (const t of deps.parentTools.list()) {
-                if (t.name === TASK_TOOL_NAME)
-                    continue;
-                parentNames.add(t.name);
-                parentByName.set(t.name, t);
-            }
-            if (agent) {
-                if (agent.tools !== "*") {
-                    const unknown = agent.tools.filter((n) => !parentNames.has(n));
-                    if (unknown.length > 0) {
-                        const available = [...parentNames].sort().join(", ");
-                        return {
-                            ok: false,
-                            output: `Agent '${agent.name}' references unknown tool(s) in 'tools': ${unknown.join(", ")}. Available tools: ${available}`,
-                        };
-                    }
-                }
-                const unknownDisallowed = agent.disallowedTools.filter((n) => !parentNames.has(n));
-                if (unknownDisallowed.length > 0) {
-                    const available = [...parentNames].sort().join(", ");
-                    return {
-                        ok: false,
-                        output: `Agent '${agent.name}' references unknown tool(s) in 'disallowedTools': ${unknownDisallowed.join(", ")}. Available tools: ${available}`,
-                    };
-                }
-            }
-            const allowSet = agent && agent.tools !== "*"
-                ? new Set(agent.tools)
-                : parentNames; // `*` or no agent → full surface (minus `task`)
-            const denySet = new Set(agent?.disallowedTools ?? []);
-            // (4.1) Resolve effective isolation mode. Order:
-            //   1) `task` tool input `isolation` (model-callable override)
-            //   2) agent-catalog frontmatter `isolation`
-            //   3) default 'none'
-            // The schema enum makes this self-documenting; we still validate
-            // the value defensively because `JSONValue` is permissive.
-            const inputIsolation = strArg(args, "isolation", false);
-            let isolationMode = "none";
-            if (inputIsolation !== undefined) {
-                if (inputIsolation !== "worktree" && inputIsolation !== "none") {
-                    return {
-                        ok: false,
-                        output: `Invalid 'isolation' value '${inputIsolation}'. Expected 'worktree' or 'none'.`,
-                    };
-                }
-                isolationMode = inputIsolation;
-            }
-            else if (agent?.isolation === "worktree") {
-                isolationMode = "worktree";
-            }
-            const childTools = new ToolRegistry();
-            const mcpFilterActive = isolationMode === "worktree" && !agent?.unsafeAllowMutatingMcp;
-            let mcpToolsFiltered = 0;
-            for (const t of parentByName.values()) {
-                if (!allowSet.has(t.name))
-                    continue;
-                if (denySet.has(t.name))
-                    continue;
-                // (5.1) Parent's `pty` instance is closed over the parent's
-                // agentId — registering it as-is for the child would create
-                // child sessions in the parent's ownership bucket, defeating
-                // D10 symmetric isolation and the `drainOwnedBy(childAgentId)`
-                // contract. Skip here and re-register with the child's id below.
-                if (t.name === PTY_TOOL_NAME)
-                    continue;
-                // (4.1 — Round-1 MUST-FIX #2) MCP tools run in their own
-                // process; the worktree's cwd does NOT confine their writes.
-                // Inside an isolated subagent, filter MCP-source tools (named
-                // `mcp__<server>__<tool>`) to those whose declared category is
-                // in the read-only set. Unannotated tools default to
-                // `integration` which we treat as potentially mutating.
-                // Opt-out via frontmatter `unsafeAllowMutatingMcp: true`.
-                if (mcpFilterActive && isMcpToolName(t.name) && !isReadOnlyMcpCategory(t.category)) {
-                    mcpToolsFiltered++;
-                    continue;
-                }
-                childTools.register(t);
-            }
-            // Resolve model override. `agent.model` MUST resolve through the
-            // registry; misses fail closed (codex Round-1 #4).
-            let childSelection;
-            if (agent?.model) {
-                if (!deps.registry) {
-                    return {
-                        ok: false,
-                        output: `Agent '${agent.name}' specifies model '${agent.model}' but the task tool was wired without a ModelRegistry; cannot validate.`,
-                    };
-                }
-                const resolved = deps.registry.get(agent.model);
-                if (!resolved) {
-                    return {
-                        ok: false,
-                        output: `Agent '${agent.name}' specifies model '${agent.model}' which is not in the registry. Run 'chances doctor' to see configured providers and known models.`,
-                    };
-                }
-                childSelection = new ModelSelection({ model: agent.model });
-            }
-            const childTurnsBudget = agent?.maxTurns
-                ? Math.min(Math.max(1, agent.maxTurns), CHILD_MAX_TURNS_CEILING)
-                : childMaxTurns;
-            // (5.5) fork-from-parent resolution. Runs BEFORE any worktree is created
-            // so a gate refusal returns cleanly with nothing to tear down. All the
-            // fork-only state (the deep-cloned child session + the model selection
-            // the child runs under) is computed once here, at execute time, so the
-            // background path's deferred `run()` closure forks the parent at SPAWN
-            // time, not at run time (D7).
-            const inputContext = strArg(args, "context", false);
-            if (inputContext !== undefined && inputContext !== "fork" && inputContext !== "fresh") {
-                return {
-                    ok: false,
-                    output: `Invalid 'context' value '${inputContext}'. Expected 'fork' or 'fresh'.`,
-                };
-            }
-            const forkRequested = inputContext === "fork";
-            // `effectiveSelection` is what the child engine runs under: a persona
-            // `model` override always wins; a fork with no override inherits the
-            // parent's CURRENT selection (pinned now); a fresh subagent keeps today's
-            // behaviour (undefined ⇒ engine default).
-            let effectiveSelection = childSelection;
-            let forkedChildSession;
-            // (D6) The prompt the child actually receives. For a fork it is wrapped
-            // with the directive (built here so the budget estimate counts it too —
-            // it depends only on `isolationMode`, not the not-yet-created worktree);
-            // a fresh subagent passes the prompt as-is.
-            let childPrompt = prompt;
-            if (forkRequested) {
-                if (!deps.parentSession) {
-                    return {
-                        ok: false,
-                        output: "context:'fork' was requested but the task tool was wired without a parent session; fork is unavailable. Use a fresh subagent with a self-contained prompt.",
-                    };
-                }
-                // Resolve effective parent + child model descriptors through the router
-                // (same fallback the engine uses), so the budget + cross-provider gate
-                // see the model the child will actually run on.
-                const parentChoice = deps.parentSelection?.get() ?? {};
-                const parentModel = deps.router.pick({
-                    preferredModel: parentChoice.model,
-                    preferredProvider: parentChoice.provider,
-                    needsTools: true,
-                }).model;
-                if (!effectiveSelection) {
-                    // No persona override: inherit the parent's current model, pinned at
-                    // execute time so a later `/model` switch (or background defer) can't
-                    // move the child off the model the user forked on.
-                    effectiveSelection = new ModelSelection({
-                        provider: parentChoice.provider,
-                        model: parentChoice.model,
-                    });
-                }
-                const childChoice = effectiveSelection.get();
-                const childModel = deps.router.pick({
-                    preferredModel: childChoice.model,
-                    preferredProvider: childChoice.provider,
-                    needsTools: true,
-                }).model;
-                // (D11) Cross-provider transcript-disclosure gate (fail-closed; not
-                // bypassable by auto-approve modes since it refuses before the gate).
-                if (childModel.provider !== parentModel.provider && !deps.allowCrossProviderFork) {
-                    return {
-                        ok: false,
-                        output: `context:'fork' would send the full conversation transcript to provider '${childModel.provider}' (model ${childModel.id}), which differs from this session's provider '${parentModel.provider}'. Set config.agent.allowCrossProviderFork=true to permit cross-provider forks, or drop the persona model override.`,
-                    };
-                }
-                // (D5 / R2 MUST-FIX) Model-aware budget. Fork the parent ONCE here (used
-                // for both the estimate and as the child's seeded session) and build the
-                // directive now so the estimate covers the SAME shape the child engine
-                // will send (`engine.ts` runTurnImpl: system + tool schemas + inherited
-                // messages + the directive-wrapped user turn) — not just the inherited
-                // history. Under-counting the tool schemas / directive would let a fork
-                // pass this guard and still overflow the model's window on its first
-                // request, which is exactly what this preflight exists to prevent.
-                forkedChildSession = SessionManager.forkFrom(deps.parentSession, "subagent");
-                childPrompt = buildForkDirective(prompt, isolationMode === "worktree");
-                const inheritedText = forkedChildSession.messages().map(messageToText).join("\n");
-                // `childTools` is fully populated here except the per-agent `pty`
-                // instance (registered in each branch below) — a one-tool undercount
-                // the window fraction + base reserve absorb. Memory context is the
-                // other model-visible system addition we can size cheaply; plan/worktree
-                // reminders + the base prompt are covered by SYSTEM_BASE_RESERVE_TOKENS.
-                const toolDefsText = childTools
-                    .list()
-                    .map((t) => `${t.name}\n${t.description}\n${JSON.stringify(t.parameters)}`)
-                    .join("\n");
-                const systemText = deps.memory?.asSystemContext() ?? "";
-                const estimate = estimateTokens(`${systemText}\n${toolDefsText}\n${inheritedText}\n${childPrompt}`) +
-                    SYSTEM_BASE_RESERVE_TOKENS;
-                const budget = deps.forkMaxContextTokens ??
-                    (childModel.contextWindow
-                        ? Math.floor(childModel.contextWindow * FORK_WINDOW_FRACTION)
-                        : CONSERVATIVE_FORK_DEFAULT);
-                if (estimate > budget) {
-                    return {
-                        ok: false,
-                        output: `Fork context (~${estimate} tokens, incl. tools + system) exceeds the budget (${budget} tokens) for model ${childModel.id}. Spawn a fresh subagent with an explicit prompt, /compact the conversation first, or raise config.agent.forkMaxContextTokens.`,
-                    };
-                }
-            }
-            // (5.1) Drain helper: called on every subagent termination
-            // path (sync return / sync throw / background return). The
-            // registry only kills sessions still owned by `childAgentId`
-            // — sessions the parent has `pty.adopt()`-ed are re-bound to
-            // the parent's agentId and are no-ops here. Failure to drain
-            // is logged once on the bus but never blocks the caller; a
-            // 2-second deadline matches `AsyncTaskRegistry.killAll` from
-            // 3.4 so engine teardown shape is uniform.
-            const drainChildPty = async (childAgentId) => {
-                if (!deps.ptySessions)
-                    return;
-                try {
-                    // (5.1 codex Round-2 SHOULD-FIX #1) Capture survivors and
-                    // surface them on the bus so operators see when a subagent
-                    // PTY ignored TERM-then-KILL past the 2 s deadline. Matches
-                    // the CLI shutdown's `pty dispose` survivor log so the two
-                    // teardown paths report the same shape.
-                    const { survivors } = await deps.ptySessions.drainOwnedBy(childAgentId, 2_000);
-                    if (survivors.length > 0) {
-                        deps.bus.emit({
-                            type: "log",
-                            level: "warn",
-                            message: `subagent ${childAgentId}: ${survivors.length} pty session(s) past 2s drain deadline: ${survivors.join(", ")}`,
-                        });
-                    }
-                }
-                catch (e) {
-                    deps.bus.emit({
-                        type: "log",
-                        level: "warn",
-                        message: `pty drainOwnedBy(${childAgentId}) failed: ${e.message ?? e}`,
-                    });
-                }
-            };
-            // 3.4 branch: `run_in_background:true` ONLY when the registry was
-            // wired. When undefined, the field is silently ignored (codex
-            // Round-1 SHOULD-FIX #1 — see design "Registry-absent fallback").
+            // 3.4 branch: `run_in_background:true` ONLY when the registry was wired.
+            // When undefined, the field is silently ignored (codex Round-1 SHOULD #1).
             const wantBackground = deps.backgroundTasks !== undefined && boolArg(args, "run_in_background") === true;
-            const agentName = agent?.name ?? "default";
-            // (4.1) Create the worktree BEFORE spawning the child engine —
-            // synchronously for the sync branch, before launching for the
-            // background branch. The child engine receives the worktree
-            // path as `worktreeCwd`. On any failure path (including
-            // cancellation), `worktreeHandle.cleanup()` is invoked from a
-            // `finally` block (sync) or the registry's settle handler
-            // (background). Cleanup is idempotent so double-invocation is
-            // safe. Round-1 MUST-FIX #3 — `signal` flows into the spawn.
-            let worktreeHandle;
-            if (isolationMode === "worktree") {
-                try {
-                    worktreeHandle = await createAgentWorktree(deps.workspaceRoot, {
-                        signal: ctx.signal,
-                    });
-                }
-                catch (e) {
-                    if (e instanceof WorktreeError) {
-                        return {
-                            ok: false,
-                            output: `Isolation worktree could not be created (${e.code}): ${e.message}. Hint: ensure the workspace is a git repository and 'git' is on PATH.`,
-                        };
-                    }
-                    throw e;
-                }
-            }
+            // (7.8 §3.2) Build the child agent via the SHARED helper (persona / tool
+            // filtering / fork gates / worktree / PTY / engine). The one byte-level
+            // difference between the two one-shot paths is event-tagging identity:
+            //   - sync       → `"none"`     ({agentName}; the parent labels sync
+            //                  children at its own tool:call/result boundary).
+            //   - background → `"deferred"` ({agentId:"", agentName}); we set
+            //                  `.agentId` to the registry task id after `launch()`.
+            const built = await buildChildEngine(deps, {
+                prompt,
+                subagentType: strArg(args, "subagent_type", false),
+                isolation: strArg(args, "isolation", false),
+                context: strArg(args, "context", false),
+            }, childMaxTurns, wantBackground ? "deferred" : "none", ctx.signal);
+            if (!built.ok)
+                return { ok: false, output: built.output };
+            const { engine, agentName, agentContext, firstPrompt, worktreeHandle, mcpToolsFiltered } = built;
             const worktreeCwd = worktreeHandle?.path;
-            // (5.5 / D6) `childPrompt` was finalised in the fork block above (directive
-            // for a fork, raw prompt for a fresh subagent). `isolationMode` — which
-            // the directive's worktree caveat depends on — is resolved before that
-            // block, so no recompute is needed here even though the worktree itself is
-            // created later.
+            // (5.1) Drain the child's PTY sessions on every termination path. Bound
+            // to the single child PTY agentId minted inside `buildChildEngine`.
+            const drainChildPty = makeDrainChildPty(deps, built.childPtyAgentId);
             if (wantBackground) {
                 // The registry runs `run(signal)` under its own unlinked
-                // AbortController — parent's `ctx.signal` does NOT bind. The
-                // child engine's loop honors `signal` via `tokenFromSignal`,
-                // same path 3.3 sync subagents use.
-                //
-                // Closure capture of the task id: `launch()` is synchronous and
-                // returns the handle before the registry kicks `run()` into
-                // microtask land. The child engine's `agentContext` is a SHARED
-                // mutable object — we set `.agentId` after `launch()` returns,
-                // and because `AgentEngine.emit` re-reads `ctx.agentId` per
-                // emit, the engine will pick up the registry-issued id by the
-                // time the child's first data frame fires.
-                const agentContextObj = {
-                    agentId: "",
-                    agentName,
-                };
-                // (5.1) PTY-ownership agentId for the child. Minted here, NOT
-                // re-using `handle.taskId` (that's pinned to AsyncTaskRegistry
-                // semantics; PTY ownership is a separate concern). The drain
-                // path at the end of `run()` calls `drainOwnedBy(ptyAgentId)`,
-                // matching sessions the model started through this subagent's
-                // `pty` tool. Adopted sessions have re-bound to the parent's
-                // agentId and are no-ops there.
-                const childPtyAgentId = createId("sub");
-                if (deps.ptySessions && deps.nativeCreatePtySession) {
-                    childTools.register(createPtyTool({
-                        registry: deps.ptySessions,
-                        agentId: childPtyAgentId,
-                        agentName,
-                        workspaceRoot: deps.workspaceRoot,
-                        // (5.1 codex Round-2 MUST-FIX #3) Isolated subagent's
-                        // PTY commands default to the worktree path, not the
-                        // parent's. Without this override, `pty.start({command:
-                        // "pwd"})` from inside an isolated subagent would
-                        // execute against the parent checkout.
-                        defaultCwd: worktreeCwd ?? deps.workspaceRoot,
-                        worktreeCwd,
-                        createHandle: deps.nativeCreatePtySession,
-                    }));
-                }
+                // AbortController — parent's `ctx.signal` does NOT bind. `launch()` is
+                // synchronous and returns the handle before the registry kicks `run()`
+                // into microtask land; the child engine's `agentContext` is the shared
+                // mutable object from `buildChildEngine`, so setting `.agentId` after
+                // launch lands before the child's first data frame fires.
                 try {
                     const handle = deps.backgroundTasks.launch({
                         name: agentName,
                         prompt,
-                        // (5.7) Carry the worktree's RELATIVE path + branch (PII-free) so
-                        // the OTel exporter can stamp `chances.gen_ai.worktree.*` on the
-                        // synthesized background span. Absolute path is never carried.
+                        // (5.7) Carry the worktree's RELATIVE path + branch (PII-free) for
+                        // the OTel exporter. Relative to the worktree's OWN canonicalRoot
+                        // (codex R2 Q4) so a caller cwd inside a pre-existing worktree
+                        // can't leak an absolute-ish `..` path.
                         ...(worktreeHandle
                             ? {
                                 worktree: {
-                                    // RELATIVE to the worktree's OWN `canonicalRoot` (codex R2
-                                    // Q4) — not `deps.workspaceRoot`, which can differ when the
-                                    // caller's cwd sits inside a pre-existing user worktree, in
-                                    // which case `relative()` could emit `..` and leak an
-                                    // absolute-ish path. Against canonicalRoot this is always a
-                                    // clean `.chances/worktrees/agent-…`. The exporter guards
-                                    // again defensively before stamping.
                                     relativePath: relative(worktreeHandle.canonicalRoot, worktreeHandle.path),
                                     branch: worktreeHandle.branch,
                                 },
@@ -587,55 +565,18 @@ export function createTaskTool(deps) {
                             : {}),
                         run: async (signal) => {
                             const startedAt = Date.now();
-                            const childSession = forkedChildSession ?? SessionManager.create("subagent");
-                            const childEngine = new AgentEngine({
-                                bus: deps.bus,
-                                router: deps.router,
-                                tools: childTools,
-                                gate: deps.gate,
-                                getApprovalMode: deps.getApprovalMode,
-                                // (5.4 D12) inherit the parent's MCP mention resolver.
-                                resolveMcpMentions: deps.resolveMcpMentions,
-                                session: childSession,
-                                memory: deps.memory,
-                                workspaceRoot: deps.workspaceRoot,
-                                maxTurns: childTurnsBudget,
-                                // (7.7 §6) A subagent is non-interactive — a max-turns ceiling
-                                // must FAIL (so the parent's task result surfaces it), not pause
-                                // for a "continue?" no one can answer.
-                                pauseOnMaxTurns: false,
-                                suppressTerminalErrors: true,
-                                // 3.4: background child suppresses lifecycle events
-                                // (turn:start/turn:end/error) so the TUI's `busy` flag
-                                // doesn't flip when the background advances a turn.
-                                suppressLifecycleEvents: true,
-                                systemBaseOverride: agent?.systemPrompt,
-                                selection: effectiveSelection,
-                                // 3.4: stamp every data-frame event the child emits
-                                // with the registry-issued task id + agent name so
-                                // subscribers can demultiplex parent vs. child output.
-                                agentContext: agentContextObj,
-                                // (4.1) Worktree isolation — child engine flips its
-                                // `ToolContext.workspaceRoot`/`cwd` to the worktree
-                                // path through AsyncLocalStorage.
-                                worktreeCwd,
-                            });
                             const childToken = tokenFromSignal(signal);
                             try {
-                                const result = await childEngine.runTurn(childPrompt, childToken, { expandMentions: false });
-                                // (Round-2 SHOULD-FIX #2) Re-check cancellation BEFORE
-                                // finalize. If a `kill` arrived after the model finished
-                                // its last tool call but before this point, the registry
-                                // will record the task as cancelled — the worktree
-                                // should be cleaned up, not retained as success.
+                                const result = await engine.runTurn(firstPrompt, childToken, {
+                                    expandMentions: false,
+                                });
+                                // (Round-2 SHOULD-FIX #2) Re-check cancellation BEFORE finalize:
+                                // a `kill` after the last tool call but before here should clean
+                                // up the worktree, not retain it as success.
                                 if (signal.aborted) {
                                     if (worktreeHandle)
                                         await worktreeHandle.cleanup();
-                                    return {
-                                        ok: false,
-                                        text: "Subagent cancelled",
-                                        durationMs: Date.now() - startedAt,
-                                    };
+                                    return { ok: false, text: "Subagent cancelled", durationMs: Date.now() - startedAt };
                                 }
                                 const finalText = result.text.trim() || "(subagent finished without producing any text)";
                                 const wrapped = await finalizeWorktree(worktreeHandle, deps.workspaceRoot, finalText, mcpToolsFiltered);
@@ -643,22 +584,14 @@ export function createTaskTool(deps) {
                                     ok: true,
                                     text: wrapped,
                                     durationMs: Date.now() - startedAt,
-                                    tokens: {
-                                        input: result.inputTokens,
-                                        output: result.outputTokens,
-                                    },
+                                    tokens: { input: result.inputTokens, output: result.outputTokens },
                                 };
                             }
                             catch (e) {
-                                // Failure / cancel: tear down the worktree (idempotent).
                                 if (worktreeHandle)
                                     await worktreeHandle.cleanup();
                                 if (e instanceof AppError && e.code === ErrorCode.Cancelled) {
-                                    return {
-                                        ok: false,
-                                        text: "Subagent cancelled",
-                                        durationMs: Date.now() - startedAt,
-                                    };
+                                    return { ok: false, text: "Subagent cancelled", durationMs: Date.now() - startedAt };
                                 }
                                 const msg = e instanceof AppError
                                     ? `Subagent failed (${e.code}): ${e.message}`
@@ -666,20 +599,17 @@ export function createTaskTool(deps) {
                                 return { ok: false, text: msg, durationMs: Date.now() - startedAt };
                             }
                             finally {
-                                // (5.1) Drain every still-running PTY session owned by
-                                // the child. Adopted sessions re-bound to the parent
-                                // are no-ops here. Fires before the registry surfaces
-                                // the completion notification so the model never sees
-                                // a `<task-notification>` for a subagent that still
-                                // holds live shells in the background.
-                                await drainChildPty(childPtyAgentId);
+                                // Drain before the registry surfaces the completion
+                                // notification, so the model never sees a `<task-notification>`
+                                // for a subagent that still holds live shells.
+                                await drainChildPty();
                             }
                         },
                     });
-                    agentContextObj.agentId = handle.taskId;
+                    agentContext.agentId = handle.taskId;
                     const body = [
                         `(background-launched) task_id=${handle.taskId} name=${agentName}`,
-                        ...(isolationMode === "worktree" && worktreeHandle
+                        ...(worktreeCwd && worktreeHandle
                             ? [`isolation=worktree path=${relative(deps.workspaceRoot, worktreeHandle.path) || worktreeHandle.path} branch=${worktreeHandle.branch}`]
                             : []),
                         "",
@@ -688,72 +618,19 @@ export function createTaskTool(deps) {
                     return { ok: true, output: body };
                 }
                 catch (e) {
-                    // launch() failed — if we already created a worktree, tear it
-                    // down so we don't leak it into the next stale-GC pass.
+                    // launch() failed — tear down any worktree so it doesn't leak.
                     if (worktreeHandle)
                         await worktreeHandle.cleanup();
-                    // Capacity refusal or registry-disposed surfaces as a labeled
-                    // AppError(Tool); fold it into ok:false so the model sees the
-                    // recovery message.
                     if (e instanceof AppError && e.code === ErrorCode.Tool) {
                         return { ok: false, output: e.message };
                     }
                     throw e;
                 }
             }
-            // Synchronous path. (3.6 codex Round-1 MUST-FIX #3) The 3.4
-            // background path correctly suppresses lifecycle frames and tags
-            // data frames with the agent identity; the sync path was missed
-            // — child `turn:start`/`turn:end`/`usage:turn` flowed onto the
-            // shared bus untagged, which (a) would flip TUI `busy` state
-            // for any subscriber that toggles on the bare event, and (b)
-            // would corrupt the 3.6 OTel exporter's `Map<turnId, Span>` by
-            // opening a second `invoke_agent` span inside the parent turn.
-            // Same shape as background: suppress lifecycle, tag data frames
-            // with `{agentName}` (no agentId — sync subagents complete before
-            // the parent's `tool:call`/`tool:result` boundary closes, so the
-            // parent already labels them at that level).
-            const syncChildPtyAgentId = createId("sub");
-            if (deps.ptySessions && deps.nativeCreatePtySession) {
-                childTools.register(createPtyTool({
-                    registry: deps.ptySessions,
-                    agentId: syncChildPtyAgentId,
-                    agentName,
-                    workspaceRoot: deps.workspaceRoot,
-                    // (5.1 codex Round-2 MUST-FIX #3) Same worktree-cwd default
-                    // override as the background branch above.
-                    defaultCwd: worktreeCwd ?? deps.workspaceRoot,
-                    worktreeCwd,
-                    createHandle: deps.nativeCreatePtySession,
-                }));
-            }
-            const childSession = forkedChildSession ?? SessionManager.create("subagent");
-            const child = new AgentEngine({
-                bus: deps.bus,
-                router: deps.router,
-                tools: childTools,
-                gate: deps.gate,
-                getApprovalMode: deps.getApprovalMode,
-                // (5.4 D12) inherit the parent's MCP mention resolver.
-                resolveMcpMentions: deps.resolveMcpMentions,
-                session: childSession,
-                memory: deps.memory,
-                workspaceRoot: deps.workspaceRoot,
-                maxTurns: childTurnsBudget,
-                // (7.7 §6) Non-interactive subagent → fail on the ceiling, never pause.
-                pauseOnMaxTurns: false,
-                suppressTerminalErrors: true,
-                suppressLifecycleEvents: true,
-                agentContext: { agentName },
-                systemBaseOverride: agent?.systemPrompt,
-                selection: effectiveSelection,
-                // (4.1) Worktree isolation — same wiring as the background
-                // branch above.
-                worktreeCwd,
-            });
+            // Synchronous path.
             const childToken = tokenFromSignal(ctx.signal);
             try {
-                const result = await child.runTurn(childPrompt, childToken, { expandMentions: false });
+                const result = await engine.runTurn(firstPrompt, childToken, { expandMentions: false });
                 const body = result.text.trim();
                 if (!body) {
                     if (worktreeHandle)
@@ -774,12 +651,7 @@ export function createTaskTool(deps) {
                 return { ok: false, output: `Subagent failed: ${e.message || String(e)}` };
             }
             finally {
-                // (5.1) Drain every PTY session owned by the sync subagent.
-                // Same drain shape as the background branch — adopted
-                // sessions re-bound to the parent are no-ops here. Fires
-                // before this `execute` returns so the parent's next turn
-                // never sees `pty.list()` results for a defunct sync child.
-                await drainChildPty(syncChildPtyAgentId);
+                await drainChildPty();
             }
         },
     };
@@ -888,6 +760,90 @@ function appendMcpFilterNotice(body, n) {
         return body;
     return `${body}\n\n[notice: ${n} mutating MCP tool(s) were hidden from this subagent due to active isolation]`;
 }
+/** (5.1 / 7.8 §3.2) PTY drain closure bound to a child's PTY agentId. Extracted
+ * from the prior inline `drainChildPty` closure so the one-shot `task` paths AND
+ * the persistent worker's `drainPty` share it. Kills sessions still owned by
+ * `childAgentId` (adopted-to-parent sessions are no-ops); failure is logged once
+ * on the bus, never blocks the caller; 2s deadline matches `killAll`. */
+function makeDrainChildPty(deps, childAgentId) {
+    return async () => {
+        if (!deps.ptySessions)
+            return;
+        try {
+            const { survivors } = await deps.ptySessions.drainOwnedBy(childAgentId, 2_000);
+            if (survivors.length > 0) {
+                deps.bus.emit({
+                    type: "log",
+                    level: "warn",
+                    message: `subagent ${childAgentId}: ${survivors.length} pty session(s) past 2s drain deadline: ${survivors.join(", ")}`,
+                });
+            }
+        }
+        catch (e) {
+            deps.bus.emit({
+                type: "log",
+                level: "warn",
+                message: `pty drainOwnedBy(${childAgentId}) failed: ${e.message ?? e}`,
+            });
+        }
+    };
+}
+/** (7.8 §3.2) The worktree-retention decision for a PERSISTENT worker — same
+ * three-probe policy as {@link finalizeWorktree} (diff/status/unmerged-commits,
+ * fail-closed on probe error), but returns just the retention BANNER (or the
+ * mcp-filter notice) to surface, with NO body to wrap (the worker delivered its
+ * results per-message already). `undefined` ⇒ nothing kept, nothing to say. */
+async function finalizeWorktreeBanner(handle, parentWorkspace, mcpToolsFiltered) {
+    const mcpNotice = mcpToolsFiltered > 0
+        ? `[notice: ${mcpToolsFiltered} mutating MCP tool(s) were hidden from this worker due to active isolation]`
+        : undefined;
+    if (!handle)
+        return mcpNotice;
+    let shortstat = "";
+    let statusEmpty = true;
+    let unmergedCommits = 0;
+    let probeFailed = false;
+    try {
+        shortstat = await gitDiffShortstat(handle.path);
+    }
+    catch {
+        probeFailed = true;
+    }
+    try {
+        statusEmpty = await gitStatusEmpty(handle.path);
+    }
+    catch {
+        probeFailed = true;
+    }
+    try {
+        unmergedCommits = await gitUnmergedCommitCount(handle.canonicalRoot, handle.branch);
+    }
+    catch {
+        probeFailed = true;
+    }
+    const hasChanges = shortstat.length > 0 || !statusEmpty || unmergedCommits > 0;
+    if (!hasChanges && !probeFailed) {
+        await handle.cleanup();
+        return mcpNotice;
+    }
+    const relPath = relative(parentWorkspace, handle.path) || handle.path;
+    const reasons = [];
+    if (shortstat.length > 0)
+        reasons.push(shortstat);
+    if (!statusEmpty)
+        reasons.push("untracked or staged files present");
+    if (unmergedCommits > 0)
+        reasons.push(`${unmergedCommits} commit(s) on ${handle.branch} not on HEAD`);
+    if (probeFailed && reasons.length === 0)
+        reasons.push("probe error during retention check — worktree kept defensively");
+    return [
+        `[worktree retained: ${relPath} on branch ${handle.branch}]`,
+        `[diff: ${reasons.join("; ")}]`,
+        mcpNotice,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
 /** Boolean arg reader. Returns true only when the value is literal `true`;
  * everything else (false, missing, wrong type) returns false. We avoid
  * coercion (truthy strings etc.) because schema-level safety matters here. */