aiden-runtime 4.5.0 → 4.6.0

package/dist/core/v4/subagent/spawnPause.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/spawnPause.ts — v4.6 Phase 3A.
+ *
+ * Operator kill-switch for sub-agent spawning. When PAUSED, any new
+ * `spawn_sub_agent` or `subagent_fanout` invocation returns a typed
+ * failure envelope (`errorCode: 'SUBAGENT_SPAWN_PAUSED'`) BEFORE any
+ * runs row is written, child agent built, or provider hit. In-flight
+ * children continue uninterrupted — the gate is at tool-handler
+ * entry only.
+ *
+ * Storage: a file marker at `$aidenHome/spawn.paused` (the
+ * `paths.root` returned by `resolveAidenPaths()`). This choice
+ * differs deliberately from the reference multi-agent system, whose
+ * pause flag is an in-process boolean — Aiden's REPL, daemon, and
+ * MCP server can all coexist on the same machine, so a single
+ * shared marker file is the cheapest way to coordinate pause state
+ * across all three runtimes. The marker survives process restart;
+ * the boot card surfaces a "spawn-paused" indicator so an operator
+ * who forgot they paused last week doesn't sit confused.
+ *
+ * Marker format: a single-line JSON document
+ *   { pausedAt: number; reason: string | null; pausedBy: string }
+ *
+ * Atomic writes: every `pause()` writes to a sibling `.tmp` path
+ * and renames atomically so a concurrent reader can never observe
+ * a half-written file. `status()` tolerates an unreadable marker
+ * (returns `{paused: true}` with no metadata) rather than crashing
+ * — the marker EXISTING is the durable fact; the JSON payload is
+ * forensic detail.
+ *
+ * Module-level singleton: `initSpawnPause({aidenHome})` then
+ * `getSpawnPause()`. Mirrors the `runtimeToggles` pattern in
+ * `core/v4/runtimeToggles.ts` but does NOT route through it —
+ * runtimeToggles is config-yaml backed (no per-toggle metadata
+ * field), and the reason/pausedAt/pausedBy fields are first-class
+ * here.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpawnPauseState = void 0;
+exports.initSpawnPause = initSpawnPause;
+exports.getSpawnPause = getSpawnPause;
+exports._resetSpawnPauseForTests = _resetSpawnPauseForTests;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// ── Implementation ───────────────────────────────────────────────────────
+const MARKER_FILENAME = 'spawn.paused';
+/**
+ * File-marker-backed pause state. Concurrent processes (REPL, daemon,
+ * MCP server) all read/write the same marker, so flipping pause from
+ * a REPL slash command is observed by an MCP-mode `subagent_fanout`
+ * call within milliseconds (next read).
+ */
+class SpawnPauseState {
+    constructor(opts) {
+        this.markerPath = node_path_1.default.join(opts.aidenHome, MARKER_FILENAME);
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * Hot path — called at the top of every `spawn_sub_agent` and
+     * `subagent_fanout` invocation. MUST stay cheap (single
+     * `fs.existsSync`). The metadata read is deferred to `status()`.
+     *
+     * Any error (FS busy, permission, etc.) silently returns
+     * `false` — failing-open is the right default because a paused
+     * state that operators can't query/clear due to FS hiccups would
+     * brick the whole spawning surface.
+     */
+    isPaused() {
+        try {
+            return node_fs_1.default.existsSync(this.markerPath);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Apply the pause marker. Atomic via tmp-file + rename so a
+     * mid-write status read never sees corrupt JSON. Idempotent —
+     * pausing while already paused just overwrites the marker (which
+     * is the right semantic for "re-pause with a fresh reason").
+     */
+    pause(opts) {
+        const payload = {
+            pausedAt: this.now(),
+            reason: opts.reason ?? null,
+            pausedBy: opts.pausedBy,
+        };
+        const tmpPath = `${this.markerPath}.tmp`;
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(this.markerPath), { recursive: true });
+        node_fs_1.default.writeFileSync(tmpPath, JSON.stringify(payload), { encoding: 'utf8' });
+        node_fs_1.default.renameSync(tmpPath, this.markerPath);
+    }
+    /**
+     * Clear the pause marker. Idempotent — ENOENT (already resumed)
+     * is treated as success, so two operators calling resume back-
+     * to-back don't error on the second.
+     */
+    resume() {
+        try {
+            node_fs_1.default.unlinkSync(this.markerPath);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== 'ENOENT')
+                throw e;
+        }
+    }
+    /**
+     * Read the current pause state with metadata. When the marker
+     * exists but is unreadable / malformed JSON, returns
+     * `{paused: true}` with no metadata fields — the EXISTENCE of
+     * the marker is the durable contract; the JSON payload is best-
+     * effort forensic detail.
+     */
+    status() {
+        if (!this.isPaused()) {
+            return { paused: false };
+        }
+        let raw;
+        try {
+            raw = node_fs_1.default.readFileSync(this.markerPath, 'utf8');
+        }
+        catch {
+            return { paused: true };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return { paused: true };
+        }
+        const pausedAt = typeof parsed.pausedAt === 'number' ? parsed.pausedAt : undefined;
+        return {
+            paused: true,
+            pausedAt,
+            reason: parsed.reason ?? null,
+            pausedBy: parsed.pausedBy ?? 'unknown',
+            durationMs: pausedAt !== undefined ? Math.max(0, this.now() - pausedAt) : undefined,
+        };
+    }
+}
+exports.SpawnPauseState = SpawnPauseState;
+// ── Module-level singleton ───────────────────────────────────────────────
+let _singleton = null;
+/**
+ * Initialize the process-wide pause state. Called once at boot
+ * (REPL: `buildAgentRuntime`; daemon: dispatcher bootstrap; MCP:
+ * `wireSubagentFanout`). Subsequent calls REPLACE the singleton —
+ * tests rely on this to swap the marker dir cleanly.
+ */
+function initSpawnPause(opts) {
+    _singleton = new SpawnPauseState(opts);
+    return _singleton;
+}
+/**
+ * Read the current singleton. Throws if `initSpawnPause` hasn't
+ * been called yet — the spawn / fanout tool handlers cannot
+ * function without it, and a silent fallback to "not paused" would
+ * defeat the kill-switch's purpose. Boot wiring is responsible for
+ * calling init before any tool handler can fire.
+ *
+ * For environments that genuinely don't have a marker dir (some
+ * test contexts), call `initSpawnPause({aidenHome: <tmp>})` with
+ * a throwaway path.
+ */
+function getSpawnPause() {
+    if (!_singleton) {
+        throw new Error('spawnPause: not initialized — call initSpawnPause({aidenHome}) at boot. ' +
+            'This usually means a sub-agent tool handler fired before runtime wiring completed.');
+    }
+    return _singleton;
+}
+/**
+ * Test-only — reset the singleton so the next `initSpawnPause`
+ * call wires a fresh state. Production callers should never need
+ * this; `initSpawnPause` is already idempotent for re-init.
+ */
+function _resetSpawnPauseForTests() {
+    _singleton = null;
+}

package/dist/core/v4/subagent/spawnSubAgent.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/spawnSubAgent.ts — v4.6 Phase 1.
+ *
+ * Public spawn primitive. Synchronously runs one child agent to handle
+ * a delegated sub-task, returns a structured `SubAgentResult` envelope.
+ * NEVER throws — every error path produces an envelope with the
+ * appropriate `status` + `error` fields so the parent's LLM can
+ * reason about the failure.
+ *
+ * Contract per `docs/v4.6/phase-1-design.md` §3, §6, §8.
+ *
+ *   - Single child (Phase 1; batch is Phase 2 via subagent_fanout
+ *     refactor)
+ *   - Synchronous: the parent's tool dispatch awaits this Promise
+ *   - Cooperative cancellation: parent's AbortSignal cascades to
+ *     child via a linked AbortController
+ *   - Wall-clock timeout: hard cap via setTimeout → child interrupt
+ *   - Persistence: writes a `runs` row with `spawned_from_run_id` +
+ *     `spawned_from_session_id` linking back to the parent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnSubAgent = spawnSubAgent;
+const node_crypto_1 = require("node:crypto");
+const childBuilder_1 = require("./childBuilder");
+const factory_1 = require("../logger/factory");
+// ── Constants ─────────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 600000;
+const MIN_TIMEOUT_MS = 1000;
+const MAX_TIMEOUT_MS = 3600000;
+const DEFAULT_MAX_ITERATIONS = 50;
+const MIN_MAX_ITERATIONS = 1;
+const MAX_MAX_ITERATIONS = 200;
+// ── Implementation ────────────────────────────────────────────────────────
+/**
+ * Spawn one child agent. Always returns an envelope; never throws.
+ *
+ * Lifecycle (per §6 state machine):
+ *
+ *   1. Generate child sessionId (flat UUID).
+ *   2. Insert `runs` row with `status: 'running'` + lineage columns.
+ *   3. Build child agent (clones FallbackAdapter, intersects toolsets,
+ *      filters blocklist, fresh ApprovalEngine with auto-deny).
+ *   4. Construct linked AbortController: parent's signal feeds into
+ *      it; a setTimeout on `timeoutMs` also aborts it.
+ *   5. Run `child.runConversation(history, { signal: childCtrl.signal })`.
+ *   6. On return / throw / timeout, classify into the envelope's
+ *      status + exitReason and update the runs row's status.
+ *   7. Clean up timer + signal listener.
+ */
+async function spawnSubAgent(spec, deps, ctx) {
+    const startedAt = Date.now();
+    // ── 1. Clamp inputs ─────────────────────────────────────────────────────
+    const maxIterations = clamp(spec.maxIterations ?? DEFAULT_MAX_ITERATIONS, MIN_MAX_ITERATIONS, MAX_MAX_ITERATIONS);
+    const timeoutMs = clamp(spec.timeoutMs ?? DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    // ── 2. Fresh sessionId + run row ────────────────────────────────────────
+    const childSessionId = (0, node_crypto_1.randomUUID)();
+    // Pre-create the child run row in 'running' state so the envelope
+    // always carries a valid childRunId — even if buildChildAgent throws.
+    let childRunId;
+    try {
+        childRunId = deps.runStore.create({
+            sessionId: childSessionId,
+            instanceId: deps.instanceId,
+            status: 'running',
+            startedAt,
+            spawnedFromRunId: ctx.parentRunId,
+            spawnedFromSessionId: ctx.parentSessionId,
+        });
+    }
+    catch (err) {
+        // Persistence failed before we even started — surface as failed
+        // envelope with a synthetic id of '0' so the contract holds.
+        return failureEnvelope({
+            childRunId: '0',
+            childSessionId,
+            error: `Failed to create child run row: ${errorMessage(err)}`,
+            durationMs: Date.now() - startedAt,
+        });
+    }
+    // ── 3. Build child agent ────────────────────────────────────────────────
+    const logger = deps.logger ?? (0, factory_1.noopLogger)();
+    let agentBundle;
+    try {
+        agentBundle = (0, childBuilder_1.buildChildAgent)({
+            ...deps,
+            // v4.6 Phase 1 observability — pass runStore + childRunId
+            // through so childBuilder can wire onToolCall → run_events
+            // for the child's tool dispatches. Both are optional in
+            // ChildBuilderDeps so unit tests of buildChildAgent stay
+            // dependency-light.
+            runStore: deps.runStore,
+            childRunId,
+            logger,
+        }, {
+            sessionId: childSessionId,
+            goal: spec.goal,
+            context: spec.context,
+            requestedToolsets: spec.toolsets,
+            maxIterations,
+            // v4.6 Phase 2P — per-spawn provider override (per design doc §12.2).
+            providerOverride: spec.provider,
+        });
+    }
+    catch (err) {
+        // v4.6 Phase 2P — distinguish provider-not-found from other build
+        // failures. ProviderNotFoundError carries the failing name + the
+        // list of valid alternatives, surfaced verbatim to the LLM in the
+        // envelope so it can pick a real provider next time. Other build
+        // failures (constructor throws, registry issues, etc.) collapse
+        // to the generic 'error' exitReason.
+        if (err instanceof childBuilder_1.ProviderNotFoundError) {
+            deps.runStore.setStatus(childRunId, 'failed', { finishReason: 'provider_not_found' });
+            return {
+                ok: false,
+                status: 'failed',
+                summary: null,
+                error: err.message,
+                exitReason: 'provider_not_found',
+                metrics: { apiCalls: 0, durationMs: Date.now() - startedAt, tokensIn: 0, tokensOut: 0 },
+                childRunId: String(childRunId),
+                childSessionId,
+            };
+        }
+        deps.runStore.setStatus(childRunId, 'failed', { finishReason: 'error' });
+        return failureEnvelope({
+            childRunId: String(childRunId),
+            childSessionId,
+            error: `Failed to build child agent: ${errorMessage(err)}`,
+            durationMs: Date.now() - startedAt,
+        });
+    }
+    // v4.6 Phase 1 observability — log the child's actual tool catalog
+    // so we can see whether the toolsets-resolution path produced a
+    // sensible set or stripped everything. The single most-load-bearing
+    // diagnostic for the "child returned 0" class of bugs.
+    const childToolNames = agentBundle.agent.tools.map((t) => t.name);
+    logger.info('spawn_sub_agent child built', {
+        childRunId: String(childRunId),
+        childSessionId,
+        toolCount: childToolNames.length,
+        toolNames: childToolNames,
+        requestedToolsets: spec.toolsets ?? null,
+        maxIterations,
+        timeoutMs,
+    });
+    // ── 4. Linked AbortController ───────────────────────────────────────────
+    // Two abort sources cascade into the child's signal:
+    //   (a) parent signal aborts — child aborts.
+    //   (b) timeoutMs elapses — child aborts.
+    // Track which one fired so we can label the envelope as
+    // 'interrupted' vs 'timeout' (the spec distinguishes them).
+    const childCtrl = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        childCtrl.abort();
+    }, timeoutMs);
+    let parentAbortHandler = null;
+    if (ctx.signal) {
+        if (ctx.signal.aborted) {
+            childCtrl.abort();
+        }
+        else {
+            parentAbortHandler = () => childCtrl.abort();
+            ctx.signal.addEventListener('abort', parentAbortHandler, { once: true });
+        }
+    }
+    const cleanupAbortWiring = () => {
+        clearTimeout(timer);
+        if (parentAbortHandler && ctx.signal) {
+            ctx.signal.removeEventListener('abort', parentAbortHandler);
+        }
+    };
+    // ── 5. Run the child ─────────────────────────────────────────────────────
+    // `child.runConversation` propagates the signal into the loop's
+    // between-iteration + pre-tool-call abort checks via the prep
+    // dispatch (commit fd62f96d).
+    let summary = null;
+    let error = null;
+    let status = 'completed';
+    let exitReason = 'completed';
+    let apiCalls = 0;
+    let tokensIn = 0;
+    let tokensOut = 0;
+    try {
+        const result = await agentBundle.agent.runConversation(agentBundle.history, { signal: childCtrl.signal });
+        apiCalls = result.turnCount; // one provider call per turn
+        tokensIn = result.totalUsage.inputTokens;
+        tokensOut = result.totalUsage.outputTokens;
+        // Classify the result per design doc §8.
+        if (result.finishReason === 'interrupted') {
+            // Distinguish timeout from parent-interrupt by which source fired.
+            if (timedOut) {
+                status = 'timeout';
+                exitReason = 'timeout';
+                error = `Sub-agent timed out after ${timeoutMs}ms (maxIterations=${maxIterations})`;
+            }
+            else {
+                status = 'interrupted';
+                exitReason = 'interrupted';
+                error = 'Parent interrupted — child did not finish in time';
+            }
+        }
+        else if (result.finishReason === 'budget_exhausted') {
+            // Hit maxIterations. If the model produced a partial final reply,
+            // we ship it as a 'completed/max_iterations' (partial summary);
+            // otherwise it's a failure.
+            if (result.finalContent && result.finalContent.length > 0) {
+                status = 'completed';
+                exitReason = 'max_iterations';
+                summary = result.finalContent;
+            }
+            else {
+                status = 'failed';
+                exitReason = 'error';
+                error = `Sub-agent hit max_iterations (${maxIterations}) without producing a summary`;
+            }
+        }
+        else if (result.finishReason === 'error') {
+            status = 'failed';
+            exitReason = 'error';
+            error = 'Sub-agent loop reported an internal error';
+        }
+        else if (result.finishReason === 'tool_loop') {
+            // TCE surfaced a tool loop — treat as a failure with structured
+            // payload buried in error string (Phase 1 doesn't yet ship the
+            // capability-card detail into the envelope).
+            status = 'failed';
+            exitReason = 'error';
+            error = `Sub-agent detected a tool loop and stopped: ${result.toolLoopCard?.title ?? 'tool_loop'}`;
+        }
+        else {
+            // 'stop' → natural completion.
+            status = 'completed';
+            exitReason = 'completed';
+            summary = result.finalContent;
+        }
+    }
+    catch (err) {
+        // child.runConversation threw — typically only happens when the
+        // provider call fails after exhausting fallback chain. Surface as
+        // a failed envelope with the error string.
+        status = 'failed';
+        exitReason = 'error';
+        error = `Sub-agent threw: ${errorMessage(err)}`;
+    }
+    finally {
+        cleanupAbortWiring();
+    }
+    // ── 6. Update run row + emit envelope ────────────────────────────────────
+    const dbStatus = status === 'completed' ? 'completed'
+        : status === 'interrupted' ? 'interrupted'
+            : 'failed';
+    deps.runStore.setStatus(childRunId, dbStatus, { finishReason: exitReason });
+    const durationMs = Date.now() - startedAt;
+    const ok = status === 'completed' && exitReason !== 'error';
+    return {
+        ok,
+        status,
+        summary,
+        error,
+        exitReason,
+        metrics: {
+            apiCalls,
+            durationMs,
+            tokensIn,
+            tokensOut,
+        },
+        childRunId: String(childRunId),
+        childSessionId,
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+function clamp(n, lo, hi) {
+    if (!Number.isFinite(n))
+        return lo;
+    return Math.max(lo, Math.min(hi, Math.floor(n)));
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Build a failed envelope for pre-run errors (run-row creation,
+ * agent construction). Always carries `summary: null`, `ok: false`,
+ * `status: 'failed'`, `exitReason: 'error'`.
+ */
+function failureEnvelope(opts) {
+    return {
+        ok: false,
+        status: 'failed',
+        summary: null,
+        error: opts.error,
+        exitReason: 'error',
+        metrics: {
+            apiCalls: 0,
+            durationMs: opts.durationMs,
+            tokensIn: 0,
+            tokensOut: 0,
+        },
+        childRunId: opts.childRunId,
+        childSessionId: opts.childSessionId,
+    };
+}

package/dist/core/v4/toolRegistry.js

@@ -49,10 +49,19 @@ class ToolRegistry {
         return [...this.handlers.keys()];
     }
     /**
-     * Schemas to advertise to the LLM. When `filterToolsets` is provided,
-     * only handlers whose `toolset` matches one of the entries are returned.
+     * Schemas to advertise to the LLM. Two optional filters, AND-combined:
+     *
+     *   - `filterToolsets`: include only handlers whose `toolset` matches
+     *     one of the entries. Applied first (preserves pre-v4.6 behaviour
+     *     when called with one argument).
+     *   - `context` (v4.6 Phase 1): include only handlers whose
+     *     `contexts` array contains this value, OR whose `contexts` is
+     *     undefined (default = visible everywhere). Applied second.
+     *
+     * Both filters default to "no filter" when omitted. Callers that
+     * predate v4.6 pass one arg or none and continue working unchanged.
      */
-    getSchemas(filterToolsets) {
+    getSchemas(filterToolsets, context) {
         const out = [];
         for (const handler of this.handlers.values()) {
             if (filterToolsets && filterToolsets.length > 0) {
@@ -60,6 +69,13 @@ class ToolRegistry {
                     continue;
                 }
             }
+            if (context !== undefined) {
+                // contexts undefined → tool is visible in both REPL and daemon
+                // (backward-compat default for every pre-v4.6 tool).
+                if (handler.contexts !== undefined && !handler.contexts.includes(context)) {
+                    continue;
+                }
+            }
             out.push(handler.schema);
         }
         return out;

package/dist/core/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // AUTO-GENERATED by scripts/inject-version.js — do not edit by hand
-exports.VERSION = '4.5.0';
+exports.VERSION = '4.6.0';

package/dist/moat/plannerGuard.js

@@ -87,10 +87,39 @@ const RULES = [
         toolsets: ['execute'],
     },
     // Process registry
+    //
+    // Note: the bare word "spawn" appears in this rule's keyword list
+    // (legacy — predates v4.6 sub-agents). The dedicated 'subagent'
+    // rule below ALSO matches "spawn" via a tighter delegation
+    // vocabulary, so a message like "spawn a background server" hits
+    // BOTH rules and adds both toolsets — UNION semantics make this
+    // additive, not conflicting.
     {
         keywords: /\b(process|background|long.?running|server|spawn|kill|daemon)\b/i,
         toolsets: ['process'],
     },
+    // v4.6 Phase 1 — sub-agent delegation surface (spawn_sub_agent +
+    // subagent_fanout). Both tools live in toolset `'subagent'`, which
+    // no pre-v4.6 rule mapped to — so PlannerGuard's per-turn narrowing
+    // silently stripped them from the model's catalog whenever any
+    // other rule fired. The model could see them via lookup_tool_schema
+    // but failed to actually invoke them because the provider tool list
+    // (post-narrow) didn't include them — see Dispatch 2H diagnostic.
+    //
+    // Regex notes:
+    //   - `spawn_sub_agent` and `subagent_fanout` literals are listed
+    //     explicitly because `\bspawn\b` does NOT match within
+    //     `spawn_sub_agent` (underscore is a word char in JS regex,
+    //     so there's no word boundary between `n` and `_`). Users who
+    //     name the tool directly hit the literal arm.
+    //   - The free-form vocabulary arm (`spawn`, `delegate`, etc.)
+    //     catches natural-language delegation intent. UNION semantics
+    //     with other rules let "spawn a child to read files" surface
+    //     both 'subagent' AND 'files'.
+    {
+        keywords: /\b(spawn_sub_agent|subagent_fanout|spawn|subagent|sub.?agent|delegate|fanout|fan.?out|child.?agent|parallel|isolated)\b/i,
+        toolsets: ['subagent'],
+    },
     // Media playback control (v4.1.4-media)
     //
     // Without this, intents like "list media sessions" matched the

package/dist/providers/v4/anthropicAdapter.js

@@ -92,14 +92,14 @@ class AnthropicAdapter {
     // ── Public: 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 json = (await reply.json());
         return decodeResponse(json);
     }
     // ── Public: 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) {
             // Server promised SSE but gave us nothing — fall through to a synthetic
             // empty done event so the agent loop terminates rather than hangs.
@@ -163,7 +163,7 @@ class AnthropicAdapter {
         // beta flags, or per-deployment routing tags without forking the adapter.
         return { ...headers, ...this.extraHeaders };
     }
-    async dispatch(body, streaming) {
+    async dispatch(body, streaming, externalSignal) {
         // Resolved once per process via the userAgent module's cache, so paying
         // for the version detection here is cheap on every retry/turn.
         const userAgent = await (0, userAgent_1.getClaudeCliUserAgent)();
@@ -174,6 +174,22 @@ class AnthropicAdapter {
         for (let attempt = 0; attempt < totalTries; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            // v4.6 prep — forward an external AbortSignal into this attempt's
+            // internal controller so a parent agent that aborts mid-flight
+            // cancels the in-flight fetch. External aborts surface as a raw
+            // AbortError (NOT ProviderTimeoutError) so AidenAgent can route
+            // them as `finishReason: 'interrupted'` instead of treating them
+            // as a retryable timeout.
+            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, {
@@ -185,7 +201,16 @@ class AnthropicAdapter {
             }
             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. Surface the raw AbortError immediately (no retry)
+                    // so AidenAgent's catch routes it as 'interrupted'.
+                    if (externalSignal?.aborted) {
+                        throw err;
+                    }
                     // Treat timeout as retryable; only surface ProviderTimeoutError if
                     // we've burned the last attempt.
                     lastErr = new errors_1.ProviderTimeoutError(this.providerName, this.timeoutMs);
@@ -200,6 +225,9 @@ class AnthropicAdapter {
                 throw lastErr;
             }
             clearTimeout(timer);
+            if (externalAbortHandler && externalSignal) {
+                externalSignal.removeEventListener('abort', externalAbortHandler);
+            }
             if (response.ok)
                 return response;
             // Phase 25.1.5d diagnostic: gated dump of request + response so we