aiden-runtime 4.5.0 → 4.6.0

package/dist/providers/v4/chatCompletionsAdapter.js

@@ -73,7 +73,7 @@ class ChatCompletionsAdapter {
     // ── Non-streaming ────────────────────────────────────────────────────
     async call(input) {
         const body = this.buildBody(input, /* streaming */ false);
-        const reply = await this.dispatch(body, /* streaming */ false);
+        const reply = await this.dispatch(body, /* streaming */ false, input.signal);
         const text = await reply.text();
         let parsed;
         try {
@@ -91,7 +91,7 @@ class ChatCompletionsAdapter {
     // ── Streaming ────────────────────────────────────────────────────────
     async *callStream(input) {
         const body = this.buildBody(input, /* streaming */ true);
-        const reply = await this.dispatch(body, /* streaming */ true);
+        const reply = await this.dispatch(body, /* streaming */ true, input.signal);
         if (!reply.body) {
             yield {
                 type: 'done',
@@ -150,7 +150,7 @@ class ChatCompletionsAdapter {
             headers['Accept'] = 'text/event-stream';
         return { ...headers, ...this.extraHeaders };
     }
-    async dispatch(body, streaming) {
+    async dispatch(body, streaming, externalSignal) {
         const headers = this.buildHeaders(streaming);
         const serialised = JSON.stringify(body);
         const totalTries = this.maxRetries + 1;
@@ -158,6 +158,19 @@ class ChatCompletionsAdapter {
         for (let attempt = 0; attempt < totalTries; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            // v4.6 prep — forward external abort into the internal controller.
+            // External aborts surface as raw AbortError so AidenAgent routes
+            // them as 'interrupted' rather than retrying as ProviderTimeoutError.
+            let externalAbortHandler = null;
+            if (externalSignal) {
+                if (externalSignal.aborted) {
+                    controller.abort();
+                }
+                else {
+                    externalAbortHandler = () => controller.abort();
+                    externalSignal.addEventListener('abort', externalAbortHandler, { once: true });
+                }
+            }
             let response;
             try {
                 response = await fetch(this.endpoint, {
@@ -169,7 +182,14 @@ class ChatCompletionsAdapter {
             }
             catch (err) {
                 clearTimeout(timer);
+                if (externalAbortHandler && externalSignal) {
+                    externalSignal.removeEventListener('abort', externalAbortHandler);
+                }
                 if (err?.name === 'AbortError') {
+                    // v4.6 prep — external abort takes priority over internal timeout.
+                    if (externalSignal?.aborted) {
+                        throw err;
+                    }
                     lastErr = new errors_1.ProviderTimeoutError(this.providerName, this.timeoutMs);
                 }
                 else {
@@ -182,6 +202,9 @@ class ChatCompletionsAdapter {
                 throw lastErr;
             }
             clearTimeout(timer);
+            if (externalAbortHandler && externalSignal) {
+                externalSignal.removeEventListener('abort', externalAbortHandler);
+            }
             if (response.ok)
                 return response;
             const status = response.status;

package/dist/providers/v4/codexResponsesAdapter.js

@@ -104,7 +104,7 @@ class CodexResponsesAdapter {
     // ── Public: non-streaming entry ─────────────────────────────────────
     async call(input) {
         const body = this.buildBody(input);
-        const reply = await this.dispatch(body);
+        const reply = await this.dispatch(body, input.signal);
         // Codex backend always streams; aggregate the SSE frames into the
         // same shape the JSON path returns. Plain api.openai.com path returns
         // JSON directly.
@@ -175,7 +175,7 @@ class CodexResponsesAdapter {
         }
         return { ...headers, ...this.extraHeaders };
     }
-    async dispatch(body) {
+    async dispatch(body, externalSignal) {
         const headers = this.buildHeaders();
         const serialised = JSON.stringify(body);
         const totalTries = this.maxRetries + 1;
@@ -183,6 +183,19 @@ class CodexResponsesAdapter {
         for (let attempt = 0; attempt < totalTries; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            // v4.6 prep — forward external abort into the internal controller.
+            // External aborts surface as raw AbortError so AidenAgent routes
+            // them as 'interrupted' rather than retrying as ProviderTimeoutError.
+            let externalAbortHandler = null;
+            if (externalSignal) {
+                if (externalSignal.aborted) {
+                    controller.abort();
+                }
+                else {
+                    externalAbortHandler = () => controller.abort();
+                    externalSignal.addEventListener('abort', externalAbortHandler, { once: true });
+                }
+            }
             let response;
             try {
                 response = await fetch(this.endpoint, {
@@ -194,7 +207,14 @@ class CodexResponsesAdapter {
             }
             catch (err) {
                 clearTimeout(timer);
+                if (externalAbortHandler && externalSignal) {
+                    externalSignal.removeEventListener('abort', externalAbortHandler);
+                }
                 if (err?.name === 'AbortError') {
+                    // v4.6 prep — external abort takes priority over internal timeout.
+                    if (externalSignal?.aborted) {
+                        throw err;
+                    }
                     lastErr = new errors_1.ProviderTimeoutError(this.providerName, this.timeoutMs);
                 }
                 else {
@@ -207,6 +227,9 @@ class CodexResponsesAdapter {
                 throw lastErr;
             }
             clearTimeout(timer);
+            if (externalAbortHandler && externalSignal) {
+                externalSignal.removeEventListener('abort', externalAbortHandler);
+            }
             if (response.ok)
                 return response;
             const status = response.status;

package/dist/providers/v4/ollamaPromptToolsAdapter.js

@@ -63,7 +63,7 @@ class OllamaPromptToolsAdapter {
         let lastError = null;
         for (let attempt = 1; attempt <= totalAttempts; attempt += 1) {
             try {
-                const response = await this.fetchWithTimeout(url, headers, body);
+                const response = await this.fetchWithTimeout(url, headers, body, input.signal);
                 if (response.ok) {
                     const json = (await response.json());
                     return this.parseResponse(json);
@@ -134,6 +134,17 @@ class OllamaPromptToolsAdapter {
         const headers = { 'Content-Type': 'application/json' };
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        // v4.6 prep — forward external abort into the internal controller.
+        let externalAbortHandler = null;
+        if (input.signal) {
+            if (input.signal.aborted) {
+                controller.abort();
+            }
+            else {
+                externalAbortHandler = () => controller.abort();
+                input.signal.addEventListener('abort', externalAbortHandler, { once: true });
+            }
+        }
         let response;
         try {
             response = await fetch(url, {
@@ -145,13 +156,23 @@ class OllamaPromptToolsAdapter {
         }
         catch (err) {
             clearTimeout(timer);
+            if (externalAbortHandler && input.signal) {
+                input.signal.removeEventListener('abort', externalAbortHandler);
+            }
             if (err instanceof Error && err.name === 'AbortError') {
+                // v4.6 prep — external abort takes priority over internal timeout.
+                if (input.signal?.aborted) {
+                    throw err;
+                }
                 throw new errors_1.ProviderTimeoutError(this.providerName, this.timeoutMs);
             }
             throw new errors_1.ProviderError(`Ollama not reachable at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`, this.providerName, undefined, err, true);
         }
         if (!response.ok) {
             clearTimeout(timer);
+            if (externalAbortHandler && input.signal) {
+                input.signal.removeEventListener('abort', externalAbortHandler);
+            }
             const status = response.status;
             const rawText = await this.safeReadText(response);
             // Phase v4.1.1-oauth-fix Phase 5: composeMessage handles body
@@ -160,8 +181,15 @@ class OllamaPromptToolsAdapter {
         }
         if (!response.body) {
             clearTimeout(timer);
+            if (externalAbortHandler && input.signal) {
+                input.signal.removeEventListener('abort', externalAbortHandler);
+            }
             throw new errors_1.ProviderError(`Provider ${this.providerName} returned an empty stream body`, this.providerName);
         }
+        // Response is good; the stream consumer will run for a while. The
+        // controller stays armed (with `externalSignal` still listening) so
+        // that mid-stream aborts cancel reader.read() via fetch's signal.
+        // Listener cleanup happens in the stream-consumer try/finally below.
         const reader = response.body.getReader();
         const decoder = new TextDecoder('utf-8');
         let lineBuffer = '';
@@ -223,10 +251,18 @@ class OllamaPromptToolsAdapter {
         }
         catch (err) {
             clearTimeout(timer);
+            // v4.6 prep — external abort during mid-stream read surfaces as
+            // AbortError; re-throw so AidenAgent routes it as 'interrupted'.
+            if (err instanceof Error && err.name === 'AbortError' && input.signal?.aborted) {
+                throw err;
+            }
             throw new errors_1.ProviderError(`Provider ${this.providerName} stream interrupted: ${err instanceof Error ? err.message : String(err)}`, this.providerName, undefined, err, true);
         }
         finally {
             clearTimeout(timer);
+            if (externalAbortHandler && input.signal) {
+                input.signal.removeEventListener('abort', externalAbortHandler);
+            }
             try {
                 reader.releaseLock();
             }
@@ -422,9 +458,20 @@ class OllamaPromptToolsAdapter {
         const textBefore = firstTagIdx >= 0 ? text.slice(0, firstTagIdx).trim() : text;
         return { textBefore, toolCalls };
     }
-    async fetchWithTimeout(url, headers, body) {
+    async fetchWithTimeout(url, headers, body, externalSignal) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        // v4.6 prep — forward external abort into the internal controller.
+        let externalAbortHandler = null;
+        if (externalSignal) {
+            if (externalSignal.aborted) {
+                controller.abort();
+            }
+            else {
+                externalAbortHandler = () => controller.abort();
+                externalSignal.addEventListener('abort', externalAbortHandler, { once: true });
+            }
+        }
         try {
             return await fetch(url, {
                 method: 'POST',
@@ -435,12 +482,20 @@ class OllamaPromptToolsAdapter {
         }
         catch (err) {
             if (err instanceof Error && err.name === 'AbortError') {
+                // v4.6 prep — external abort takes priority over internal timeout.
+                // Surface the raw AbortError so AidenAgent routes it as 'interrupted'.
+                if (externalSignal?.aborted) {
+                    throw err;
+                }
                 throw new errors_1.ProviderTimeoutError(this.providerName, this.timeoutMs);
             }
             throw err;
         }
         finally {
             clearTimeout(timer);
+            if (externalAbortHandler && externalSignal) {
+                externalSignal.removeEventListener('abort', externalAbortHandler);
+            }
         }
     }
     async safeReadText(response) {

package/dist/tools/v4/index.js

@@ -90,6 +90,9 @@ const memoryReplace_1 = require("./memory/memoryReplace");
 const memoryRemove_1 = require("./memory/memoryRemove");
 const sessionSummary_1 = require("./memory/sessionSummary");
 const subagentFanout_1 = require("./subagent/subagentFanout");
+// v4.6 Phase 1 — spawn_sub_agent stub registered alongside the
+// fanout stub so the schema is visible at agent construction.
+const spawnSubAgentTool_1 = require("./subagent/spawnSubAgentTool");
 /**
  * Register every read-only tool into `registry`. The
  * `lookup_tool_schema` tool needs a registry reference, so it's
@@ -152,11 +155,25 @@ function registerReadOnlyTools(registry) {
     // Until then, calling the stub returns a clear "not wired" error
     // rather than crashing.
     register(makeSubagentFanoutStub());
+    // v4.6 Phase 1 — register a stub for spawn_sub_agent. Same
+    // rationale: agent construction at `cli/v4/aidenCLI.ts` snapshots
+    // the tool array, so the schema must be in the registry by then.
+    // The REPL wiring at `buildAgentRuntime` calls
+    // `register(makeSpawnSubAgentTool({...real deps}))` to replace
+    // this stub once `parentAgent`, `runStore`, etc. are available.
+    // The stub carries `contexts: ['repl']` so it's excluded from the
+    // daemon agent's tool catalog via `getSchemas(_, 'daemon')`.
+    register((0, spawnSubAgentTool_1.makeSpawnSubAgentStub)());
 }
 /** Stub used until the runtime wires real provider / adapter / agent
  *  dependencies. Returns the SAME schema as the real tool so MCP and
  *  /tools see a consistent surface. */
 function makeSubagentFanoutStub() {
+    // v4.6 Phase 2R — `runChild` removed from `SubagentFanoutFactoryOptions`.
+    // The stub returns a "no providers configured" error envelope on every
+    // call via `resolveProviders: () => []`. Production wires real
+    // `spawnDeps` post-runtime build (`cli/v4/aidenCLI.ts` for REPL,
+    // `cli/v4/commands/mcp.ts` for MCP serve).
     return (0, subagentFanout_1.makeSubagentFanoutTool)({
         resolveProviders: () => [],
         resolveActiveModel: () => ({ providerId: 'unset', modelId: 'unset' }),
@@ -167,9 +184,6 @@ function makeSubagentFanoutStub() {
                     'Call register(makeSubagentFanoutTool({...})) after buildAgentRuntime.');
             },
         },
-        runChild: async () => {
-            throw new Error('subagent_fanout: tool not wired — runtime did not replace the stub.');
-        },
     });
 }
 /**

package/dist/tools/v4/skills/lookupToolSchema.js

@@ -64,7 +64,12 @@ function makeLookupToolSchema(registry) {
                 category: handler.category,
                 mutates: handler.mutates,
                 toolset: handler.toolset,
-                riskTier: 'safe', // v4.4 Phase 1
+                // v4.6 Phase 1 — read the queried tool's actual risk tier
+                // (was previously hardcoded to 'safe' regardless of the tool,
+                // which mis-reported caution/dangerous tools as safe in the
+                // /tools surface). Falls back to 'safe' for tools that never
+                // annotated their tier — matches the registry-level default.
+                riskTier: handler.riskTier ?? 'safe',
             };
         },
     };

package/dist/tools/v4/subagent/spawnSubAgentTool.js

@@ -0,0 +1,334 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/subagent/spawnSubAgentTool.ts — v4.6 Phase 1.
+ *
+ * LLM-callable wrapper for the `spawn_sub_agent` primitive. JSON
+ * schema and description text are verbatim from
+ * `docs/v4.6/phase-1-design.md` §4. The handler:
+ *
+ *   1. Reads the parent agent's current AbortSignal via the
+ *      Flag 1 pattern (`parentAgent.getCurrentSignal()` captured
+ *      reference, not a widened executor signature).
+ *   2. Validates and clamps arguments.
+ *   3. Calls `spawnSubAgent` from `core/v4/subagent/spawnSubAgent.ts`.
+ *   4. Returns the result envelope as the tool result body.
+ *
+ * Q9 — additive to the existing `subagent_fanout` tool. Both
+ * coexist in Phase 1; Phase 2 will refactor `subagent_fanout` to
+ * call this primitive N times.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPAWN_SUB_AGENT_SCHEMA = void 0;
+exports.makeSpawnSubAgentStub = makeSpawnSubAgentStub;
+exports.makeSpawnSubAgentTool = makeSpawnSubAgentTool;
+const factory_1 = require("../../../core/v4/logger/factory");
+const spawnSubAgent_1 = require("../../../core/v4/subagent/spawnSubAgent");
+// v4.6 Phase 3A — operator kill-switch. Checked at handler entry
+// BEFORE any work (no run row written, no child built, no provider
+// call). In-flight children continue uninterrupted; only NEW spawns
+// are blocked. Singleton initialised by REPL/daemon/MCP boot wiring.
+const spawnPause_1 = require("../../../core/v4/subagent/spawnPause");
+// ── Pause helper (v4.6 Phase 3A) ──────────────────────────────────────────
+/**
+ * Safe pause read for the handler entry guard. Catches the
+ * "not initialized" error from `getSpawnPause()` and returns
+ * `{paused: false, status: {paused: false}}` — wiring-order bugs
+ * (handler firing before `initSpawnPause` ran) must NOT take down
+ * the spawn surface. Production boot wiring always inits first,
+ * so this only matters for tests that omit the init step.
+ */
+function safeReadPause() {
+    try {
+        const state = (0, spawnPause_1.getSpawnPause)();
+        const status = state.status();
+        return { paused: status.paused, status };
+    }
+    catch {
+        return { paused: false, status: { paused: false } };
+    }
+}
+// ── Schema description (verbatim from design doc §4) ───────────────────────
+const SCHEMA_DESC = 'Spawn a focused child agent to handle one delegated sub-task synchronously. ' +
+    'The child runs with no access to your conversation history, an intersected ' +
+    'toolset (cannot exceed your capabilities), and a fresh system prompt built ' +
+    'from the goal + optional context. Returns a structured result envelope with ' +
+    "the child's summary, metrics, and exit reason. Use this when a sub-task " +
+    'benefits from isolated context (e.g. exploring a separate codebase area, ' +
+    'running a focused investigation, drafting an artifact without polluting your ' +
+    'main turn). Do NOT use for long-running or scheduled work — use daemon ' +
+    'triggers for that. Spawning is bounded: max 1 child at a time in Phase 1, ' +
+    'no nested spawning, max 200 iterations per child. Each spawn pays full ' +
+    'agent-startup cost (system prompt build, tool catalog ship) and roughly ' +
+    'doubles token spend for that sub-task. Prefer inline work for anything you ' +
+    'can answer in 1-3 of your own iterations. Spawn when isolation, focus, or ' +
+    'a restricted toolset actually helps.';
+// ── Schema constant (shared by real factory + boot-time stub) ─────────────
+/**
+ * v4.6 Phase 1 — module-level schema constant so the boot-time stub
+ * (`makeSpawnSubAgentStub`) advertises the SAME JSON-schema surface
+ * the real factory ships. Both register under name `spawn_sub_agent`
+ * with `contexts: ['repl']`, so the model sees a consistent surface
+ * regardless of whether the stub or the real handler is active.
+ */
+exports.SPAWN_SUB_AGENT_SCHEMA = {
+    name: 'spawn_sub_agent',
+    description: SCHEMA_DESC,
+    inputSchema: {
+        type: 'object',
+        required: ['goal'],
+        properties: {
+            goal: {
+                type: 'string',
+                description: 'The single concrete task for the child. Phrase as an imperative ' +
+                    'outcome — what should be done, not how. The child cannot ask ' +
+                    'follow-up questions; if the goal is ambiguous, refine it before ' +
+                    'spawning.',
+            },
+            context: {
+                type: 'string',
+                description: "Optional background the child needs but couldn't infer from the " +
+                    "goal alone (file paths, prior findings, constraints). Plain text. " +
+                    "The child does NOT see your conversation history; anything it needs " +
+                    'must be here or discoverable via its toolset.',
+            },
+            toolsets: {
+                type: 'array',
+                description: 'OPTIONAL — when present, RESTRICTS the child to specific toolsets. ' +
+                    'OMIT this field to let the child inherit your full toolset (recommended ' +
+                    'for most cases — children inherit your capabilities minus the hard ' +
+                    'blocklist). Each entry MUST be one of the enumerated valid names ' +
+                    'below; invalid names get stripped, and if every requested name is ' +
+                    'invalid the child falls back to inheriting your full toolset (with a ' +
+                    'warning logged). The child can never exceed your capabilities — this ' +
+                    'parameter only narrows them.',
+                items: {
+                    type: 'string',
+                    // v4.6 Phase 1 — enum reflects the actual toolset string
+                    // values registered in tools/v4/. Kept in sync with the
+                    // registry; new toolsets ship by being added to a tool's
+                    // `toolset` field AND to this list.
+                    enum: [
+                        'browser',
+                        'execute',
+                        'files',
+                        'mcp',
+                        'memory',
+                        'process',
+                        'sessions',
+                        'skills',
+                        'subagent',
+                        'system',
+                        'terminal',
+                        'web',
+                    ],
+                },
+            },
+            maxIterations: {
+                type: 'integer',
+                description: 'Maximum tool-call iterations the child may run. Clamped to [1, 200]. ' +
+                    'Choose tight bounds for narrow tasks (5-15) and looser for ' +
+                    'exploration (50-100). Default 50.',
+            },
+            timeoutMs: {
+                type: 'integer',
+                description: 'Hard wall-clock timeout in milliseconds. Default 10 minutes. The ' +
+                    "child is signalled to interrupt on timeout; if it doesn't yield " +
+                    'cooperatively, the worker leaks but the parent stays responsive.',
+            },
+            provider: {
+                type: 'string',
+                description: "OPTIONAL — override the child's provider. Pass a provider ID like " +
+                    "'groq', 'chatgpt-plus', 'anthropic'. Omit to inherit the parent's " +
+                    'provider (recommended for most callers). Mainly used by ' +
+                    "`subagent_fanout`'s rotation for provider diversity. Validated " +
+                    "against the parent's available pool at dispatch — an unknown name " +
+                    "produces a failed envelope with `exitReason: 'provider_not_found'` " +
+                    'and lists the valid names in the error message. Single-provider ' +
+                    '(non-FallbackAdapter) parents reject this field with an error.',
+            },
+        },
+    },
+};
+// ── Boot-time stub (registered before runtime deps are resolved) ──────────
+/**
+ * v4.6 Phase 1 — stub handler used until the REPL wiring at
+ * `cli/v4/aidenCLI.ts` replaces it with the real factory. Returns
+ * the SAME schema surface so `toolRegistry.getSchemas(undefined,
+ * 'repl')` at agent construction sees `spawn_sub_agent` and the
+ * LLM can address the tool by name. If called before the real
+ * wiring lands, returns a clear "not wired" error envelope so the
+ * model gets a structured error rather than a crash.
+ *
+ * Mirrors `makeSubagentFanoutStub` in `tools/v4/index.ts`.
+ */
+function makeSpawnSubAgentStub() {
+    return {
+        schema: exports.SPAWN_SUB_AGENT_SCHEMA,
+        category: 'network',
+        mutates: false,
+        toolset: 'subagent',
+        riskTier: 'caution',
+        contexts: ['repl'],
+        async execute() {
+            return {
+                ok: false,
+                status: 'failed',
+                summary: null,
+                error: 'spawn_sub_agent: tool not wired — runtime did not replace the stub. ' +
+                    'Call register(makeSpawnSubAgentTool({...})) after buildAgentRuntime.',
+                exitReason: 'error',
+                metrics: { apiCalls: 0, durationMs: 0, tokensIn: 0, tokensOut: 0 },
+                childRunId: '0',
+                childSessionId: '',
+            };
+        },
+    };
+}
+// ── Implementation ────────────────────────────────────────────────────────
+function makeSpawnSubAgentTool(factory) {
+    return {
+        schema: exports.SPAWN_SUB_AGENT_SCHEMA,
+        // The tool itself spends tokens. Disk / process side effects, if
+        // any, happen INSIDE the child agent whose toolset is intersected
+        // with the parent's and stripped of the v4.6 blocklist.
+        category: 'network',
+        mutates: false,
+        toolset: 'subagent',
+        riskTier: 'caution',
+        // v4.6 Phase 1 — REPL-only execution context per Q6.
+        // Daemon-fired agents must not initiate sub-agent spawns in
+        // Phase 1: the spawn factory captured the REPL agent reference
+        // at construction, so a daemon-fired turn invoking this tool
+        // would route its child's signal chain through the REPL agent's
+        // state rather than the daemon turn's. Tagging it `['repl']`
+        // here causes `toolRegistry.getSchemas(_, 'daemon')` (used by
+        // daemonAgentBuilder.ts:130) to exclude `spawn_sub_agent` from
+        // the daemon agent's tool catalog, so the model never sees it
+        // when running in daemon mode. Phase 3+ may add a daemon-mode
+        // spawn factory tied to the daemon agent's own reference.
+        contexts: ['repl'],
+        async execute(args, _ctx) {
+            // ── 0. Operator kill-switch (v4.6 Phase 3A) ─────────────────────────
+            // First thing — before arg validation, run-row insertion, or
+            // any child build. A paused state must short-circuit cleanly
+            // with NO side effects (no `runs` row, no log noise beyond
+            // the rejection). Locked decision: paused calls are operator-
+            // induced, NOT real failures; they don't pollute `aiden runs
+            // list`. Envelope intentionally drops the standard SubAgentResult
+            // shape because (a) no childRunId exists (no row was written)
+            // and (b) the error class is qualitatively different from a
+            // spawn that ran and failed.
+            const pauseGate = safeReadPause();
+            if (pauseGate.paused) {
+                const s = pauseGate.status;
+                const reasonSuffix = s.reason ? ` (reason: ${s.reason})` : '';
+                return {
+                    success: false,
+                    errorCode: 'SUBAGENT_SPAWN_PAUSED',
+                    message: `spawn_sub_agent: spawning is paused${reasonSuffix}. ` +
+                        'Run /spawn-pause off to resume.',
+                    pausedAt: s.pausedAt ?? null,
+                    reason: s.reason ?? null,
+                    pausedBy: s.pausedBy ?? null,
+                    durationMs: s.durationMs ?? null,
+                };
+            }
+            // ── 1. Validate + coerce ─────────────────────────────────────────────
+            const goal = typeof args.goal === 'string' ? args.goal.trim() : '';
+            if (!goal) {
+                return {
+                    ok: false,
+                    status: 'failed',
+                    summary: null,
+                    error: "spawn_sub_agent: 'goal' is required and must be a non-empty string",
+                    exitReason: 'error',
+                    metrics: { apiCalls: 0, durationMs: 0, tokensIn: 0, tokensOut: 0 },
+                    childRunId: '0',
+                    childSessionId: '',
+                };
+            }
+            const spec = {
+                goal,
+                context: typeof args.context === 'string' ? args.context : undefined,
+                toolsets: Array.isArray(args.toolsets)
+                    ? args.toolsets.filter((t) => typeof t === 'string')
+                    : undefined,
+                maxIterations: typeof args.maxIterations === 'number' ? args.maxIterations : undefined,
+                timeoutMs: typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined,
+                // v4.6 Phase 2P — per-spawn provider override (per design doc §12.2).
+                // Validation happens in childBuilder against the parent's FallbackAdapter
+                // provider pool; an unknown name produces a failed envelope.
+                provider: typeof args.provider === 'string' ? args.provider : undefined,
+            };
+            // v4.6 Phase 1 observability — log the parsed spec so the next
+            // smoke test can correlate "what the model asked for" with the
+            // child's actual behaviour. Goal is truncated to keep the log
+            // line readable. The parent's sessionId (read off the agent
+            // instance) is included so logs from one user turn cluster.
+            const logger = factory.logger ?? (0, factory_1.noopLogger)();
+            const goalPreview = spec.goal.length > 200 ? spec.goal.slice(0, 200) + '…' : spec.goal;
+            logger.info('spawn_sub_agent invoked', {
+                parentSessionId: factory.parentAgent.getCurrentSignal !== undefined
+                    ? factory.parentAgent.sessionId ?? null
+                    : null,
+                goalPreview,
+                goalLen: spec.goal.length,
+                contextLen: spec.context?.length ?? 0,
+                toolsets: spec.toolsets ?? null,
+                maxIterations: spec.maxIterations ?? null,
+                timeoutMs: spec.timeoutMs ?? null,
+            });
+            // ── 2. Read the parent's current signal (Flag 1 pattern) ─────────────
+            const parentSignal = factory.parentAgent.getCurrentSignal();
+            // ── 3. Resolve optional parent run / session identifiers ─────────────
+            const parentRunId = factory.resolveParentRunId?.();
+            const parentSessionId = factory.resolveParentSessionId?.();
+            // ── 4. Invoke the primitive. NEVER throws — always envelope. ─────────
+            const result = await (0, spawnSubAgent_1.spawnSubAgent)(spec, {
+                // ChildBuilderDeps fields:
+                toolRegistry: factory.toolRegistry,
+                parentToolContext: factory.parentToolContext,
+                parentProvider: factory.parentProvider,
+                parentProviderId: factory.parentProviderId,
+                parentModelId: factory.parentModelId,
+                resolveVerifiedFlag: factory.resolveVerifiedFlag,
+                resolveToolset: factory.resolveToolset,
+                resolveMutates: factory.resolveMutates,
+                // Persistence:
+                runStore: factory.runStore,
+                instanceId: factory.instanceId,
+                // v4.6 Phase 1 observability:
+                logger,
+            }, {
+                signal: parentSignal,
+                parentRunId,
+                parentSessionId,
+            });
+            // Completion log — pairs with "spawn_sub_agent invoked" so a
+            // grep on parentSessionId surfaces invoke → complete in order.
+            logger.info('spawn_sub_agent completed', {
+                childRunId: result.childRunId,
+                childSessionId: result.childSessionId,
+                status: result.status,
+                exitReason: result.exitReason,
+                ok: result.ok,
+                apiCalls: result.metrics.apiCalls,
+                durationMs: result.metrics.durationMs,
+                tokensIn: result.metrics.tokensIn,
+                tokensOut: result.metrics.tokensOut,
+                summaryLen: result.summary?.length ?? 0,
+                errorPreview: result.error?.slice(0, 200) ?? null,
+            });
+            // The envelope IS the tool result body. The agent loop's tool-
+            // result handling will JSON-stringify this and feed it back to
+            // the parent's LLM as the tool message content.
+            return result;
+        },
+    };
+}