@chances-ai/engine 24.0.0

package/dist/core/task-tool.js

@@ -0,0 +1,901 @@
+import { relative } from "node:path";
+import { AppError, ErrorCode, ModelSelection, createId, tokenFromSignal, } from "@chances-ai/runtime";
+import { SessionManager } from "../session/index.js";
+import { ToolRegistry, createPtyTool } from "../tools/index.js";
+import { renderCatalogForToolDescription } from "../agents/index.js";
+import { AgentEngine, DEFAULT_MAX_TURNS } from "./engine.js";
+import { estimateTokens } from "./compaction/estimate.js";
+import { createAgentWorktree, WorktreeError, } from "./worktree/index.js";
+import { gitDiffShortstat, gitStatusEmpty, gitUnmergedCommitCount, } from "./worktree/git.js";
+/** Public tool name. Exported so callers building child registries (or codex
+ * review!) can refer to the constant rather than re-spelling "task". */
+export const TASK_TOOL_NAME = "task";
+/** (5.1) Sibling constant — both the parent's `pty` (registered by
+ * `buildEngine`) and any per-subagent re-registration (here) use the
+ * same well-known name. */
+const PTY_TOOL_NAME = "pty";
+/** 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. */
+const CHILD_MAX_TURNS_CEILING = 50;
+/** (5.5) Fraction of the effective child model's context window a `context:
+ * "fork"` subagent may fill with inherited history. The remainder is left for
+ * the child's own multi-turn work, system prompt, tool schemas, and responses.
+ * `config.agent.forkMaxContextTokens` overrides the derived budget entirely. */
+const FORK_WINDOW_FRACTION = 0.5;
+/** (5.5) Budget used only when the effective child model's window can't be
+ * resolved. Deliberately conservative (small windows exist — the estimator
+ * itself warns of 32K/65K providers) so an unknown model never gets an
+ * optimistic high cap. */
+const CONSERVATIVE_FORK_DEFAULT = 24_000;
+/** (5.5 / R2 MUST-FIX) Flat allowance added to the fork estimate for the parts
+ * of the child's first request we don't size exactly: the base system prompt
+ * and any plan-mode / worktree system reminders (the per-agent `pty` tool
+ * schema lands here too). Memory context + the other tool schemas + the
+ * directive + inherited history ARE counted explicitly; this covers the rest so
+ * the preflight errs toward refusing a borderline fork rather than overflowing. */
+const SYSTEM_BASE_RESERVE_TOKENS = 1_500;
+/** (5.5) Flatten a message's content parts to text for fork token estimation.
+ * Tool-call args and tool-result outputs count toward the inherited size, so
+ * we serialize them rather than only counting `text` parts. */
+function messageToText(m) {
+    return m.content
+        .map((p) => {
+        if (p.type === "text")
+            return p.text;
+        if (p.type === "tool-call")
+            return `${p.name} ${JSON.stringify(p.args)}`;
+        if (p.type === "tool-result")
+            return p.output;
+        return "";
+    })
+        .join("\n");
+}
+/** (5.5 / R2 SHOULD-FIX) Rough token size of a session's full transcript — the
+ * consent-relevant "how much am I sharing" figure shown in the fork permission
+ * summary. The execute-time guard uses a fuller estimate (tools + system); this
+ * is just the inherited history. */
+function inheritedForkTokens(session) {
+    return estimateTokens(session.messages().map(messageToText).join("\n"));
+}
+/** (5.5 / D6) Frame the inherited history so the child treats it as background
+ * context, not a conversation to continue, and surface the worktree caveat when
+ * the child is filesystem-isolated. Lands as the child's first user turn (after
+ * the forked history). */
+function buildForkDirective(prompt, isWorktree) {
+    const worktreeNote = isWorktree
+        ? " Note: you run in an isolated git worktree, so the parent's *uncommitted* working-tree edits referenced above are NOT visible here."
+        : "";
+    return ("[FORKED CONTEXT] The conversation above was inherited from the agent that " +
+        "delegated this task — it is background context only; do not continue it." +
+        worktreeNote +
+        "\n\nYour task:\n\n" +
+        prompt);
+}
+function strArg(args, key, required) {
+    const v = args[key];
+    if (v === undefined || v === null) {
+        if (required)
+            throw new AppError(ErrorCode.Tool, `Expected string arg "${key}"`);
+        return undefined;
+    }
+    if (typeof v !== "string")
+        throw new AppError(ErrorCode.Tool, `Expected string arg "${key}"`);
+    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.
+ *
+ * **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.
+ */
+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.";
+    // Append the catalog block when agents are configured. Each entry's
+    // description is hard-capped + control-stripped + framed as metadata (not
+    // instructions) by `renderCatalogForToolDescription` — codex Round-1 #7/#8.
+    const catalog = deps.agents;
+    const rendered = catalog && catalog.size > 0 ? renderCatalogForToolDescription(catalog) : null;
+    const description = rendered && rendered.text
+        ? `${baseDescription}\n\n${rendered.text}`
+        : baseDescription;
+    // Schema. `subagent_type` is open string (the catalog is dynamic; static
+    // enum would be stale the moment a user edits a file). All three ref
+    // repos converge on this shape. Built as a JSONValue object explicitly
+    // so the conditional `subagent_type` doesn't end up as a union type the
+    // surrounding `Tool.parameters: JSONValue` field can't accept.
+    const properties = {
+        description: {
+            type: "string",
+            description: "Short label (1–3 words) describing what this subtask does. Surfaces in the permission prompt so the user sees what they're approving.",
+        },
+        prompt: {
+            type: "string",
+            description: "Full task description for the child agent. Treat this like the very first user message — make it self-contained. Even with context:'fork', the child does NOT see your CURRENT turn (only completed prior turns), so always restate the immediate ask and paste any current-turn content (e.g. a resource you just @-mentioned) the child needs.",
+        },
+    };
+    if (catalog && catalog.size > 0) {
+        properties["subagent_type"] = {
+            type: "string",
+            description: "Optional persona from the catalog (see this tool's description). Omit to spawn the default subagent (full tool inheritance from the parent).",
+        };
+    }
+    if (deps.backgroundTasks) {
+        properties["run_in_background"] = {
+            type: "boolean",
+            description: "Set to true to launch this subagent in the background and return immediately with a task id. You will receive the result as a <task-notification> block on a future turn. Use this when you want to fan out parallel work (issue multiple background launches in one turn) or when you want to keep working while a long-running investigation continues. Do not poll, do not relaunch.",
+        };
+    }
+    // (4.1) Worktree isolation, model-callable.
+    properties["isolation"] = {
+        type: "string",
+        enum: ["worktree", "none"],
+        description: "Optional FS isolation. 'worktree' runs this subagent inside a fresh git worktree under .chances/worktrees/; writes are not visible to the parent until the task completes. 'none' (the default) shares the parent's working tree. Overrides the agent catalog frontmatter when set.",
+    };
+    // (5.5) Conversation-context mode, model-callable (per-call only — no
+    // frontmatter default, since fork changes transcript disclosure + cost).
+    properties["context"] = {
+        type: "string",
+        enum: ["fork", "fresh"],
+        description: "Conversation context for the child. 'fresh' (the default) = empty context, child sees only `prompt`. 'fork' = the child inherits a copy of THIS conversation's completed turns as background context (for continuing the current line of work). Forking shares your full transcript with the child's model; it is refused if the inherited context is too large for that model, or if the child's model is a different provider than this session (unless config.agent.allowCrossProviderFork).",
+    };
+    return {
+        name: TASK_TOOL_NAME,
+        description,
+        category: "integration",
+        parameters: {
+            type: "object",
+            properties,
+            required: ["prompt"],
+        },
+        summarize: (args) => {
+            const desc = strArg(args, "description", false);
+            const prompt = strArg(args, "prompt", true);
+            const subType = strArg(args, "subagent_type", false);
+            const head = prompt.length > 80 ? prompt.slice(0, 80) + "…" : prompt;
+            // When the model targets a persona, surface the effective tool list
+            // in the permission summary so the user sees the narrowed surface
+            // before approving the spawn (codex Round-1 #17).
+            const personaTail = subType && catalog?.has(subType)
+                ? ` (tools: ${formatToolListForSummary(catalog.get(subType).tools)})`
+                : "";
+            const label = subType ? `task[${subType}]` : desc ? `task[${desc}]` : "task";
+            // (5.5 / D9) Surface fork transcript-disclosure + the effective
+            // model/provider in the permission summary so the user approving the
+            // spawn sees that the full conversation is handed to the child (and to
+            // which provider). Best-effort: never let summary resolution throw.
+            let forkTail = "";
+            if (strArg(args, "context", false) === "fork") {
+                try {
+                    const personaModel = subType && catalog?.has(subType) ? catalog.get(subType).model : undefined;
+                    const parentChoice = deps.parentSelection?.get() ?? {};
+                    const parentProvider = deps.router.pick({
+                        preferredModel: parentChoice.model,
+                        preferredProvider: parentChoice.provider,
+                        needsTools: true,
+                    }).model.provider;
+                    const childModel = (personaModel
+                        ? deps.router.pick({ preferredModel: personaModel, needsTools: true })
+                        : deps.router.pick({
+                            preferredModel: parentChoice.model,
+                            preferredProvider: parentChoice.provider,
+                            needsTools: true,
+                        })).model;
+                    const differs = childModel.provider !== parentProvider;
+                    const tokTail = deps.parentSession
+                        ? ` ~${inheritedForkTokens(deps.parentSession)}tok`
+                        : "";
+                    forkTail = ` (fork: full transcript${tokTail} → ${childModel.id}/${childModel.provider}${differs ? " ⚠ differs from session" : ""})`;
+                }
+                catch {
+                    forkTail = " (fork: full transcript)";
+                }
+            }
+            return `${label}: ${head}${personaTail}${forkTail}`;
+        },
+        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").
+            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;
+                }
+            }
+            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.
+            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,
+                    }));
+                }
+                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.
+                        ...(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,
+                                },
+                            }
+                            : {}),
+                        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,
+                                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.
+                                if (signal.aborted) {
+                                    if (worktreeHandle)
+                                        await worktreeHandle.cleanup();
+                                    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);
+                                return {
+                                    ok: true,
+                                    text: wrapped,
+                                    durationMs: Date.now() - startedAt,
+                                    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,
+                                    };
+                                }
+                                const msg = e instanceof AppError
+                                    ? `Subagent failed (${e.code}): ${e.message}`
+                                    : `Subagent failed: ${e.message || String(e)}`;
+                                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);
+                            }
+                        },
+                    });
+                    agentContextObj.agentId = handle.taskId;
+                    const body = [
+                        `(background-launched) task_id=${handle.taskId} name=${agentName}`,
+                        ...(isolationMode === "worktree" && worktreeHandle
+                            ? [`isolation=worktree path=${relative(deps.workspaceRoot, worktreeHandle.path) || worktreeHandle.path} branch=${worktreeHandle.branch}`]
+                            : []),
+                        "",
+                        "You will receive a <task-notification> block on a future turn when this task completes. Do not poll; do not relaunch unless explicitly asked.",
+                    ].join("\n");
+                    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.
+                    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,
+                suppressTerminalErrors: true,
+                suppressLifecycleEvents: true,
+                agentContext: { agentName },
+                systemBaseOverride: agent?.systemPrompt,
+                selection: effectiveSelection,
+                // (4.1) Worktree isolation — same wiring as the background
+                // branch above.
+                worktreeCwd,
+            });
+            const childToken = tokenFromSignal(ctx.signal);
+            try {
+                const result = await child.runTurn(childPrompt, childToken, { expandMentions: false });
+                const body = result.text.trim();
+                if (!body) {
+                    if (worktreeHandle)
+                        await worktreeHandle.cleanup();
+                    return { ok: false, output: "Subagent finished without producing any text" };
+                }
+                const wrapped = await finalizeWorktree(worktreeHandle, deps.workspaceRoot, body, mcpToolsFiltered);
+                return { ok: true, output: wrapped };
+            }
+            catch (e) {
+                if (worktreeHandle)
+                    await worktreeHandle.cleanup();
+                if (e instanceof AppError && e.code === ErrorCode.Cancelled)
+                    throw e;
+                if (e instanceof AppError) {
+                    return { ok: false, output: `Subagent failed (${e.code}): ${e.message}` };
+                }
+                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);
+            }
+        },
+    };
+}
+/** (4.1) MCP-bridged tools follow the `mcp__<server>__<tool>` naming
+ * convention established in 3.1. Source-of-truth lives in `@chances-ai/mcp`
+ * but matching by prefix keeps task-tool free of an mcp import. */
+function isMcpToolName(name) {
+    return name.startsWith("mcp__");
+}
+/** (4.1) Read-only chances tool categories. MCP tools whose declared
+ * category falls outside this set are filtered out of isolated
+ * subagents by default; `unsafeAllowMutatingMcp: true` opts back in. */
+function isReadOnlyMcpCategory(category) {
+    return (category === "file-read" ||
+        category === "memory-read" ||
+        category === "network-read" ||
+        category === "search");
+}
+/**
+ * (4.1) Decides what to do with the worktree after the child finishes
+ * cleanly. Codex Round-2 caught three independent retention bugs in the
+ * v1 implementation; folded fixes:
+ *
+ *   - MUST-FIX #1: `git diff --shortstat HEAD` is empty when the child
+ *     COMMITTED its work (HEAD moved). Solution: also probe
+ *     `gitUnmergedCommitCount(branch ^HEAD)` — any commit on the child's
+ *     branch that isn't reachable from HEAD counts as "has work to
+ *     keep".
+ *   - MUST-FIX #2: `git diff` doesn't show untracked files. A subagent
+ *     that creates new files only would look clean. Solution: also
+ *     probe `gitStatusEmpty` — any untracked/modified/staged file
+ *     counts as "has work to keep".
+ *   - MUST-FIX #4: silently mapping probe failures to "empty diff"
+ *     drives destructive cleanup on transient flakiness. Solution: any
+ *     probe that throws marks `probeFailed = true` and we retain the
+ *     worktree.
+ *
+ * Net rule: a worktree is silently removed ONLY when all three probes
+ * succeed AND all three report no effect. Otherwise we keep it, surface
+ * the path + branch + diff-stat banner to the parent, and let the user
+ * decide. Matches claude-code's belt-and-suspenders `AgentTool.tsx`
+ * policy.
+ *
+ * Also folds Round-2 SHOULD-FIX #3: when MCP tools were filtered, the
+ * notice is appended on BOTH the retained and the clean-removed
+ * branches (previously only retained).
+ */
+export async function __finalizeWorktreeForTest(handle, parentWorkspace, body, mcpToolsFiltered) {
+    return finalizeWorktree(handle, parentWorkspace, body, mcpToolsFiltered);
+}
+async function finalizeWorktree(handle, parentWorkspace, body, mcpToolsFiltered) {
+    if (!handle) {
+        return appendMcpFilterNotice(body, mcpToolsFiltered);
+    }
+    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 appendMcpFilterNotice(body, mcpToolsFiltered);
+    }
+    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");
+    const banner = [
+        `[worktree retained: ${relPath} on branch ${handle.branch}]`,
+        `[diff: ${reasons.join("; ")}]`,
+        mcpToolsFiltered > 0
+            ? `[notice: ${mcpToolsFiltered} mutating MCP tool(s) were hidden from this subagent due to active isolation]`
+            : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return `${banner}\n\n${body}`;
+}
+function appendMcpFilterNotice(body, n) {
+    if (n <= 0)
+        return body;
+    return `${body}\n\n[notice: ${n} mutating MCP tool(s) were hidden from this subagent due to active isolation]`;
+}
+/** 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. */
+function boolArg(args, key) {
+    const v = args[key];
+    return v === true;
+}
+/** Format an agent's tool spec into the one-line permission summary. */
+function formatToolListForSummary(tools) {
+    if (tools === "*")
+        return "*";
+    if (tools.length === 0)
+        return "(none)";
+    if (tools.length <= 5)
+        return tools.join(", ");
+    return `${tools.slice(0, 5).join(", ")}, +${tools.length - 5} more`;
+}
+//# sourceMappingURL=task-tool.js.map