@aitne/daemon 0.1.0

package/dist/core/backends/claude-code-core.js

@@ -0,0 +1,2541 @@
+import { query, } from "@anthropic-ai/claude-agent-sdk";
+import { collectSessionDeniedTools, INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, isAutonomousProcessKey, matchRunAllowedToolPattern, } from "@aitne/shared";
+import { readIntegrations } from "../../db/integrations-store.js";
+import { buildExecutionPrompt, buildSummaryPrompt, } from "./prompt-utils.js";
+import { homedir } from "node:os";
+import { resolve as resolvePath, isAbsolute } from "node:path";
+import { getContextDir } from "../../config.js";
+import { materializeMcpForSession } from "../../services/mcp/session-materializer.js";
+import { parseMcpToolName } from "../../services/mcp/risk.js";
+import { logMcpToolCall, updateMcpToolCallResult } from "../../services/mcp/tool-audit.js";
+import { BackendQuotaError, BackendDecisiveFailure, DelegatedProxyTimeoutError, classifyAbortReason, } from "../agent-core.js";
+import { IdleWatchdog } from "./idle-watchdog.js";
+import { DELEGATED_PROXY_DEFAULTS } from "../../services/delegated-proxy-config.js";
+import { buildDelegatedToolPrompt, emptyCost, flattenToolResultContent, tryParseToolResult, withDurationMs, } from "../../services/delegated-tool-runtime.js";
+import { createSessionWorkdir, cleanupSessionWorkdir } from "../workdir.js";
+import { buildDaemonApiCliEnv } from "../daemon-api-cli.js";
+import { createLogger } from "../../logging.js";
+import { DEFAULT_CLAUDE_HIGH_MODEL, DEFAULT_CLAUDE_MEDIUM_MODEL, findRegisteredModel, getModelsForBackend, } from "./model-registry.js";
+import { readClaudeCredentials } from "./claude-credentials-store.js";
+import { ALWAYS_DISALLOWED_TOOLS, classifyAbsoluteBlock, } from "../../safety/always-disallowed.js";
+import { recordAbsoluteBlockAudit } from "../../safety/absolute-block-audit.js";
+import { isPathInsideOrEqual, shellPathForms, } from "../path-compat.js";
+import { CliPathCache, isPlausibleAnthropicApiKey } from "./cli-utils.js";
+import { probeApiKeyServerSide } from "./api-key-probe.js";
+import { extractSilentApiErrors, logSilentApiErrors, } from "./silent-api-error-detector.js";
+const logger = createLogger("claude-code-core");
+/**
+ * Detect which cloud-provider mode the Claude Code SDK is currently
+ * configured for, based on the documented `CLAUDE_CODE_USE_*` env flags.
+ * Returns null when running in the default direct-API-key / OAuth mode.
+ *
+ * Required-env spec follows the official Claude Code docs (verified
+ * 2026-05):
+ *  - **Bedrock** — only `AWS_REGION` is required by Claude Code itself
+ *    (the docs explicitly call this out). AWS credentials flow through
+ *    the SDK's default credential chain, which can come from any of
+ *    AWS_ACCESS_KEY_ID/SECRET, AWS_BEARER_TOKEN_BEDROCK, AWS_PROFILE, or
+ *    `~/.aws/`. Requiring access-key + secret here would falsely fail
+ *    bearer-token / profile setups.
+ *  - **Vertex** — `ANTHROPIC_VERTEX_PROJECT_ID` + `CLOUD_ML_REGION`.
+ *    GCP credentials flow through ADC, which can be `gcloud auth
+ *    application-default login` or a `GOOGLE_APPLICATION_CREDENTIALS`
+ *    file path; we don't require either at this layer.
+ *  - **Foundry** — `ANTHROPIC_FOUNDRY_RESOURCE` OR
+ *    `ANTHROPIC_FOUNDRY_BASE_URL`. The API key is optional; without it,
+ *    Claude Code uses the Azure DefaultAzureCredential chain.
+ *
+ * The SDK reads these flags itself; the daemon only inspects them so
+ * the auth probes (`checkAuth` / `checkAuthDetailed`) can return the
+ * right `method` and skip the Anthropic-API probe (which would 401
+ * against a Bedrock / Vertex / Foundry deployment).
+ */
+function detectCloudProviderEnv() {
+    if (process.env.CLAUDE_CODE_USE_BEDROCK?.trim() === "1") {
+        const missing = [];
+        if (!process.env.AWS_REGION?.trim())
+            missing.push("AWS_REGION");
+        return {
+            method: "bedrock",
+            flagEnvVar: "CLAUDE_CODE_USE_BEDROCK",
+            label: "Amazon Bedrock",
+            missing,
+        };
+    }
+    if (process.env.CLAUDE_CODE_USE_VERTEX?.trim() === "1") {
+        const required = [
+            "ANTHROPIC_VERTEX_PROJECT_ID",
+            "CLOUD_ML_REGION",
+        ];
+        return {
+            method: "vertex",
+            flagEnvVar: "CLAUDE_CODE_USE_VERTEX",
+            label: "Google Vertex AI",
+            missing: required.filter((name) => !process.env[name]?.trim()),
+        };
+    }
+    if (process.env.CLAUDE_CODE_USE_FOUNDRY?.trim() === "1") {
+        const hasResource = Boolean(process.env.ANTHROPIC_FOUNDRY_RESOURCE?.trim());
+        const hasBaseUrl = Boolean(process.env.ANTHROPIC_FOUNDRY_BASE_URL?.trim());
+        return {
+            method: "foundry",
+            flagEnvVar: "CLAUDE_CODE_USE_FOUNDRY",
+            label: "Microsoft Foundry",
+            missing: hasResource || hasBaseUrl
+                ? []
+                : ["ANTHROPIC_FOUNDRY_RESOURCE or ANTHROPIC_FOUNDRY_BASE_URL"],
+        };
+    }
+    return null;
+}
+// Probe data is derived from `INTEGRATION_DESCRIPTORS.backendConnectors.claude`
+// at module init, so adding a new delegated integration only requires the
+// registry update — the prompt, prefix list, and tool-name regex follow
+// automatically. Before this was registry-driven, every new integration
+// silently broke its own probe (`present` permanently false) until someone
+// remembered to edit four constants in lockstep. See
+// `docs/design/17-delegated-mode-v2.md` §7.1.
+//
+// Tool names span two character classes:
+//   - Gmail / Calendar: `search_threads`, `list_events` (snake_case only)
+//   - Notion:           `notion-search`, `notion-create-pages` (kebab-case)
+// The trailing `[A-Za-z0-9_-]+` class covers both. Namespace strings are
+// regex-escaped because Codex (`._`) and Gemini (`.`) namespaces contain
+// metacharacters.
+function buildClaudeProbeData() {
+    const meta = [];
+    for (const key of INTEGRATION_KEYS) {
+        const descriptor = INTEGRATION_DESCRIPTORS[key];
+        const connector = descriptor.backendConnectors.claude;
+        if (!connector)
+            continue;
+        const seen = new Set();
+        for (const tools of Object.values(connector.capabilityTools)) {
+            for (const t of tools)
+                seen.add(t);
+        }
+        meta.push({
+            displayName: descriptor.displayName,
+            toolNamespace: connector.toolNamespace,
+            requiredCapabilities: connector.requiredCapabilities,
+            capabilityToolNames: Array.from(seen),
+        });
+    }
+    const prefixes = meta.map((m) => m.toolNamespace);
+    const lines = ["Use `ToolSearch` only."];
+    for (const m of meta) {
+        // Keyword query: display name + required capability words split on
+        // `_` / `-`. Mirrors the pre-registry-driven prompts (Gmail used
+        // `'Gmail search read draft label'`, Calendar used `'Google Calendar
+        // list get create update delete event'`) — both are display name +
+        // requiredCapabilities expanded into word tokens. Using the
+        // capability set (semantic) rather than every capability tool name
+        // (mechanical) keeps ToolSearch's token-overlap ranking sharp; a
+        // bag-of-tool-name-fragments query dilutes the signal across
+        // ~15-30 tokens per integration and demotes the actually-relevant
+        // hits.
+        const queryWords = [
+            m.displayName,
+            ...m.requiredCapabilities.flatMap((c) => c.split(/[-_]/)),
+        ]
+            .join(" ")
+            .replace(/\s+/g, " ")
+            .trim();
+        lines.push(`Search for ${m.displayName} connector tools with query '${queryWords}' and max_results 20.`);
+    }
+    lines.push("Do not call any of the searched MCP tools.");
+    lines.push(`After the searches, print every full tool name returned that starts with one of: ${prefixes
+        .map((p) => `'${p}'`)
+        .join(", ")}.`);
+    // Per-integration "must include" hints: ToolSearch caps results at
+    // max_results, so lower-ranked tools (e.g. Gmail's label_* family) can
+    // be missed by keyword search. Listing them explicitly nudges the agent
+    // to print them when they do appear in any of the searches above.
+    for (const m of meta) {
+        if (m.capabilityToolNames.length === 0)
+            continue;
+        const fullNames = m.capabilityToolNames
+            .map((n) => m.toolNamespace + n)
+            .join(", ");
+        lines.push(`Include these ${m.displayName} tools if present: ${fullNames}.`);
+    }
+    lines.push("One tool name per line. No markdown fences. No explanation. If no such tools are available, print NONE.");
+    // Defense: an empty prefix list would compile to `\b(?:)[A-Za-z0-9_-]+\b`,
+    // which matches any word — every connector probe would falsely "succeed".
+    // Realistically `INTEGRATION_DESCRIPTORS` is non-empty, but the guard
+    // keeps a future registry rollback from corrupting probe semantics.
+    const escapedPrefixes = prefixes.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    const regex = escapedPrefixes.length === 0
+        ? /(?!)/g
+        : new RegExp(`\\b(?:${escapedPrefixes.join("|")})[A-Za-z0-9_-]+\\b`, "g");
+    return { prompt: lines.join(" "), prefixes, regex };
+}
+const CLAUDE_PROBE_DATA = buildClaudeProbeData();
+export const CLAUDE_PROBE_TOOLS_PROMPT = CLAUDE_PROBE_DATA.prompt;
+const CLAUDE_PROBE_TOOL_PREFIXES = CLAUDE_PROBE_DATA.prefixes;
+const CLAUDE_CONNECTOR_TOOL_RE = CLAUDE_PROBE_DATA.regex;
+/**
+ * The built-in Claude Code tool that loads schemas for deferred MCP tools.
+ * When a session inherits many MCP servers from the user's global config,
+ * the CLI defers a portion of the tool schemas; the model must call
+ * `ToolSearch` to bring a specific tool's schema into the working set
+ * before invoking it. The proxy explicitly allows it (see runDelegatedTool)
+ * and the stream parser excludes it from `wrongToolName` capture so a
+ * partial-trace failure (`ToolSearch` + max_turns before the connector
+ * call) classifies as `no_tool_call` rather than the misleading
+ * `wrong_tool=ToolSearch`.
+ */
+const DEFERRED_TOOL_DISCOVERY_TOOL_NAME = "ToolSearch";
+/**
+ * Registry-driven allowlist entries for integrations currently delegated to
+ * Claude. Under `permissionMode: "dontAsk"`, any tool not in the SDK's
+ * `allowedTools` is silently denied — so a delegated Gmail / Calendar
+ * integration whose skill instructs the agent to call
+ * `mcp__claude_ai_Gmail__search_threads` will fail with "permission denied"
+ * unless that exact tool name is pre-authorized here.
+ *
+ * Pure over `(integrations)` — callers pass the record read from
+ * `db/integrations-store.ts#readIntegrations`. The SDK's MCP tool matcher is
+ * literal (`mcp__<server>__<tool>` — see `services/mcp/risk.ts`), so we
+ * enumerate every capability tool the registry declares rather than using a
+ * wildcard. This guarantees the allowlist only widens by what the registry
+ * explicitly advertises; adding a new connector tool demands a registry
+ * update first.
+ *
+ * Only integrations whose `delegatedBackend === "claude"` contribute — a
+ * Codex-delegated Gmail integration must not widen Claude's surface.
+ */
+export function computeDelegatedClaudeTools(integrations) {
+    const out = new Set();
+    for (const key of INTEGRATION_KEYS) {
+        const state = integrations[key];
+        if (!state || state.mode !== "delegated")
+            continue;
+        if (state.delegatedBackend !== "claude")
+            continue;
+        const connector = INTEGRATION_DESCRIPTORS[key].backendConnectors.claude;
+        if (!connector)
+            continue;
+        for (const toolNames of Object.values(connector.capabilityTools)) {
+            for (const toolName of toolNames) {
+                out.add(connector.toolNamespace + toolName);
+            }
+        }
+    }
+    return Array.from(out);
+}
+export class AgentTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Agent execution exceeded timeout of ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = "AgentTimeoutError";
+    }
+}
+export function isClaudeCodeQuotaError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const maybeRecord = error;
+    const message = error.message.toLowerCase();
+    const code = typeof maybeRecord.code === "string" ? maybeRecord.code.toLowerCase() : "";
+    const type = typeof maybeRecord.type === "string" ? maybeRecord.type.toLowerCase() : "";
+    if (maybeRecord.status === 429) {
+        return true;
+    }
+    if (code.includes("rate") || code.includes("quota")) {
+        return true;
+    }
+    if (type.includes("rate") || type.includes("quota")) {
+        return true;
+    }
+    return /rate.?limit|quota|too many requests|you['']?\s*ve hit your limit/.test(message);
+}
+export function isClaudeCodeMaxBudgetError(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : "";
+    const code = typeof error === "object" && error !== null && typeof error.code === "string"
+        ? error.code
+        : "";
+    const type = typeof error === "object" && error !== null && typeof error.type === "string"
+        ? error.type
+        : "";
+    return /max(?:imum)? budget|max_budget_usd|budget limit|per-turn budget/i.test(`${message} ${code} ${type}`);
+}
+export function extractClaudeCodeQuotaResetHint(error) {
+    if (!(error instanceof Error)) {
+        return null;
+    }
+    const match = /resets?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*(?:\(([^)]+)\))?/i.exec(error.message);
+    if (!match) {
+        return null;
+    }
+    const rawHour = Number(match[1]);
+    const meridiem = match[3].toLowerCase();
+    let hour = rawHour % 12;
+    if (meridiem === "pm") {
+        hour += 12;
+    }
+    return {
+        hour,
+        minute: match[2] ? Number(match[2]) : 0,
+        timeZone: match[4]?.trim() || undefined,
+        rawLabel: error.message.slice(match.index).replace(/^resets?\s+/i, "").trim(),
+    };
+}
+/**
+ * ClaudeCodeCore intentionally does NOT run a pre-flight `checkAuth()`
+ * gate inside `execute()` / `runTurn()`. Codex and Gemini each call
+ * `await this.checkAuth()` at the top of `runTurn()` as a cheap way
+ * to surface an early `BackendDecisiveFailure("auth")` before paying
+ * the latency of spawning the CLI subprocess; Claude uses the
+ * `@anthropic-ai/claude-agent-sdk` stream consumer instead, and the
+ * SDK's first HTTP round-trip already returns a decisive 401 on its
+ * own. A pre-flight here would duplicate work (two credential reads
+ * per execute) and isn't needed to prevent accidental token use —
+ * the reactive path in `BackendRouter` catches the SDK's 401, maps
+ * it to `BackendDecisiveFailure("auth")`, and calls
+ * `recordReactiveAuthFailure` exactly as if a pre-flight had run.
+ *
+ * This asymmetry is deliberate and matched by the corresponding
+ * explanatory comments at `codex-core.ts` / `gemini-cli-core.ts`'s
+ * `runTurn` pre-flight and at `IAgentCore.checkAuth` in
+ * `agent-core.ts`. If you add a new backend, decide the pre-flight
+ * question based on the CLI / SDK's own startup cost, not on
+ * pattern-matching against one of the existing three.
+ */
+export class ClaudeCodeCore {
+    config;
+    writeTracker;
+    backendId = "claude";
+    static RETRY_DELAY_MS = 5 * 60 * 1000;
+    static MAX_RETRIES = 1;
+    // Lazily re-resolved with a 60 s TTL so CLI install/uninstall is
+    // detected without a daemon restart (roadmap §9.4). Constructor does an
+    // eager PATH scan so the first checkAuth() call has no extra latency.
+    cliPathCache;
+    /** Legacy shared read token injected into the Claude subprocess env. */
+    readToken;
+    /** Scoped token manager preferred over the legacy shared read token. */
+    readTokenManager;
+    /** B-003 Phase 3 — DB + blob store for per-session MCP materialization. */
+    mcpContext;
+    /** Transparent getter — all existing `this.cliPath` references keep working. */
+    get cliPath() {
+        return this.cliPathCache.get();
+    }
+    constructor(config, 
+    /**
+     * Shared AgentWriteTracker. When present, the Write/Edit PreToolUse hook
+     * pre-marks vault-scoped writes so the ObsidianWatcher attributes the
+     * resulting chokidar event to `actor='agent'` instead of `'user'`. Without
+     * this wiring, the hourly_check dispatcher would re-discover the agent's
+     * own vault writes every cycle and loop.
+     */
+    writeTracker) {
+        this.config = config;
+        this.writeTracker = writeTracker;
+        this.warnOnMissingCriticalTools();
+        this.cliPathCache = new CliPathCache("claude");
+    }
+    /** Set the per-daemon-boot read token for subprocess-local daemon API auth. */
+    setReadToken(token) {
+        this.readToken = token;
+    }
+    setReadTokenManager(manager) {
+        this.readTokenManager = manager;
+    }
+    setMcpContext(context) {
+        this.mcpContext = context;
+        logger.info({ backendId: this.backendId }, "MCP context wired — delegated-integration allowlist resolution enabled");
+    }
+    /**
+     * Load the per-session MCP materialization. When the core hasn't been
+     * wired with a context (tests, startup ordering) we return an empty
+     * result rather than throwing — equivalent to "no enabled servers".
+     */
+    async materializeMcp(sessionDir, processKey) {
+        if (!this.mcpContext) {
+            return {
+                servers: [],
+                env: {},
+                configPath: null,
+                claudeMcpServers: null,
+                disallowedTools: [],
+            };
+        }
+        // Allow mode bypasses the approve-tier MCP strip that autonomous
+        // process keys normally trigger — "strong permission mode" means every
+        // MCP is reachable, including routines that would otherwise have
+        // `slack_send_message` et al stripped.
+        const allowMode = this.config.claudeExecutionPermissionMode === "allow";
+        const autonomous = !allowMode && (processKey ? isAutonomousProcessKey(processKey) : false);
+        return materializeMcpForSession({
+            db: this.mcpContext.db,
+            blobStore: this.mcpContext.blobStore,
+            sessionDir,
+            backendId: this.backendId,
+            autonomous,
+            contextDir: getContextDir(this.config),
+        });
+    }
+    /**
+     * Tools the reactive DM path depends on. If `allowedToolsOverride` is set
+     * but drops any of these, sessions will silently deny them under
+     * `permissionMode: "dontAsk"` and the owner will see a misleading
+     * "restricted" error. See BUG-DM-BACKEND-PERMISSIONS.md §9 (Fix 1a).
+     */
+    static CRITICAL_OVERRIDE_TOOLS = ["Skill", "Bash(jq *)"];
+    /**
+     * Pure computation: which of the CRITICAL_OVERRIDE_TOOLS are missing from
+     * the current `allowedToolsOverride`. Returns `[]` when the override is
+     * unset (the default allowlist already contains all critical tools).
+     */
+    getMissingCriticalOverrideTools() {
+        const override = this.config.allowedToolsOverride;
+        if (!override)
+            return [];
+        return ClaudeCodeCore.CRITICAL_OVERRIDE_TOOLS.filter((tool) => !override.includes(tool));
+    }
+    /**
+     * `allowedToolsOverride` REPLACES the default allowlist (it does not merge).
+     * Emit a one-shot warning at construction so a mis-configuration surfaces
+     * in the daemon log instead of a confusing DM reply.
+     */
+    warnOnMissingCriticalTools() {
+        // In allow mode neither the override nor the default allowlist applies —
+        // the SDK runs under bypassPermissions, so a missing Skill / Bash(jq *)
+        // entry in the override is cosmetic. Suppress the warning.
+        if (this.config.claudeExecutionPermissionMode === "allow")
+            return;
+        const missing = this.getMissingCriticalOverrideTools();
+        if (missing.length === 0)
+            return;
+        logger.warn({
+            missing,
+            overrideSize: this.config.allowedToolsOverride?.length ?? 0,
+        }, "allowedToolsOverride is set but missing critical tools. " +
+            "The reactive DM path calls user skills and jq pipelines; without these " +
+            "the session will deny them with 'dontAsk' and respond to the owner with " +
+            "a misleading 'restricted' message. Either append the missing entries to " +
+            "the override, or clear the override to fall back to the default allowlist.");
+    }
+    /**
+     * Translate the Aitne advisor config into the SDK `options.settings`
+     * shape. `advisorModel` is a field on `Settings`, not on `Options` — the
+     * query() parameter must be passed inside a `settings` object.
+     *
+     * Returns an empty object when advisor is disabled so we don't clobber any
+     * settings source that would otherwise load.
+     */
+    buildAdvisorSettings() {
+        if (!this.config.advisorEnabled || !this.config.advisorModel) {
+            return {};
+        }
+        return {
+            settings: {
+                advisorModel: this.config.advisorModel,
+            },
+        };
+    }
+    buildSystemPrompt() {
+        // Character is NOT appended here — Phase 2 of the Character feature
+        // (see docs/design/15-character.md §15.4.3) moved the injection into
+        // the rendered CLAUDE.md so Claude / Codex / Gemini see a byte-
+        // identical block. The remaining append is the WhatsApp-prefix
+        // operational note, which is byte-stable per-session and therefore
+        // cache-friendly.
+        const appendParts = [
+            "WhatsApp outbound messages are prefixed by the daemon. Do not add that prefix yourself unless the user explicitly asks.",
+        ];
+        return {
+            type: "preset",
+            preset: "claude_code",
+            append: appendParts.join("\n"),
+            // Strip per-session dynamic sections (cwd, auto-memory path, git
+            // status) from the cached system prompt prefix. The content is
+            // re-injected as the first user message so the model still sees it,
+            // but the system prompt becomes byte-identical across sessions —
+            // enabling inter-session prompt cache hits within the 5-minute TTL.
+            // Biggest wins: back-to-back routines (morning_routine + roadmap_refresh
+            // + post-morning catchups) and retry chains where the second session
+            // starts within minutes of the first.
+            //
+            // Limitation: the SDK still reads CLAUDE.md and .claude/skills/ from
+            // cwd at session init. Different event types use different profiles
+            // (routine.md vs conversational.md) and skill subsets, so the file
+            // layer differs across event types → no cross-event-type cache hit.
+            // This flag only helps same-type back-to-back sessions.
+            excludeDynamicSections: true,
+        };
+    }
+    /**
+     * Expand CLI-style aliases ("opus", "sonnet") to their current canonical
+     * API IDs. Unrecognised strings pass through unchanged so custom or
+     * fine-tuned model IDs reach the SDK verbatim.
+     *
+     * NOTE: `"opus"` now resolves to Opus 4.7 (previously 4.6). Legacy
+     * `agent_schedule.model = 'opus'` rows will silently route to 4.7 on the
+     * next dispatch — intentional, since the alias means "latest Opus".
+     */
+    resolveActualModelId(modelId) {
+        if (modelId === "opus") {
+            return DEFAULT_CLAUDE_HIGH_MODEL;
+        }
+        if (modelId === "sonnet") {
+            return DEFAULT_CLAUDE_MEDIUM_MODEL;
+        }
+        return modelId;
+    }
+    async execute(params, streamCallbacks) {
+        return await this.runWithRetry(() => this.executeOnce(params, streamCallbacks), { eventType: params.event.type, modelId: params.modelId });
+    }
+    async executeOnce(params, streamCallbacks) {
+        const { prompt, context, event, modelId, maxTurns, maxBudgetUsd, sessionDir, persistSession = false, conversationHistory, webSearchEnabled = false, } = params;
+        const fullPrompt = buildExecutionPrompt(prompt, context, event, conversationHistory);
+        const startMs = Date.now();
+        const actualModelId = this.resolveActualModelId(modelId);
+        // If caller provided a persistent sessionDir, use it (non-DM Opus sessions
+        // that may be resumed later). Otherwise create a disposable temp dir.
+        // The disposable path also receives user skills so agent DMs that don't
+        // take the persistent-workdir path can still discover user-authored skills.
+        const useSessionDir = sessionDir ?? createSessionWorkdir(this.config.workspaceDir, event.type, `${this.config.dataDir}/skills`, {
+            backendId: this.backendId,
+            processKey: params.processKey,
+            character: this.config.character,
+        });
+        const isOwnedTempDir = !sessionDir;
+        const daemonReadToken = this.readTokenManager?.issue(useSessionDir) ?? this.readToken;
+        const mcp = await this.materializeMcp(useSessionDir, params.processKey);
+        const delegatedTools = this.getDelegatedClaudeTools();
+        const sessionDeniedTools = this.getSessionDeniedTools();
+        logger.info({
+            eventType: event.type,
+            model: actualModelId,
+            maxTurns,
+            promptLen: fullPrompt.length,
+            mcpServers: mcp.servers.map((s) => s.id),
+            delegatedToolCount: delegatedTools.length,
+            sessionDeniedToolCount: sessionDeniedTools.length,
+        }, "Agent execute started");
+        try {
+            const allowMode = this.config.claudeExecutionPermissionMode === "allow";
+            // P22 §3.4 step 4 — when the dispatcher pins a per-execute
+            // `allowedToolsOverride`, suspend Allow mode for this run: the
+            // optimizer agent must NOT receive `bypassPermissions`, regardless
+            // of the operator's per-backend Execution Mode setting. We swap
+            // back to strict `dontAsk` + the explicit allowedTools list. The
+            // ALWAYS_DISALLOWED_TOOLS layer still applies.
+            const optimizerClampActive = Array.isArray(params.allowedToolsOverride) && params.allowedToolsOverride.length > 0;
+            const stream = query({
+                prompt: fullPrompt,
+                options: {
+                    model: actualModelId,
+                    maxTurns,
+                    maxBudgetUsd,
+                    effort: actualModelId.includes("opus") ? "high" : "medium",
+                    cwd: useSessionDir,
+                    env: {
+                        ...buildDaemonApiCliEnv(useSessionDir, this.config.apiPort, {
+                            readToken: daemonReadToken,
+                            sessionBackend: "claude",
+                            sessionId: params.sessionDbId,
+                            eventCorrelationId: event.correlationId,
+                        }),
+                        ...mcp.env,
+                        ...(params.turnToken ? { PA_TURN_TOKEN: params.turnToken } : {}),
+                    },
+                    systemPrompt: this.buildSystemPrompt(),
+                    ...(optimizerClampActive
+                        ? {
+                            permissionMode: "dontAsk",
+                            allowedTools: [...params.allowedToolsOverride],
+                            disallowedTools: [
+                                ...ALWAYS_DISALLOWED_TOOLS,
+                                ...this.config.disallowedTools,
+                                ...mcp.disallowedTools,
+                                ...sessionDeniedTools,
+                            ],
+                        }
+                        : allowMode
+                            ? {
+                                permissionMode: "bypassPermissions",
+                                allowDangerouslySkipPermissions: true,
+                                disallowedTools: [
+                                    ...ALWAYS_DISALLOWED_TOOLS,
+                                    ...mcp.disallowedTools,
+                                    ...sessionDeniedTools,
+                                ],
+                            }
+                            : {
+                                permissionMode: "dontAsk",
+                                allowedTools: this.getAllowedTools(webSearchEnabled, delegatedTools),
+                                disallowedTools: [
+                                    ...ALWAYS_DISALLOWED_TOOLS,
+                                    ...this.config.disallowedTools,
+                                    ...mcp.disallowedTools,
+                                    ...sessionDeniedTools,
+                                ],
+                            }),
+                    ...(mcp.claudeMcpServers
+                        ? {
+                            mcpServers: mcp.claudeMcpServers,
+                        }
+                        : {}),
+                    hooks: this.getSecurityHooks(allowMode),
+                    persistSession,
+                    includePartialMessages: !!streamCallbacks,
+                    ...this.buildAdvisorSettings(),
+                },
+            });
+            const result = await this.withTimeout(stream, () => this.consumeStream(stream, actualModelId, startMs, streamCallbacks, event.type), this.config.executeTimeoutMinutes);
+            logger.info({ eventType: event.type, model: actualModelId, durationMs: result.durationMs, costUsd: result.costUsd, numTurns: result.numTurns, isError: result.isError }, "Agent execute completed");
+            return result;
+        }
+        catch (err) {
+            logger.error({ err, eventType: event.type, model: actualModelId, durationMs: Date.now() - startMs }, "Agent execute failed");
+            throw err;
+        }
+        finally {
+            if (isOwnedTempDir) {
+                this.readTokenManager?.revoke(useSessionDir);
+            }
+            // Only clean up temp dirs we created; caller-owned dirs have their own lifecycle
+            if (isOwnedTempDir) {
+                cleanupSessionWorkdir(useSessionDir);
+            }
+        }
+    }
+    async executeResume(params, streamCallbacks) {
+        return await this.runWithRetry(() => this.executeResumeOnce(params, streamCallbacks), { sessionId: params.sessionId, modelId: params.modelId });
+    }
+    async executeResumeOnce(params, streamCallbacks) {
+        const { sessionId, message, modelId, sessionDir, webSearchEnabled = false } = params;
+        const startMs = Date.now();
+        const actualModelId = this.resolveActualModelId(modelId);
+        const isOpusTier = actualModelId.includes("opus");
+        const maxTurns = params.maxTurns ?? (isOpusTier ? 300 : 50);
+        const maxBudgetUsd = params.maxBudgetUsd ?? (isOpusTier ? 5.0 : 1.0);
+        if (!sessionDir) {
+            throw new Error("sessionDir is required for executeResume — SDK stores session history per-cwd");
+        }
+        const daemonReadToken = this.readTokenManager?.issue(sessionDir) ?? this.readToken;
+        // Resume is always a reactive DM continuation (owner in the loop), so the
+        // approve-tier MCP strip stays off even for otherwise-autonomous process
+        // keys. `materializeMcp` short-circuits on no context / no servers.
+        const mcp = await this.materializeMcp(sessionDir, undefined);
+        const delegatedTools = this.getDelegatedClaudeTools();
+        const sessionDeniedTools = this.getSessionDeniedTools();
+        logger.info({
+            sessionId,
+            model: actualModelId,
+            maxTurns,
+            mcpServers: mcp.servers.map((s) => s.id),
+            delegatedToolCount: delegatedTools.length,
+            sessionDeniedToolCount: sessionDeniedTools.length,
+        }, "Agent resume started");
+        // Use the same cwd as the original execute() so the SDK can find
+        // the session history (stored per-cwd in ~/.claude/projects/).
+        const allowMode = this.config.claudeExecutionPermissionMode === "allow";
+        const stream = query({
+            prompt: message,
+            options: {
+                resume: sessionId,
+                maxTurns,
+                maxBudgetUsd,
+                cwd: sessionDir,
+                env: {
+                    ...buildDaemonApiCliEnv(sessionDir, this.config.apiPort, {
+                        readToken: daemonReadToken,
+                        sessionBackend: "claude",
+                        sessionId: params.sessionDbId,
+                        eventCorrelationId: params.eventCorrelationId,
+                    }),
+                    ...mcp.env,
+                    ...(params.turnToken ? { PA_TURN_TOKEN: params.turnToken } : {}),
+                },
+                systemPrompt: this.buildSystemPrompt(),
+                ...(allowMode
+                    ? {
+                        permissionMode: "bypassPermissions",
+                        allowDangerouslySkipPermissions: true,
+                        disallowedTools: [
+                            ...ALWAYS_DISALLOWED_TOOLS,
+                            ...mcp.disallowedTools,
+                            ...sessionDeniedTools,
+                        ],
+                    }
+                    : {
+                        permissionMode: "dontAsk",
+                        allowedTools: this.getAllowedTools(webSearchEnabled, delegatedTools),
+                        disallowedTools: [
+                            ...ALWAYS_DISALLOWED_TOOLS,
+                            ...this.config.disallowedTools,
+                            ...mcp.disallowedTools,
+                            ...sessionDeniedTools,
+                        ],
+                    }),
+                ...(mcp.claudeMcpServers
+                    ? { mcpServers: mcp.claudeMcpServers }
+                    : {}),
+                hooks: this.getSecurityHooks(allowMode),
+                includePartialMessages: !!streamCallbacks,
+                ...this.buildAdvisorSettings(),
+            },
+        });
+        return await this.withTimeout(stream, () => this.consumeStream(stream, actualModelId, startMs, streamCallbacks, "message.received"), this.config.executeTimeoutMinutes);
+    }
+    async runWithRetry(fn, context) {
+        let lastError;
+        for (let attempt = 0; attempt <= ClaudeCodeCore.MAX_RETRIES; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < ClaudeCodeCore.MAX_RETRIES &&
+                    this.isRetryableExecutionError(error)) {
+                    logger.warn({
+                        ...context,
+                        attempt: attempt + 1,
+                        maxRetries: ClaudeCodeCore.MAX_RETRIES,
+                        error: this.getErrorMessage(error),
+                    }, "Retrying Claude backend after transient failure");
+                    await this.sleep(ClaudeCodeCore.RETRY_DELAY_MS);
+                    continue;
+                }
+                throw this.classifyExecutionError(error);
+            }
+        }
+        throw this.classifyExecutionError(lastError);
+    }
+    isRetryableExecutionError(error) {
+        if (error instanceof BackendQuotaError ||
+            error instanceof BackendDecisiveFailure) {
+            return false;
+        }
+        if (error instanceof AgentTimeoutError) {
+            return true;
+        }
+        if (isClaudeCodeQuotaError(error)) {
+            return false;
+        }
+        const status = this.getErrorStatus(error);
+        if (typeof status === "number" && status >= 500) {
+            return true;
+        }
+        const code = this.getErrorCode(error)?.toUpperCase();
+        if (code &&
+            ["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "EPIPE", "ECONNABORTED", "ENOTFOUND"].includes(code)) {
+            return true;
+        }
+        return /network error|fetch failed|socket hang up|connection reset|timed out/i.test(this.getErrorMessage(error));
+    }
+    /** Visible for testing. */
+    classifyExecutionError(error) {
+        if (error instanceof BackendQuotaError ||
+            error instanceof BackendDecisiveFailure) {
+            return error;
+        }
+        const quotaError = this.toBackendQuotaError(error);
+        if (quotaError) {
+            return quotaError;
+        }
+        if (error instanceof AgentTimeoutError) {
+            return new BackendDecisiveFailure(this.backendId, "timeout", error);
+        }
+        if (this.isAuthError(error)) {
+            return new BackendDecisiveFailure(this.backendId, "auth", error);
+        }
+        return new BackendDecisiveFailure(this.backendId, "other_non_retryable", error);
+    }
+    toBackendQuotaError(error) {
+        if (isClaudeCodeMaxBudgetError(error)) {
+            return new BackendQuotaError(this.backendId, "max_budget_usd", null, this.getErrorMessage(error));
+        }
+        if (!isClaudeCodeQuotaError(error)) {
+            return null;
+        }
+        const hint = extractClaudeCodeQuotaResetHint(error);
+        return new BackendQuotaError(this.backendId, this.getErrorCode(error) ?? "rate_limited", hint ? this.toBackendQuotaResetHint(hint) : null, this.getErrorMessage(error));
+    }
+    toBackendQuotaResetHint(hint) {
+        return {
+            hour: hint.hour,
+            minute: hint.minute,
+            timeZone: hint.timeZone,
+            rawLabel: hint.rawLabel,
+        };
+    }
+    isAuthError(error) {
+        const status = this.getErrorStatus(error);
+        if (status === 401 || status === 403) {
+            return true;
+        }
+        const code = this.getErrorCode(error)?.toLowerCase() ?? "";
+        const type = this.getErrorType(error)?.toLowerCase() ?? "";
+        if (code.includes("auth") ||
+            code.includes("forbidden") ||
+            code.includes("unauthorized") ||
+            type.includes("auth") ||
+            type.includes("forbidden") ||
+            type.includes("unauthorized")) {
+            return true;
+        }
+        return /unauthorized|forbidden|authentication|invalid api key|login required/i.test(this.getErrorMessage(error));
+    }
+    getErrorStatus(error) {
+        return typeof error === "object" && error !== null && "status" in error
+            ? error.status
+            : undefined;
+    }
+    getErrorCode(error) {
+        return typeof error === "object" && error !== null && typeof error.code === "string"
+            ? error.code
+            : undefined;
+    }
+    getErrorType(error) {
+        return typeof error === "object" && error !== null && typeof error.type === "string"
+            ? error.type
+            : undefined;
+    }
+    getErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === "string") {
+            return error;
+        }
+        return "Claude backend execution failed";
+    }
+    async sleep(ms) {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+        });
+    }
+    async summarize(conversationText) {
+        const prompt = buildSummaryPrompt(conversationText);
+        const startMs = Date.now();
+        const sessionDir = createSessionWorkdir(this.config.workspaceDir, "message.received", undefined, { backendId: this.backendId, character: this.config.character });
+        const daemonReadToken = this.readTokenManager?.issue(sessionDir) ?? this.readToken;
+        try {
+            // Light-tier model for cheap conversation summarization. Tracks the
+            // canonical default in MODEL_REGISTRY so a Sonnet generation bump
+            // propagates here for free, mirroring how Codex/Gemini do it via
+            // their own `pickSummaryModel()` helpers.
+            const summaryModel = DEFAULT_CLAUDE_MEDIUM_MODEL;
+            const stream = query({
+                prompt,
+                options: {
+                    model: summaryModel,
+                    maxTurns: 1,
+                    maxBudgetUsd: 0.25,
+                    cwd: sessionDir,
+                    env: buildDaemonApiCliEnv(sessionDir, this.config.apiPort, { readToken: daemonReadToken, sessionBackend: "claude" }),
+                    systemPrompt: { type: "preset", preset: "claude_code" },
+                    permissionMode: "dontAsk",
+                    allowedTools: [],
+                },
+            });
+            const result = await this.withTimeout(stream, () => this.consumeStream(stream, summaryModel, startMs), this.config.executeTimeoutMinutes);
+            return result.output || "";
+        }
+        finally {
+            this.readTokenManager?.revoke(sessionDir);
+            cleanupSessionWorkdir(sessionDir);
+        }
+    }
+    async checkAuth() {
+        // Presence check only — this is the cheap gate used from the reactive
+        // execute path. Detailed probe lives in checkAuthDetailed().
+        const cloud = detectCloudProviderEnv();
+        if (cloud) {
+            if (cloud.missing.length > 0) {
+                return {
+                    ok: false,
+                    reason: `${cloud.flagEnvVar}=1 but missing required env vars: ${cloud.missing.join(", ")}`,
+                };
+            }
+            return { ok: true, method: cloud.method };
+        }
+        const rawApiKey = process.env.ANTHROPIC_API_KEY?.trim();
+        if (rawApiKey) {
+            if (!isPlausibleAnthropicApiKey(rawApiKey)) {
+                return {
+                    ok: false,
+                    reason: "ANTHROPIC_API_KEY is set but does not look like an Anthropic key (expected `sk-ant-…`).",
+                };
+            }
+            return { ok: true, method: "api_key" };
+        }
+        if (!this.cliPath) {
+            return {
+                ok: false,
+                reason: "Claude Code CLI is not installed or not on PATH. Run `npm install -g @anthropic-ai/claude-code`.",
+            };
+        }
+        return { ok: true, method: "cli_login" };
+    }
+    /**
+     * Detailed auth probe used by AuthHealthMonitor and the dashboard setup
+     * wizard. Two modes:
+     *  - **API key** (`ANTHROPIC_API_KEY`): format check + server-side probe
+     *    via `probeApiKeyServerSide("anthropic", ...)` (roadmap §9.1).
+     *    Throws on network/timeout so `checkAll()` records `probe_network_error`.
+     *  - **CLI login**: reads `~/.claude/credentials.json` for `refreshToken`.
+     *    Never writes to the Keychain or credentials file — refresh is left
+     *    to the CLI (Phase 0 confirmed rotating refresh_tokens; daemon-driven
+     *    refresh would race and corrupt state).
+     */
+    async checkAuthDetailed() {
+        const cloud = detectCloudProviderEnv();
+        if (cloud) {
+            if (cloud.missing.length > 0) {
+                return {
+                    ok: false,
+                    status: "missing",
+                    method: cloud.method,
+                    detail: `${cloud.flagEnvVar}=1 but missing: ${cloud.missing.join(", ")}`,
+                    recoveryCommand: `Set the missing env vars or unset ${cloud.flagEnvVar}`,
+                };
+            }
+            // Real auth happens inside the SDK against AWS / GCP / Azure. The
+            // daemon does not run a server-side probe for cloud providers — the
+            // first execution will surface any credential failure. Mark the
+            // status as `ok` here so the dashboard reports "Configured (cloud)";
+            // AuthHealthMonitor still re-runs this check hourly so a malformed
+            // env (env vars cleared after launch) flips the cache to `missing`.
+            return {
+                ok: true,
+                status: "ok",
+                method: cloud.method,
+                detail: `Configured via ${cloud.label} — runtime auth verified by Claude Code SDK`,
+            };
+        }
+        const rawApiKey = process.env.ANTHROPIC_API_KEY?.trim();
+        if (rawApiKey) {
+            if (!isPlausibleAnthropicApiKey(rawApiKey)) {
+                return {
+                    ok: false,
+                    status: "expired",
+                    method: "api_key",
+                    detail: "ANTHROPIC_API_KEY does not match Anthropic key format (expected `sk-ant-…`).",
+                    recoveryCommand: "Unset ANTHROPIC_API_KEY or replace it with a valid Anthropic API key",
+                };
+            }
+            // Format is plausible — attempt a server-side probe to detect
+            // revoked keys within 1 hourly cycle (roadmap §9.1). On network
+            // failure, the probe throws and the caller (checkAll or check-auth
+            // route) records `probe_network_error` without flipping DB cache.
+            const probe = await probeApiKeyServerSide("anthropic", rawApiKey);
+            return {
+                ok: probe.ok,
+                status: probe.ok ? "ok" : "expired",
+                method: "api_key",
+                detail: probe.detail,
+                ...(!probe.ok && {
+                    recoveryCommand: "Unset ANTHROPIC_API_KEY or replace it with a valid Anthropic API key",
+                }),
+            };
+        }
+        if (!this.cliPath) {
+            return {
+                ok: false,
+                status: "missing",
+                method: "cli_login",
+                detail: "Claude Code CLI not found on PATH",
+                recoveryCommand: "npm install -g @anthropic-ai/claude-code",
+            };
+        }
+        const bundle = await readClaudeCredentials();
+        if (!bundle) {
+            return {
+                ok: false,
+                status: "expired",
+                method: "cli_login",
+                detail: "No Claude credentials found",
+                recoveryCommand: "claude auth login",
+            };
+        }
+        if (!bundle.refreshToken) {
+            return {
+                ok: false,
+                status: "expired",
+                method: "cli_login",
+                detail: "Credentials lack refresh_token — run `claude auth login`",
+                recoveryCommand: "claude auth login",
+            };
+        }
+        return { ok: true, status: "ok", method: "oauth" };
+    }
+    /**
+     * Phase 5 §4.11 live probe. Claude Code 2.1+ may defer large MCP tool
+     * manifests behind `ToolSearch`, so the old zero-turn `system.init.tools`
+     * capture is no longer sufficient for hosted claude.ai connectors like
+     * Gmail and Google Calendar. Run a tightly-scoped turn that can only use
+     * the read-only ToolSearch catalog, then extract connector names from
+     * both returned `tool_reference` blocks and the final printed answer.
+     */
+    async probeTools() {
+        const sessionDir = createSessionWorkdir(this.config.workspaceDir, "message.received", undefined, { backendId: this.backendId, character: this.config.character });
+        const daemonReadToken = this.readTokenManager?.issue(sessionDir) ?? this.readToken;
+        try {
+            const stream = query({
+                prompt: CLAUDE_PROBE_TOOLS_PROMPT,
+                options: {
+                    model: DEFAULT_CLAUDE_MEDIUM_MODEL,
+                    maxTurns: 3,
+                    maxBudgetUsd: 0.25,
+                    cwd: sessionDir,
+                    env: buildDaemonApiCliEnv(sessionDir, this.config.apiPort, { readToken: daemonReadToken, sessionBackend: "claude" }),
+                    systemPrompt: { type: "preset", preset: "claude_code" },
+                    permissionMode: "dontAsk",
+                    allowedTools: ["ToolSearch"],
+                },
+            });
+            const tools = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    void (async () => {
+                        try {
+                            await stream.return?.(undefined);
+                        }
+                        catch {
+                            /* stream already closed */
+                        }
+                    })();
+                    reject(new Error("probeTools: timeout waiting for ToolSearch probe"));
+                }, 60_000);
+                timer.unref?.();
+                void (async () => {
+                    const collected = [];
+                    let terminalError = null;
+                    try {
+                        for await (const message of stream) {
+                            collected.push(...extractClaudeProbeTools(message));
+                            if (message.type === "result") {
+                                const result = message;
+                                if (result.is_error) {
+                                    terminalError = describeClaudeProbeResultError(result);
+                                }
+                            }
+                        }
+                        clearTimeout(timer);
+                        const deduped = Array.from(new Set(collected));
+                        if (terminalError && deduped.length === 0) {
+                            reject(new Error(`probeTools: ${terminalError}`));
+                            return;
+                        }
+                        resolve(deduped);
+                    }
+                    catch (err) {
+                        clearTimeout(timer);
+                        reject(err instanceof Error ? err : new Error(String(err)));
+                    }
+                })();
+            });
+            logger.info({ toolCount: tools.length }, "Live probe collected tool manifest");
+            return tools;
+        }
+        finally {
+            this.readTokenManager?.revoke(sessionDir);
+            cleanupSessionWorkdir(sessionDir);
+        }
+    }
+    listModels() {
+        const defaultMediumModel = DEFAULT_CLAUDE_MEDIUM_MODEL;
+        const defaultHighModel = DEFAULT_CLAUDE_HIGH_MODEL;
+        const configuredModels = [
+            {
+                ...(findRegisteredModel(this.backendId, defaultMediumModel) ?? {
+                    backendId: this.backendId,
+                    modelId: defaultMediumModel,
+                    label: defaultMediumModel,
+                    tier: "medium",
+                    available: true,
+                }),
+            },
+            {
+                ...(findRegisteredModel(this.backendId, defaultHighModel) ?? {
+                    backendId: this.backendId,
+                    modelId: defaultHighModel,
+                    label: defaultHighModel,
+                    tier: "high",
+                    available: true,
+                }),
+            },
+        ];
+        const models = [...configuredModels, ...getModelsForBackend(this.backendId)];
+        return models.filter((model, index, list) => list.findIndex((candidate) => candidate.modelId === model.modelId) === index);
+    }
+    async consumeStream(stream, model, startMs, streamCallbacks, eventType) {
+        let output = "";
+        let streamedOutput = "";
+        let sessionId = null;
+        let costUsd = 0;
+        let usage = {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheCreationInputTokens: 0,
+            cacheReadInputTokens: 0,
+        };
+        const modelUsage = {};
+        let numTurns = 0;
+        let durationApiMs = 0;
+        let isError = false;
+        let stopReason = null;
+        // Context-update tracking (Phase 6 + H2 refinement).
+        const contextUpdateCalls = new Set();
+        const failedContextUpdates = new Set();
+        // Advisor tool invocation count — incremented each time the SDK stream
+        // emits a `server_tool_use` content block with `name: "advisor"`. This is
+        // the `advisor_20260301` Anthropic-hosted tool. See `docs/advisor.md`.
+        let advisorCallCount = 0;
+        // B-003 Phase 4.4 — MCP tool result matching.
+        // Maps tool_use_id → { rowId, startMs } so that when the SDK delivers the
+        // matching tool_result block we can backfill ok/error/duration_ms.
+        // startMs is set when the assistant message containing the tool_use block is
+        // processed. The resulting duration_ms therefore covers SDK dispatch latency
+        // (model → executor → result delivery) rather than pure tool execution time.
+        const mcpPendingResults = new Map();
+        try {
+            for await (const message of stream) {
+                if (message.type === "system" && message.subtype === "init") {
+                    const sysMsg = message;
+                    sessionId = sysMsg.session_id;
+                    logger.debug({ sessionId, model: sysMsg.model }, "Session initialized");
+                }
+                else if (message.type === "stream_event") {
+                    // Forward streaming text deltas to the caller (e.g., dashboard SSE)
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK stream_event lacks typed .event
+                    const event = message.event;
+                    if (event?.type === "content_block_delta" && event?.delta?.type === "text_delta") {
+                        streamedOutput += event.delta.text;
+                        streamCallbacks?.onText?.(event.delta.text);
+                    }
+                }
+                else if (message.type === "assistant") {
+                    // Track Bash tool_use blocks that hit the context API + server-side
+                    // advisor tool invocations.
+                    const assistantMsg = message;
+                    const blocks = assistantMsg.message?.content;
+                    if (Array.isArray(blocks)) {
+                        for (const block of blocks) {
+                            if (!block || typeof block !== "object")
+                                continue;
+                            const blockType = block.type;
+                            const blockName = block.name;
+                            if (blockType === "tool_use" && blockName === "Bash") {
+                                const toolUseId = block.id;
+                                const cmd = (block.input?.command ?? "");
+                                if (typeof toolUseId === "string" &&
+                                    typeof cmd === "string" &&
+                                    ClaudeCodeCore.isContextUpdateCommand(cmd)) {
+                                    contextUpdateCalls.add(toolUseId);
+                                }
+                            }
+                            else if (blockType === "tool_use" &&
+                                typeof blockName === "string" &&
+                                blockName.startsWith("mcp__")) {
+                                // B-003 Phase 4.4 — persist MCP tool call to `mcp_tool_calls`.
+                                // Capture tool_use_id + start time so we can match the result
+                                // block that arrives later in a `user` message.
+                                const parsed = parseMcpToolName(blockName);
+                                if (parsed) {
+                                    logger.debug({
+                                        serverId: parsed.serverId,
+                                        toolName: parsed.toolName,
+                                        sessionId,
+                                        eventType,
+                                    }, "mcp.tool_call");
+                                    if (this.mcpContext?.db) {
+                                        try {
+                                            const rowId = logMcpToolCall(this.mcpContext.db, {
+                                                serverId: parsed.serverId,
+                                                toolName: parsed.toolName,
+                                                eventType,
+                                                sessionId: sessionId ?? undefined,
+                                            });
+                                            const toolUseId = block.id;
+                                            if (typeof toolUseId === "string") {
+                                                mcpPendingResults.set(toolUseId, { rowId, startMs: Date.now() });
+                                            }
+                                        }
+                                        catch (err) {
+                                            logger.warn({ err, serverId: parsed.serverId }, "mcp.tool_call audit insert failed");
+                                        }
+                                    }
+                                }
+                            }
+                            else if (blockType === "server_tool_use" &&
+                                blockName === "advisor") {
+                                // The advisor_20260301 server-side tool. The SDK emits one
+                                // server_tool_use per invocation; we count them here.
+                                advisorCallCount += 1;
+                            }
+                        }
+                    }
+                }
+                else if (message.type === "user") {
+                    // The SDK emits the tool_result that feeds back to the model
+                    // as a 'user' message whose content array contains
+                    // tool_result blocks. Check is_error on each result matched
+                    // against our pending context tool_use ids, and scan the
+                    // merged tool output for PA_API_ERROR markers emitted by the
+                    // daemon API wrappers.
+                    const userMsg = message;
+                    const content = userMsg.message?.content;
+                    if (Array.isArray(content)) {
+                        for (const block of content) {
+                            if (block &&
+                                block.type === "tool_result") {
+                                const toolUseId = block.tool_use_id;
+                                const isError = block.is_error === true;
+                                if (typeof toolUseId === "string") {
+                                    // Context-update error tracking.
+                                    if (contextUpdateCalls.has(toolUseId) && isError) {
+                                        failedContextUpdates.add(toolUseId);
+                                    }
+                                    // B-003 Phase 4.4 — backfill ok/error/duration_ms for MCP tool calls.
+                                    const pending = mcpPendingResults.get(toolUseId);
+                                    if (pending && this.mcpContext?.db) {
+                                        const ok = !isError;
+                                        const errorText = isError
+                                            ? flattenToolResultContent(block.content).slice(0, 1000) || null
+                                            : null;
+                                        const durationMs = Date.now() - pending.startMs;
+                                        try {
+                                            updateMcpToolCallResult(this.mcpContext.db, pending.rowId, ok, errorText, durationMs);
+                                        }
+                                        catch (err) {
+                                            logger.warn({ err, rowId: pending.rowId }, "mcp.tool_call result update failed");
+                                        }
+                                        mcpPendingResults.delete(toolUseId);
+                                    }
+                                }
+                                const resultText = flattenToolResultContent(block.content);
+                                const apiErrors = extractSilentApiErrors(resultText);
+                                if (apiErrors.length > 0) {
+                                    logSilentApiErrors(logger, apiErrors, {
+                                        backendId: this.backendId,
+                                        sessionId,
+                                        eventType,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                else if (message.type === "result") {
+                    const r = message;
+                    if (r.subtype === "success") {
+                        const resultOutput = typeof r.result === "string" ? r.result : "";
+                        // Claude SDK can stream assistant text and still report an empty
+                        // final result when the turn ends after a tool-only message.
+                        output =
+                            resultOutput.trim().length > 0
+                                ? resultOutput
+                                : streamedOutput.trim().length > 0
+                                    ? streamedOutput
+                                    : resultOutput;
+                    }
+                    sessionId = r.session_id;
+                    costUsd = r.total_cost_usd;
+                    usage = {
+                        inputTokens: r.usage.input_tokens,
+                        outputTokens: r.usage.output_tokens,
+                        cacheCreationInputTokens: r.usage.cache_creation_input_tokens ?? 0,
+                        cacheReadInputTokens: r.usage.cache_read_input_tokens ?? 0,
+                    };
+                    // Convert SDK modelUsage to our format
+                    for (const [modelName, mu] of Object.entries(r.modelUsage)) {
+                        modelUsage[modelName] = {
+                            inputTokens: mu.inputTokens,
+                            outputTokens: mu.outputTokens,
+                            costUsd: mu.costUSD,
+                        };
+                    }
+                    numTurns = r.num_turns;
+                    durationApiMs = r.duration_api_ms;
+                    isError = r.is_error;
+                    stopReason = r.stop_reason;
+                    if (r.subtype !== "success") {
+                        logger.warn({ subtype: r.subtype, errors: "errors" in r ? r.errors : [] }, "Agent session ended with error");
+                    }
+                }
+            }
+        }
+        finally {
+            // Always signal stream completion — even on error — so the client's
+            // streaming state is reset (prevents stuck "streaming = true").
+            streamCallbacks?.onEnd?.();
+        }
+        const contextUpdated = contextUpdateCalls.size > failedContextUpdates.size;
+        return {
+            output,
+            sessionId,
+            backendId: this.backendId,
+            modelId: model,
+            costSource: "sdk",
+            costUsd,
+            usage,
+            modelUsage,
+            numTurns,
+            durationMs: Date.now() - startMs,
+            durationApiMs,
+            model,
+            isError,
+            stopReason,
+            contextUpdated,
+            advisorCallCount,
+        };
+    }
+    /**
+     * Race `fn()` against an `executeTimeoutMinutes` wall-clock timer.
+     *
+     * On timeout we must terminate the underlying SDK stream too — otherwise
+     * `Promise.race` just rejects while `query()` keeps running in the
+     * background, which in retry scenarios would produce two concurrent
+     * Claude Code sessions for the same event and double quota consumption.
+     */
+    async withTimeout(stream, fn, timeoutMinutes) {
+        const timeoutMs = timeoutMinutes * 60 * 1000;
+        let timer;
+        let timedOut = false;
+        const fnPromise = fn();
+        // Attach a no-op catch so post-timeout rejections from fn() don't
+        // surface as unhandledRejection once Promise.race has already resolved.
+        fnPromise.catch(() => undefined);
+        try {
+            return await Promise.race([
+                fnPromise,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        reject(new AgentTimeoutError(timeoutMs));
+                        // Cancel the SDK stream asynchronously.
+                        void (async () => {
+                            try {
+                                const iterable = stream;
+                                const iterator = typeof iterable[Symbol.asyncIterator] === "function"
+                                    ? iterable[Symbol.asyncIterator]()
+                                    : null;
+                                await iterator?.return?.(undefined);
+                            }
+                            catch {
+                                // ignore — cancellation is best-effort
+                            }
+                        })();
+                    }, timeoutMs);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            void timedOut; // reference to avoid unused-variable if optimizer drops it
+        }
+    }
+    /**
+     * Detect whether a Bash command invokes a write against the Context
+     * File API (`PUT|PATCH /api/context/*` via curl).
+     */
+    static isContextUpdateCommand(command) {
+        if (!/\bcurl\b/.test(command))
+            return false;
+        if (!/\/api\/context\//.test(command))
+            return false;
+        const segments = command.split(/[;&|\n]+/);
+        for (const seg of segments) {
+            if (!/\bcurl\b/.test(seg))
+                continue;
+            if (!/\/api\/context\//.test(seg))
+                continue;
+            if (/(?:-X|--request)\s+(?:PUT|PATCH)\b/.test(seg)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // Template resolution and event data extraction are shared with Codex/Gemini
+    // backends via prompt-utils.ts (buildExecutionPrompt, extractEventData).
+    /**
+     * Allowed tools whitelist for dontAsk permission mode.
+     *
+     * `delegatedTools` is UNION'd onto the returned list — even when
+     * `allowedToolsOverride` is set. This is a deliberate deviation from the
+     * override's otherwise-absolute "replace everything" contract (see
+     * `CRITICAL_OVERRIDE_TOOLS` at line 293, which warns but does not union).
+     * Rationale: delegated mode is a runtime-configurable axis orthogonal to
+     * the dashboard's tool-customization override. If a user set the override
+     * before flipping an integration to delegated, silently dropping the
+     * registry-declared connector tools would break mail/calendar with a
+     * misleading "permission denied" DM. Union semantics keep the override's
+     * curation intent while letting delegated mode widen the surface to
+     * whatever the registry already advertised.
+     */
+    getAllowedTools(webSearchEnabled, delegatedTools = []) {
+        const base = this.config.allowedToolsOverride ?? [
+            "Read",
+            "Glob",
+            "Grep",
+            "Write",
+            "Edit",
+            "Skill", // user skills (external-services, obsidian-*, observations, ...)
+            "Bash(curl *)", // curl broadly allowed; hooks restrict to localhost
+            "Bash(git *)", // Git operations
+            "Bash(jq *)", // safe JSON post-processor for curl pipelines
+        ];
+        const merged = new Set(base);
+        if (!this.config.allowedToolsOverride && webSearchEnabled) {
+            merged.add("WebSearch");
+        }
+        for (const tool of delegatedTools)
+            merged.add(tool);
+        return Array.from(merged);
+    }
+    /**
+     * Thin wrapper around the pure `computeDelegatedClaudeTools` helper that
+     * pulls the integrations record from the wired mcp context. Returns `[]`
+     * when the context is not yet wired (tests, startup ordering) — which
+     * matches the pre-fix behavior for sessions that ran before the daemon
+     * finished composing. A one-shot warning is emitted in `setMcpContext`
+     * confirming wiring.
+     */
+    getDelegatedClaudeTools() {
+        if (!this.mcpContext)
+            return [];
+        try {
+            const integrations = readIntegrations(this.mcpContext.db);
+            return computeDelegatedClaudeTools(integrations);
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to read integrations for delegated-tool allowlist — proceeding without delegated tools");
+            return [];
+        }
+    }
+    /**
+     * DELEGATED-MODE-V2-DESIGN.md §4.3.3 — same-backend deny enforcement at
+     * the SDK boundary. For every integration whose `delegatedBackend === "claude"`,
+     * expand `state.deniedTools` against the connector's known tools and emit
+     * the namespaced names (`mcp__claude_ai_<X>__<tool>`). The SDK refuses any
+     * tool listed in `disallowedTools` regardless of `allowedTools` — hard
+     * enforcement.
+     *
+     * Returns `[]` when context isn't wired (tests / pre-startup) and on read
+     * failures, matching the conservative pattern used by
+     * `getDelegatedClaudeTools`.
+     */
+    getSessionDeniedTools() {
+        if (!this.mcpContext)
+            return [];
+        try {
+            const integrations = readIntegrations(this.mcpContext.db);
+            const map = collectSessionDeniedTools(integrations, "claude");
+            const out = [];
+            for (const names of map.values()) {
+                for (const n of names)
+                    out.push(n);
+            }
+            return out;
+        }
+        catch (err) {
+            logger.warn({ err }, "Failed to read integrations for same-backend denied-tools — proceeding without per-integration deny");
+            return [];
+        }
+    }
+    /**
+     * Security hooks:
+     *   1. Bash(curl *) — restrict to localhost Daemon API, block connection-override flags. (strict only)
+     *   2. Bash(jq *)  — block file-access flags and the `env` filter (process env exfiltration). (strict only)
+     *   3. Write/Edit  — block writes into the session helper dir and context dir, mark vault writes.
+     *
+     * In allow mode the curl and jq hooks are dropped, but the Write/Edit hook
+     * stays: the context-dir chokepoint exists for memory integrity (today-write
+     * lock, md_file_snapshots, CONTEXT_WRITE_PERMISSIONS), not permissions.
+     */
+    getSecurityHooks(allowMode = false) {
+        const bashCurlHook = async (input) => {
+            const toolInput = input.tool_input;
+            const cmd = toolInput?.command ?? "";
+            if (/\bcurl\b/.test(cmd)) {
+                const urls = cmd.match(/https?:\/\/[^\s'"]+/g) ?? [];
+                if (urls.length === 0) {
+                    return {
+                        decision: "block",
+                        reason: "curl command must contain an explicit localhost URL",
+                    };
+                }
+                for (const url of urls) {
+                    try {
+                        const parsed = new URL(url);
+                        if (parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
+                            return {
+                                decision: "block",
+                                reason: `curl target not allowed: ${url} (host: ${parsed.hostname})`,
+                            };
+                        }
+                        const effectivePort = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
+                        if (effectivePort !== String(this.config.apiPort)) {
+                            return {
+                                decision: "block",
+                                reason: `curl target port not allowed: ${effectivePort}`,
+                            };
+                        }
+                    }
+                    catch {
+                        return {
+                            decision: "block",
+                            reason: `curl target URL is malformed: ${url}`,
+                        };
+                    }
+                }
+                if (/--connect-to|--resolve|--config\b|(?:^|\s)-[a-zA-Z]*K|--proxy\b|(?:^|\s)-[a-zA-Z]*x|--socks/.test(cmd)) {
+                    return {
+                        decision: "block",
+                        reason: "curl connection override flags not allowed (--connect-to, --resolve, --config, --proxy)",
+                    };
+                }
+            }
+            return { continue: true };
+        };
+        const bashJqHook = async (input) => {
+            const toolInput = input.tool_input;
+            const cmd = toolInput?.command ?? "";
+            if (!/\bjq\b/.test(cmd))
+                return { continue: true };
+            // Narrow to THIS jq invocation's own args (up to the next pipe / chain op)
+            // so that later pipeline stages are not inspected by the jq rules.
+            //
+            // Known approximation: `[^|;&]*` does not respect shell quoting, so a
+            // jq filter with a `|` INSIDE a quoted expression (e.g. `jq 'env | keys'`)
+            // will truncate `jqPart` at the first `|` regardless of whether that `|`
+            // is a jq pipe inside quotes or an actual shell pipeline break. This is
+            // intentionally conservative on the safe side: the env-filter check
+            // below still fires on the truncated left half (`jq 'env `), so attack
+            // payloads are still blocked. The downside is slightly reduced precision
+            // on benign expressions containing the jq `|` operator — those get
+            // scanned only up to the first pipe, not their full extent.
+            const jqMatch = cmd.match(/\bjq\b([^|;&]*)/);
+            if (!jqMatch)
+                return { continue: true };
+            const jqPart = jqMatch[0];
+            // (a) Block file-access flags — --slurpfile / --rawfile read arbitrary
+            // files, which would bypass the Read deny list (~/.ssh/**, .env, etc.).
+            if (/(?:^|\s)--slurpfile\b/.test(jqPart) || /(?:^|\s)--rawfile\b/.test(jqPart)) {
+                return {
+                    decision: "block",
+                    reason: "jq --slurpfile and --rawfile are not allowed " +
+                        "(would bypass Read(.env) / Read(~/.ssh/**) disallow rules).",
+                };
+            }
+            // (b) Block module loading — -L <dir> + import can load filter code from
+            // the filesystem, effectively RCE inside the jq process.
+            if (/(?:^|\s)-L(?:\s|=|$)/.test(jqPart)) {
+                return {
+                    decision: "block",
+                    reason: "jq -L (module load path) is not allowed.",
+                };
+            }
+            // (c) Block the `env` filter. `jq env`, `jq -n env`, `jq 'env.FOO'`,
+            // `jq '. , env'` all dump the daemon's process.env to stdout. Process.env
+            // on this daemon is expected to be clean (secrets live in the keychain),
+            // but defense-in-depth: if OPENAI_API_KEY or similar is ever exported at
+            // launch, the env filter is the shortest exfil path.
+            //
+            // Heuristic: match bare `env` NOT preceded by a field-access dot or word
+            // char, and NOT followed by a word char. This matches jq's env filter
+            // (`env`, `env.HOME`, `(env)`, `env|keys`) while leaving field access
+            // like `.env`, `.env_var`, `.data.environments` untouched.
+            if (/(?:^|[^\w.])env(?!\w)/.test(jqPart)) {
+                return {
+                    decision: "block",
+                    reason: "jq env filter is not allowed — it dumps the daemon process " +
+                        "environment, which is a known exfiltration vector for any " +
+                        "secrets loaded via .env at startup.",
+                };
+            }
+            return { continue: true };
+        };
+        /**
+         * Block any Bash command that references the context-directory path.
+         *
+         * Rationale: the daemon API is the ONLY sanctioned write channel for
+         * context files — it enforces today-write-lock, md_file_snapshots,
+         * CONTEXT_WRITE_PERMISSIONS, and onPromptContextChanged. In strict mode,
+         * the allowlist (Bash narrowed to curl/git/jq) + fileWriteHook keeps
+         * this chokepoint intact. In allow mode Bash is unrestricted, so an
+         * agent could bypass via `echo > today.md`, `tee`, `python -c 'open…'`,
+         * `git log … > context/…`, etc.
+         *
+         * This hook runs in BOTH modes (defense-in-depth). The heuristic is
+         * deliberately conservative: we block the command if its raw text
+         * contains any of the well-known path representations of the context
+         * dir. This has false positives for read-only uses (`cat context/*.md`),
+         * but the agent always has the Read tool and the daemon GET endpoint
+         * available, so a blocked shell-read is an error message, not a
+         * capability loss. Obfuscation beyond the handled variants (dynamic
+         * path construction inside a subshell) is out of scope — the threat
+         * model is "the model picks a shell workaround", not adversarial
+         * prompt injection.
+         */
+        const bashContextWriteHook = async (input) => {
+            const toolInput = input.tool_input;
+            const cmd = toolInput?.command ?? "";
+            if (typeof cmd !== "string" || cmd.length === 0)
+                return { continue: true };
+            const absContextDir = resolvePath(getContextDir(this.config));
+            const home = homedir();
+            const pathForms = shellPathForms(absContextDir, home);
+            for (const form of pathForms) {
+                if (cmd.includes(form)) {
+                    return {
+                        decision: "block",
+                        reason: `Bash commands that reference the context directory (${absContextDir}) are ` +
+                            `not allowed. Use the daemon API: ` +
+                            `GET/PUT/PATCH http://localhost:${this.config.apiPort}/api/context/<path>. ` +
+                            `The API enforces today-write-lock, md_file_snapshots, CONTEXT_WRITE_PERMISSIONS, ` +
+                            `and onPromptContextChanged — bypassing it via shell redirects or script ` +
+                            `engines leaves the memory layer inconsistent. Matched path form: ${form}.`,
+                    };
+                }
+            }
+            return { continue: true };
+        };
+        const fileWriteHook = async (input) => {
+            const hookInput = input;
+            const toolInput = hookInput.tool_input;
+            const rawFilePath = toolInput?.file_path;
+            if (typeof rawFilePath !== "string" || rawFilePath.length === 0) {
+                return { continue: true };
+            }
+            const filePath = rawFilePath;
+            const cwd = hookInput.cwd;
+            if (!cwd && !isAbsolute(filePath))
+                return { continue: true };
+            const absFile = resolvePath(cwd ?? "/", filePath);
+            // (a) Block writes into the session-local helper dir. The `curl` shim in
+            // `.pa/bin/` carries daemon-auth env at execution time; letting the model
+            // rewrite it would turn the helper into a secret exfiltration vector.
+            const absHelperDir = resolvePath(cwd ?? "/", ".pa");
+            const withinHelperDir = isPathInsideOrEqual(absHelperDir, absFile);
+            if (withinHelperDir) {
+                return {
+                    decision: "block",
+                    reason: "Direct Write/Edit to .pa is forbidden. " +
+                        "Session helper binaries are managed by the daemon.",
+                };
+            }
+            // (b) Block writes into the context dir.
+            const contextDir = getContextDir(this.config);
+            const absContextDir = resolvePath(contextDir);
+            const withinContext = isPathInsideOrEqual(absContextDir, absFile);
+            if (withinContext) {
+                return {
+                    decision: "block",
+                    reason: `Direct Write/Edit to context dir is forbidden. ` +
+                        `Use the daemon API instead: ` +
+                        `PUT http://localhost:${this.config.apiPort}/api/context/<path> (full replace) or ` +
+                        `PATCH http://localhost:${this.config.apiPort}/api/context/<path> (section op). ` +
+                        `The API enforces CONTEXT_WRITE_PERMISSIONS, morningRoutineLock, md_file_snapshots, ` +
+                        `onPromptContextChanged, and expectedMtime concurrency. Path: ${absFile}`,
+                };
+            }
+            // (c) Mark vault-scoped writes for observer attribution.
+            // Targets the EXTERNAL Obsidian vault; the ObsidianWatcher observer
+            // watches that path and would otherwise misattribute agent writes
+            // as user writes.
+            if (!this.writeTracker)
+                return { continue: true };
+            const vaultPath = this.config.externalObsidianVaultPath;
+            if (!vaultPath)
+                return { continue: true };
+            const absVault = resolvePath(vaultPath);
+            const withinVault = isPathInsideOrEqual(absVault, absFile);
+            if (!withinVault)
+                return { continue: true };
+            this.writeTracker.markWriting(absFile);
+            logger.debug({ filePath: absFile }, "vault write pre-marked for observer attribution");
+            return { continue: true };
+        };
+        // EXECUTION-MODE-DESIGN.md §6 — absolute-block audit hook. Runs ahead
+        // of every other Bash/Read/Write/Edit hook in both modes. The SDK-level
+        // `disallowedTools` rejection is the authoritative block; this hook is
+        // redundant defense-in-depth that also writes the `blocked_absolute`
+        // audit row so the owner can see the layer is active.
+        const makeAbsoluteBlockHook = (toolName, argField) => async (input) => {
+            const toolInput = input.tool_input;
+            const raw = toolInput?.[argField];
+            if (typeof raw !== "string")
+                return { continue: true };
+            const match = classifyAbsoluteBlock(toolName, raw);
+            if (!match)
+                return { continue: true };
+            recordAbsoluteBlockAudit({
+                db: this.mcpContext?.db,
+                backend: "claude",
+                mode: this.config.claudeExecutionPermissionMode,
+                match,
+                toolName,
+            });
+            return {
+                decision: "block",
+                reason: `Absolute-block layer denied this ${toolName} call ` +
+                    `(category: ${match.category}). This rule holds in both Safe ` +
+                    `and Allow modes — see EXECUTION-MODE-DESIGN.md §6.`,
+            };
+        };
+        const bashAbsoluteBlockHook = makeAbsoluteBlockHook("Bash", "command");
+        const readAbsoluteBlockHook = makeAbsoluteBlockHook("Read", "file_path");
+        const writeAbsoluteBlockHook = makeAbsoluteBlockHook("Write", "file_path");
+        const editAbsoluteBlockHook = makeAbsoluteBlockHook("Edit", "file_path");
+        // The context-write hook is always attached to Bash — it is the only
+        // guarantee that the daemon-API chokepoint for memory files survives
+        // allow mode (where curl/jq restrictions are dropped and Bash can
+        // otherwise redirect into context/*.md freely).
+        //
+        // The absolute-block audit hook is appended LAST on every matcher
+        // (§6.3). Appended rather than prepended so existing per-index hook
+        // tests keep pointing at the same functions; semantically it is a
+        // fallback defense whose practical effect is duplicating the SDK's
+        // `disallowedTools` rejection into an `agent_actions` row.
+        return {
+            PreToolUse: [
+                {
+                    matcher: "Bash",
+                    hooks: allowMode
+                        ? [bashContextWriteHook, bashAbsoluteBlockHook]
+                        : [
+                            bashCurlHook,
+                            bashJqHook,
+                            bashContextWriteHook,
+                            bashAbsoluteBlockHook,
+                        ],
+                },
+                { matcher: "Write", hooks: [fileWriteHook, writeAbsoluteBlockHook] },
+                { matcher: "Edit", hooks: [fileWriteHook, editAbsoluteBlockHook] },
+                { matcher: "Read", hooks: [readAbsoluteBlockHook] },
+            ],
+        };
+    }
+    /**
+     * Delegated proxy invocation — Claude SDK path.
+     *
+     * Spawns a one-shot SDK `query()` constrained to a single `allowedTools`
+     * entry (the requested connector tool), parses the structured stream
+     * for the matching `tool_use` → `tool_result` pair, and returns the raw
+     * tool result. The model's surrounding text is discarded — the route
+     * handler only sees the connector's structured payload.
+     *
+     * Error classes (DelegatedToolErrorClass):
+     *   - `wrong_tool`     — model called a tool we did not request (anti-prompt-injection).
+     *   - `no_tool_call`   — model never invoked the tool within `maxTurns`.
+     *   - `tool_error`     — connector returned `is_error: true`.
+     *   - `parse_error`    — stream produced no terminal `result` event.
+     *   - `auth_error`     — SDK reported `authentication_failed`.
+     *   - `timeout`        — invoker's wall-clock signal aborted the stream.
+     *   - `subprocess_crashed` — exception thrown out of the iterator.
+     *
+     * Cost is captured from the terminal `SDKResultMessage` regardless of
+     * subtype so the invoker can attribute partial spend on the failure
+     * paths (no_tool_call, wrong_tool, tool_error).
+     */
+    async runDelegatedTool(params) {
+        const startMs = Date.now();
+        const { toolName, toolArgs, modelId, maxTurns, maxBudgetUsd, sessionDir } = params;
+        const prompt = buildDelegatedToolPrompt(toolName, toolArgs);
+        const daemonReadToken = this.readTokenManager?.issue(sessionDir) ?? this.readToken;
+        let stream = null;
+        const aborted = { value: false };
+        // `abortReason` carries the reason that caused `aborted.value=true`
+        // so the post-loop classifier can map idle-watchdog aborts to
+        // `errorClass="timeout"`. Falls back to the caller's signal reason
+        // when only the caller initiated the abort.
+        let abortReason = null;
+        const closeStream = () => {
+            void (async () => {
+                try {
+                    await stream?.return?.(undefined);
+                }
+                catch {
+                    /* stream already closed */
+                }
+            })();
+        };
+        const onAbort = () => {
+            aborted.value = true;
+            abortReason = params.abortSignal?.reason ?? null;
+            closeStream();
+        };
+        if (params.abortSignal) {
+            if (params.abortSignal.aborted) {
+                aborted.value = true;
+                abortReason = params.abortSignal.reason ?? null;
+            }
+            else {
+                params.abortSignal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+        // Idle watchdog. Claude SDK runs in-process; cold-start is
+        // negligible (no MCP/CLI load) so the typical first message lands
+        // within 1-3 s. A 30 s idle threshold catches a stuck SDK iterator
+        // (network stall, server-side hang) without false-tripping a slow
+        // tool. On trip we close the stream the same way `onAbort` does and
+        // record the trip in `abortReason` so the classifier returns
+        // `errorClass="timeout"` (uniform with CLI backends).
+        const idleTimeoutMs = DELEGATED_PROXY_DEFAULTS.idleTimeoutMsByBackend.claude
+            ?? DELEGATED_PROXY_DEFAULTS.idleTimeoutMs;
+        const idleWatchdog = new IdleWatchdog({
+            idleTimeoutMs,
+            onTimeout: (idleMs) => {
+                if (aborted.value)
+                    return;
+                aborted.value = true;
+                abortReason = new DelegatedProxyTimeoutError(`claude SDK stream idle for ${idleMs}ms (limit ${idleTimeoutMs}ms)`);
+                logger.warn({ idleMs, idleTimeoutMs, toolName }, "claude delegated proxy idle watchdog tripped");
+                closeStream();
+            },
+        });
+        try {
+            stream = query({
+                prompt,
+                options: {
+                    model: modelId,
+                    maxTurns,
+                    maxBudgetUsd,
+                    cwd: sessionDir,
+                    env: buildDaemonApiCliEnv(sessionDir, this.config.apiPort, { readToken: daemonReadToken, sessionBackend: "claude" }),
+                    systemPrompt: { type: "preset", preset: "claude_code" },
+                    permissionMode: "dontAsk",
+                    // The connector tool must be pre-authorized — Claude SDK with
+                    // permissionMode="dontAsk" silently denies anything not in
+                    // allowedTools.
+                    //
+                    // ToolSearch is Claude Code's deferred-tool discovery mechanism:
+                    // when many MCP servers are registered in the user's global
+                    // config (~/.claude.json: Notion, Gmail, GCal, Drive, Figma,
+                    // Canva, Hugging Face, …) the CLI ships only a working set of
+                    // tool schemas and defers the rest. To call a deferred tool, the
+                    // model must first call ToolSearch to load its schema. Without
+                    // ToolSearch allowed, the proxy's first turn was wasted on a
+                    // denied ToolSearch call (audit log 2026-04-29: 1 Notion failure
+                    // logged as `wrong_tool=ToolSearch`, 5 logged as
+                    // `subprocess_crashed: Reached maximum number of turns (2)` —
+                    // the model retried other approaches and exhausted the budget).
+                    //
+                    // Allowing ToolSearch is safe: allowedTools enforcement still
+                    // gates which tools can be CALLED, and ToolSearch only loads
+                    // schemas into context. The proxy parser below also skips
+                    // ToolSearch when capturing `wrongToolName` so a ToolSearch+
+                    // partial-result trace classifies as `no_tool_call` rather than
+                    // misleading `wrong_tool=ToolSearch`.
+                    //
+                    // TODO(future): a cleaner architectural fix is to materialize a
+                    // session-local `.mcp.json` containing only the relevant
+                    // connector's MCP server and pass `strictMcpConfig: true` —
+                    // that prevents deferral entirely (one MCP server → schemas fit
+                    // in the working set). Punted because it requires extracting
+                    // server configs from the user's global file per integration.
+                    allowedTools: [toolName, DEFERRED_TOOL_DISCOVERY_TOOL_NAME],
+                    // Defense-in-depth: even with allowedTools restricted to a tight
+                    // set, keep the absolute-block layer (rm -rf, sudo, secret file
+                    // reads) merged so a future relaxation of allowedTools can't
+                    // accidentally drop these guarantees.
+                    disallowedTools: [...ALWAYS_DISALLOWED_TOOLS],
+                    // Adaptive thinking is the SDK default for thinking-capable
+                    // models (Haiku 4.5+ / Sonnet 4.6+). Per Anthropic's docs
+                    // thinking happens within a single API call so it does not
+                    // typically burn an extra turn — but for a proxy that issues
+                    // one named tool call with explicit args, thinking adds latency
+                    // and tokens for no benefit. The proxy.md profile says "no
+                    // narration"; disabling thinking aligns runtime behavior with
+                    // that intent.
+                    thinking: { type: "disabled" },
+                },
+            });
+            let capturedToolUseId = null;
+            let capturedToolResult = undefined;
+            let capturedToolErrorMessage = null;
+            let wrongToolName = null;
+            let cost = emptyCost();
+            let terminalSubtype = null;
+            let terminalIsError = false;
+            let terminalErrors = [];
+            try {
+                idleWatchdog.start();
+                for await (const message of stream) {
+                    idleWatchdog.beat();
+                    if (aborted.value) {
+                        break;
+                    }
+                    if (message.type === "assistant") {
+                        const assistantMsg = message;
+                        const blocks = assistantMsg.message?.content;
+                        if (!Array.isArray(blocks))
+                            continue;
+                        for (const block of blocks) {
+                            if (!block || typeof block !== "object")
+                                continue;
+                            const blockType = block.type;
+                            if (blockType !== "tool_use")
+                                continue;
+                            const blockName = block.name;
+                            const blockId = block.id;
+                            if (typeof blockName !== "string" || typeof blockId !== "string") {
+                                continue;
+                            }
+                            if (blockName === toolName) {
+                                if (capturedToolUseId === null) {
+                                    capturedToolUseId = blockId;
+                                }
+                            }
+                            else if (blockName === DEFERRED_TOOL_DISCOVERY_TOOL_NAME) {
+                                // Expected intermediate step for loading the connector's
+                                // deferred MCP schema — not a violation. Do not capture as
+                                // wrongToolName so a partial trace (ToolSearch + max_turns
+                                // before the connector call) classifies as `no_tool_call`
+                                // instead of misleading `wrong_tool=ToolSearch`.
+                            }
+                            else if (wrongToolName === null) {
+                                wrongToolName = blockName;
+                                // Early abort: bound the wall-clock spend on a wrong_tool
+                                // failure to ~5s. Set `aborted` so the next loop iteration
+                                // breaks; close the SDK stream so any pending tool_use
+                                // doesn't continue. The post-loop classifier checks
+                                // `wrongToolName` BEFORE the abort branch, so the failure
+                                // is correctly attributed.
+                                aborted.value = true;
+                                closeStream();
+                            }
+                        }
+                    }
+                    else if (message.type === "user") {
+                        const userMsg = message;
+                        const content = userMsg.message?.content;
+                        if (!Array.isArray(content))
+                            continue;
+                        for (const block of content) {
+                            if (!block || typeof block !== "object")
+                                continue;
+                            if (block.type !== "tool_result")
+                                continue;
+                            const tuid = block.tool_use_id;
+                            if (tuid !== capturedToolUseId)
+                                continue;
+                            const isToolError = block.is_error === true;
+                            const rawContent = block.content;
+                            const flat = flattenToolResultContent(rawContent);
+                            if (isToolError) {
+                                capturedToolErrorMessage =
+                                    flat.trim().length > 0 ? flat : "tool returned is_error";
+                            }
+                            else if (capturedToolResult === undefined) {
+                                capturedToolResult = tryParseToolResult(flat);
+                            }
+                        }
+                    }
+                    else if (message.type === "result") {
+                        const r = message;
+                        terminalSubtype = r.subtype;
+                        terminalIsError = r.is_error;
+                        cost = {
+                            tokensInput: r.usage.input_tokens ?? 0,
+                            tokensOutput: r.usage.output_tokens ?? 0,
+                            cacheCreationTokens: r.usage.cache_creation_input_tokens ?? 0,
+                            cacheReadTokens: r.usage.cache_read_input_tokens ?? 0,
+                            costUsd: r.total_cost_usd ?? 0,
+                            durationMs: r.duration_ms ?? Date.now() - startMs,
+                            numTurns: r.num_turns ?? 0,
+                        };
+                        if (r.subtype !== "success" && "errors" in r && Array.isArray(r.errors)) {
+                            terminalErrors = r.errors;
+                        }
+                        // The result message is terminal per SDK semantics. Break out
+                        // before the next iterator step. When `r.is_error` is true, the
+                        // SDK's transport sets `lastErrorResultText` and throws on the
+                        // next `readMessages` iteration — wrapping it as
+                        // `Error("Claude Code returned an error result: <text>")`. That
+                        // throw would land in the outer catch and misclassify as
+                        // `subprocess_crashed`, discarding the captured cost. Audit log
+                        // (2026-04-29) showed 5 such failures with num_turns=0,
+                        // tokens=0, masking that this was actually `error_max_turns`.
+                        // Breaking here lets the post-loop classifier run with the
+                        // captured terminalSubtype, terminalErrors, wrongToolName, and
+                        // cost intact.
+                        break;
+                    }
+                }
+            }
+            finally {
+                idleWatchdog.stop();
+                try {
+                    await stream?.return?.(undefined);
+                }
+                catch {
+                    /* stream already closed */
+                }
+            }
+            cost = withDurationMs(cost, startMs);
+            // wrong_tool check hoisted above the abort branch because the
+            // early-abort path sets `aborted.value` AND `wrongToolName`.
+            // Without this ordering the failure would surface as `cancelled`
+            // instead of the actual upstream cause. The `abortReason` field
+            // distinguishes idle-watchdog aborts (errorClass="timeout") from
+            // caller-initiated cancels (errorClass="cancelled" unless the
+            // caller's reason was itself a `DelegatedProxyTimeoutError`).
+            if (wrongToolName !== null) {
+                return {
+                    ok: false,
+                    errorClass: "wrong_tool",
+                    message: `model called '${wrongToolName}' instead of requested '${toolName}'`,
+                    cost,
+                };
+            }
+            if (aborted.value) {
+                const reason = abortReason ?? params.abortSignal?.reason;
+                const errorClass = classifyAbortReason(reason);
+                const idleAbort = reason instanceof DelegatedProxyTimeoutError
+                    && /idle/.test(reason.message);
+                return {
+                    ok: false,
+                    errorClass,
+                    message: errorClass === "timeout"
+                        ? (idleAbort
+                            ? `delegated proxy stream went idle (no claude SDK events for ${idleTimeoutMs}ms)`
+                            : "delegated proxy timed out (wall-clock)")
+                        : "delegated proxy cancelled by caller",
+                    cost,
+                };
+            }
+            if (capturedToolResult !== undefined) {
+                return { ok: true, toolResult: capturedToolResult, cost };
+            }
+            if (capturedToolErrorMessage !== null) {
+                return {
+                    ok: false,
+                    errorClass: "tool_error",
+                    message: capturedToolErrorMessage,
+                    cost,
+                };
+            }
+            // Map specific terminal subtypes before falling through to
+            // no_tool_call. The model can fail for auth or budget reasons
+            // before ever emitting a tool_use block.
+            if (terminalSubtype === "error_during_execution" && terminalErrors.length > 0) {
+                const joined = terminalErrors.join("; ");
+                if (/auth|unauthorized|authentication_failed|invalid api key/i.test(joined)) {
+                    return {
+                        ok: false,
+                        errorClass: "auth_error",
+                        message: joined,
+                        cost,
+                    };
+                }
+                return {
+                    ok: false,
+                    errorClass: "tool_error",
+                    message: joined,
+                    cost,
+                };
+            }
+            if (terminalSubtype === null && !terminalIsError) {
+                // Stream ended before any terminal `result` arrived — abnormal
+                // termination not classified as an abort. Treat as parse_error
+                // so the route handler can surface the bug rather than retrying.
+                return {
+                    ok: false,
+                    errorClass: "parse_error",
+                    message: "Claude SDK stream ended without a terminal result message",
+                    cost,
+                };
+            }
+            return {
+                ok: false,
+                errorClass: "no_tool_call",
+                message: `model did not invoke '${toolName}' within ${maxTurns} turns (subtype=${terminalSubtype ?? "unknown"})`,
+                cost,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const cost = withDurationMs(emptyCost(), startMs);
+            // Map auth-shape exceptions before the catch-all subprocess_crashed.
+            if (/authentication_failed|unauthorized|invalid api key|sk-ant-/i.test(message)) {
+                return { ok: false, errorClass: "auth_error", message, cost };
+            }
+            if (aborted.value) {
+                return {
+                    ok: false,
+                    errorClass: classifyAbortReason(abortReason ?? params.abortSignal?.reason),
+                    message,
+                    cost,
+                };
+            }
+            return { ok: false, errorClass: "subprocess_crashed", message, cost };
+        }
+        finally {
+            params.abortSignal?.removeEventListener("abort", onAbort);
+            this.readTokenManager?.revoke(sessionDir);
+        }
+    }
+    /**
+     * DELEGATED-TASK-MODE-DESIGN.md §9.1 — Claude SDK task mode. The
+     * subprocess plans + executes 1..N MCP calls within `allowedTools` and
+     * emits a final assistant message that the runtime helper validates
+     * against the caller's `outputSchema`.
+     *
+     * Stream parsing differences from `runDelegatedTool`:
+     *   - We accept multiple `tool_use` blocks (counted against `maxToolCalls`).
+     *   - We track per-tool durations to feed `onToolStep`.
+     *   - We capture the *final* assistant text (after the last tool turn)
+     *     as the validation target, not a single tool's `tool_result`.
+     *
+     * Safety:
+     *   - `allowedTools` already excludes the destructive set when
+     *     `allowDestructive: false`; the SDK will not surface those tools.
+     *   - `disallowedTools` is the absolute-block layer + the destructive
+     *     set as defense-in-depth (so a future relaxation of allowedTools
+     *     can't accidentally widen the surface).
+     *
+     * The §6.2 "no retry after write" rule is enforced at the invoker
+     * layer; this method just signals via `writeClassToolFired` whether
+     * any destructive tool ran during the task.
+     */
+    async runDelegatedTask(params) {
+        const startMs = Date.now();
+        const { systemPrompt, allowedTools, destructiveTools, writeClassTools, modelId, maxToolCalls, maxBudgetUsd, sessionDir, onToolStep, } = params;
+        const daemonReadToken = this.readTokenManager?.issue(sessionDir) ?? this.readToken;
+        const trace = [];
+        // §6.2 / §7.4 — match against the *write-class* set (destructive ∪
+        // reversible writes), not just destructive. Otherwise reversible
+        // write tools like `create_draft` slip past the retry guard and the
+        // single retry creates a duplicate side effect.
+        //
+        // Phase 1 (`/exec`) entries are fully-qualified exact names — the
+        // exact-equality fast path inside `matchRunAllowedToolPattern` covers
+        // them at one comparison. Phase 2 (`/api/delegated/run`) may pass
+        // `*`-suffixed glob patterns derived from the caller's allowedTools
+        // (DELEGATED-TASK-MODE-DESIGN.md §4.2); the shared helper handles both.
+        const writeClassMatcher = (name) => writeClassTools.some((pattern) => matchRunAllowedToolPattern(pattern, name));
+        let writeClassToolFired = false;
+        // DELEGATED-TASK-MODE-DESIGN.md §13 Phase 3.1 — Claude SDK
+        // structured-output. When the invoker passed `structuredOutputEnabled:
+        // true` AND a `wrappedSchema`, configure `outputFormat` so the SDK
+        // validates the model's final emission against the schema (with its
+        // own internal retries) and surfaces it on `SDKResultSuccess.structured_output`.
+        // We still capture the assistant text as a fallback — if the SDK
+        // returns success without `structured_output` (older subtype, future
+        // shape change, kill-switch flips off mid-call), the existing text
+        // path takes over.
+        const useStructuredOutput = params.structuredOutputEnabled === true
+            && !!params.wrappedSchema;
+        let capturedStructured;
+        let sawStructuredOutputRetryError = false;
+        let stream = null;
+        const aborted = { value: false };
+        const onAbort = () => {
+            aborted.value = true;
+            void (async () => {
+                try {
+                    await stream?.return?.(undefined);
+                }
+                catch {
+                    /* stream already closed */
+                }
+            })();
+        };
+        if (params.abortSignal) {
+            if (params.abortSignal.aborted) {
+                aborted.value = true;
+            }
+            else {
+                params.abortSignal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+        const pendingByUseId = new Map();
+        let toolCallCount = 0;
+        let loopAborted = false;
+        let assistantTextChunks = [];
+        /** The "final" assistant message is the most recent assistant message
+         *  that contained NO `tool_use` block. The SDK emits one assistant
+         *  message per turn; the planning turns mix text + tool_use, the
+         *  closing turn is text-only. */
+        let lastAssistantTextOnlyChunks = [];
+        try {
+            stream = query({
+                prompt: systemPrompt,
+                options: {
+                    model: modelId,
+                    maxTurns: Math.max(2, maxToolCalls + 1),
+                    maxBudgetUsd,
+                    cwd: sessionDir,
+                    env: buildDaemonApiCliEnv(sessionDir, this.config.apiPort, { readToken: daemonReadToken, sessionBackend: "claude" }),
+                    systemPrompt: { type: "preset", preset: "claude_code" },
+                    permissionMode: "dontAsk",
+                    allowedTools: [...allowedTools],
+                    // Defense-in-depth: absolute-block layer + destructive denies.
+                    // Destructive entries are redundant with the allowedTools
+                    // subtraction (when allowDestructive=false) but kept so a
+                    // future allowedTools widening doesn't drop the guarantee.
+                    disallowedTools: [
+                        ...ALWAYS_DISALLOWED_TOOLS,
+                        ...(params.allowDestructive ? [] : destructiveTools),
+                    ],
+                    // §13 Phase 3.1 — bind the wrapped schema (user schema OR
+                    // confirmation envelope OR error envelope) to SDK 0.2.98's
+                    // `outputFormat`. Result message carries `structured_output`
+                    // which we read below. Off when the kill switch is false or
+                    // the invoker omitted the wrapped schema.
+                    ...(useStructuredOutput && params.wrappedSchema
+                        ? {
+                            outputFormat: {
+                                type: "json_schema",
+                                schema: params.wrappedSchema,
+                            },
+                        }
+                        : {}),
+                },
+            });
+            let cost = emptyCost();
+            try {
+                for await (const message of stream) {
+                    if (aborted.value || loopAborted)
+                        break;
+                    if (message.type === "assistant") {
+                        const assistantMsg = message;
+                        const blocks = assistantMsg.message?.content;
+                        if (!Array.isArray(blocks))
+                            continue;
+                        const textChunks = [];
+                        let sawToolUse = false;
+                        for (const block of blocks) {
+                            if (!block || typeof block !== "object")
+                                continue;
+                            const blockType = block.type;
+                            if (blockType === "text") {
+                                const text = block.text;
+                                if (typeof text === "string")
+                                    textChunks.push(text);
+                                continue;
+                            }
+                            if (blockType !== "tool_use")
+                                continue;
+                            sawToolUse = true;
+                            const blockName = block.name;
+                            const blockId = block.id;
+                            const blockArgs = block.input;
+                            if (typeof blockName !== "string" || typeof blockId !== "string") {
+                                continue;
+                            }
+                            toolCallCount += 1;
+                            if (toolCallCount > maxToolCalls) {
+                                // §7.5 — once the cap is exceeded, abort. The next
+                                // tool_use is treated as overrun.
+                                loopAborted = true;
+                                aborted.value = true;
+                                try {
+                                    await stream?.return?.(undefined);
+                                }
+                                catch {
+                                    /* already closed */
+                                }
+                                break;
+                            }
+                            if (writeClassMatcher(blockName)) {
+                                writeClassToolFired = true;
+                            }
+                            pendingByUseId.set(blockId, {
+                                name: blockName,
+                                args: blockArgs,
+                                startedAt: Date.now(),
+                            });
+                        }
+                        assistantTextChunks = assistantTextChunks.concat(textChunks);
+                        if (!sawToolUse && textChunks.length > 0) {
+                            lastAssistantTextOnlyChunks = textChunks;
+                        }
+                    }
+                    else if (message.type === "user") {
+                        const userMsg = message;
+                        const content = userMsg.message?.content;
+                        if (!Array.isArray(content))
+                            continue;
+                        for (const block of content) {
+                            if (!block || typeof block !== "object")
+                                continue;
+                            if (block.type !== "tool_result")
+                                continue;
+                            const tuid = block.tool_use_id;
+                            if (typeof tuid !== "string")
+                                continue;
+                            const pending = pendingByUseId.get(tuid);
+                            if (!pending)
+                                continue;
+                            pendingByUseId.delete(tuid);
+                            const isToolError = block.is_error === true;
+                            // `tool_result` content is either a string or an array of
+                            // content blocks (typically a single `{type:"text", text}`).
+                            // The MCP SDK wraps connector JSON responses by serializing
+                            // to that text body, so the response-shape walker
+                            // downstream wants the parsed object. Pull the first text
+                            // block, JSON-parse when possible, fallback to the raw
+                            // string so the field is always populated for ok steps.
+                            let parsedToolResult;
+                            const blockContent = block.content;
+                            if (typeof blockContent === "string") {
+                                try {
+                                    parsedToolResult = JSON.parse(blockContent);
+                                }
+                                catch {
+                                    parsedToolResult = blockContent;
+                                }
+                            }
+                            else if (Array.isArray(blockContent)) {
+                                const firstText = blockContent.find((b) => !!b
+                                    && typeof b === "object"
+                                    && b.type === "text"
+                                    && typeof b.text === "string");
+                                if (firstText) {
+                                    try {
+                                        parsedToolResult = JSON.parse(firstText.text);
+                                    }
+                                    catch {
+                                        parsedToolResult = firstText.text;
+                                    }
+                                }
+                                else {
+                                    parsedToolResult = blockContent;
+                                }
+                            }
+                            const step = {
+                                toolName: pending.name,
+                                toolArgs: pending.args,
+                                durationMs: Date.now() - pending.startedAt,
+                                status: isToolError ? "error" : "ok",
+                                costUsd: null,
+                                tokensInput: null,
+                                tokensOutput: null,
+                                toolResult: parsedToolResult,
+                            };
+                            trace.push(step);
+                            onToolStep?.(step);
+                        }
+                    }
+                    else if (message.type === "result") {
+                        const r = message;
+                        cost = {
+                            tokensInput: r.usage.input_tokens ?? 0,
+                            tokensOutput: r.usage.output_tokens ?? 0,
+                            cacheCreationTokens: r.usage.cache_creation_input_tokens ?? 0,
+                            cacheReadTokens: r.usage.cache_read_input_tokens ?? 0,
+                            costUsd: r.total_cost_usd ?? 0,
+                            durationMs: r.duration_ms ?? Date.now() - startMs,
+                            numTurns: r.num_turns ?? 0,
+                        };
+                        // §13 Phase 3.1 — capture structured output when present, and
+                        // map the SDK's structured-output-retry-exhausted subtype to
+                        // a parse_error so the invoker classifies it consistently
+                        // with the text-extract path.
+                        if (r.subtype === "success") {
+                            const success = r;
+                            if (success.structured_output !== undefined) {
+                                capturedStructured = success.structured_output;
+                            }
+                        }
+                        else if (r.subtype === "error_max_structured_output_retries") {
+                            sawStructuredOutputRetryError = true;
+                        }
+                    }
+                }
+            }
+            finally {
+                try {
+                    await stream?.return?.(undefined);
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+            cost = withDurationMs(cost, startMs);
+            if (loopAborted) {
+                return {
+                    ok: false,
+                    errorClass: "loop_aborted",
+                    message: `subprocess exceeded maxToolCalls=${maxToolCalls}`,
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            if (aborted.value) {
+                const errorClass = classifyAbortReason(params.abortSignal?.reason);
+                return {
+                    ok: false,
+                    errorClass,
+                    message: errorClass === "timeout"
+                        ? "delegated task timed out (wall-clock)"
+                        : "delegated task cancelled by caller",
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            const finalText = lastAssistantTextOnlyChunks.length > 0
+                ? lastAssistantTextOnlyChunks.join("\n").trim()
+                : assistantTextChunks.join("\n").trim();
+            // §13 Phase 3.1 — `error_max_structured_output_retries` typically
+            // fires when the model wanted to emit a §7.2 confirmation envelope
+            // or §5.1 error envelope, neither of which satisfies the user's
+            // narrow schema. The assistant text emissions captured during those
+            // retries land in `assistantTextChunks` / `lastAssistantTextOnlyChunks`,
+            // so the invoker's text-extract chain can route them via
+            // `detectConfirmationEnvelope` / `detectErrorEnvelope`. Only return
+            // `parse_error` if there is also no usable text — otherwise fall
+            // through to the text-emission path (no `structuredOutput` field
+            // set, so the invoker uses `rawAssistantText`).
+            if (sawStructuredOutputRetryError
+                && capturedStructured === undefined
+                && finalText.length === 0) {
+                return {
+                    ok: false,
+                    errorClass: "parse_error",
+                    message: "Claude SDK exhausted structured-output retries and emitted no text fallback.",
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            // §13 Phase 3.1 — when the SDK supplied `structured_output`, that
+            // is the validated final emission; the assistant text may be empty
+            // (the SDK consumes the JSON internally on success). Skip the
+            // empty-text parse_error guard in that case.
+            if (capturedStructured === undefined && finalText.length === 0) {
+                return {
+                    ok: false,
+                    errorClass: "parse_error",
+                    message: "Claude SDK stream ended without a text-only assistant turn",
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            return {
+                ok: true,
+                // When structured output is present, `rawAssistantText` is purely
+                // a fallback; the invoker prefers `structuredOutput`. Carry both
+                // so a future kill-switch flip mid-restart still sees an
+                // extractable text emission.
+                rawAssistantText: finalText,
+                cost,
+                trace,
+                writeClassToolFired,
+                ...(capturedStructured !== undefined
+                    ? { structuredOutput: capturedStructured }
+                    : {}),
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const cost = withDurationMs(emptyCost(), startMs);
+            if (/authentication_failed|unauthorized|invalid api key|sk-ant-/i.test(message)) {
+                return {
+                    ok: false,
+                    errorClass: "auth_error",
+                    message,
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            if (aborted.value) {
+                return {
+                    ok: false,
+                    errorClass: classifyAbortReason(params.abortSignal?.reason),
+                    message,
+                    cost,
+                    trace,
+                    writeClassToolFired,
+                };
+            }
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message,
+                cost,
+                trace,
+                writeClassToolFired,
+            };
+        }
+        finally {
+            params.abortSignal?.removeEventListener("abort", onAbort);
+            this.readTokenManager?.revoke(sessionDir);
+        }
+    }
+}
+function extractClaudeProbeTools(message) {
+    if (!message || typeof message !== "object")
+        return [];
+    const out = [];
+    const record = message;
+    if (record.type === "system" && record.subtype === "init" && Array.isArray(record.tools)) {
+        addClaudeProbeTools(record.tools, out);
+    }
+    if (record.type === "assistant" || record.type === "user") {
+        addClaudeProbeTools(record.message, out);
+    }
+    if (record.type === "result") {
+        addClaudeProbeTools(record.result, out);
+    }
+    return out;
+}
+function addClaudeProbeTools(value, out, depth = 0) {
+    if (depth > 8 || value === null || value === undefined)
+        return;
+    if (typeof value === "string") {
+        for (const match of value.matchAll(CLAUDE_CONNECTOR_TOOL_RE)) {
+            out.push(match[0]);
+        }
+        if (isClaudeProbeToolName(value))
+            out.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            addClaudeProbeTools(item, out, depth + 1);
+        return;
+    }
+    if (typeof value !== "object")
+        return;
+    const record = value;
+    addClaudeProbeTools(record.tool_name, out, depth + 1);
+    addClaudeProbeTools(record.text, out, depth + 1);
+    addClaudeProbeTools(record.content, out, depth + 1);
+    addClaudeProbeTools(record.message, out, depth + 1);
+    addClaudeProbeTools(record.result, out, depth + 1);
+    addClaudeProbeTools(record.tools, out, depth + 1);
+}
+function isClaudeProbeToolName(value) {
+    return CLAUDE_PROBE_TOOL_PREFIXES.some((prefix) => {
+        if (!value.startsWith(prefix))
+            return false;
+        // Hyphen is part of the alphabet for kebab-case connectors (Notion's
+        // `notion-search` etc.). Snake-case connectors keep working because
+        // `_` is still in the class.
+        return /^[A-Za-z0-9_-]+$/.test(value.slice(prefix.length));
+    });
+}
+function describeClaudeProbeResultError(result) {
+    if ("result" in result && typeof result.result === "string" && result.result.trim()) {
+        return result.result.trim();
+    }
+    if ("errors" in result && Array.isArray(result.errors) && result.errors.length > 0) {
+        return result.errors.join("; ");
+    }
+    return result.subtype;
+}
+//# sourceMappingURL=claude-code-core.js.map