comisai 1.0.37 → 1.0.40

package/node_modules/@comis/daemon/dist/wiring/setup-cross-session/setup-cross-session-events.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Proxy typing event listener registration for cross-session messaging.
+ *
+ * Hosts the `typing:proxy_start` / `typing:proxy_stop` event handlers and
+ * the TTL sweep timer that the registry orchestrator wires after
+ * sub-agent runner construction. The handlers create per-run
+ * TypingController instances scoped to the parent-channel adapter and
+ * clean up on graceful shutdown.
+ *
+ * @module
+ */
+import { systemNowMs, systemSetInterval, systemClearInterval } from "@comis/core";
+import { createTypingController } from "@comis/channels";
+/** Per-platform typing refresh intervals (matches inbound-pipeline.ts). */
+const PROXY_TYPING_REFRESH = {
+    telegram: 4000,
+    discord: 8000,
+    whatsapp: 8000,
+    signal: 4000,
+    line: 15000,
+    imessage: 4000,
+};
+const PROXY_TTL_MS = 300_000; // 5 min max (matches sub-agent watchdog)
+const PROXY_SWEEP_INTERVAL_MS = 60_000; // Sweep every 60s
+/**
+ * Register the proxy typing event handlers on the daemon event bus. Three
+ * listeners are attached:
+ *   1. `typing:proxy_start` — create TypingController for parent channel
+ *      (no-op when the platform lacks typing support or the runId is already
+ *      tracked).
+ *   2. `typing:proxy_stop` — stop the controller and remove the entry.
+ *   3. `system:shutdown` — stop every active controller + clear the TTL
+ *      sweep timer.
+ *
+ * Additionally schedules a TTL sweep timer that stops any controller older
+ * than 5 minutes (mirrors the sub-agent watchdog timeout).
+ */
+export function registerProxyTypingListeners(deps) {
+    const { container, adaptersByType, logger } = deps;
+    const proxyControllers = new Map();
+    // typing:proxy_start — create TypingController for parent channel
+    container.eventBus.on("typing:proxy_start", (evt) => {
+        // Skip duplicate proxy for same run
+        if (proxyControllers.has(evt.runId))
+            return;
+        // Skip channels without typing support
+        const refreshMs = PROXY_TYPING_REFRESH[evt.channelType];
+        if (!refreshMs)
+            return;
+        const adapter = adaptersByType.get(evt.channelType);
+        if (!adapter?.platformAction)
+            return;
+        const boundPlatformAction = adapter.platformAction.bind(adapter);
+        const controller = createTypingController({ mode: "thinking", refreshMs, ttlMs: PROXY_TTL_MS }, async (chatId) => {
+            // Pass threadId for forum topic routing
+            await boundPlatformAction("sendTyping", { chatId, ...(evt.threadId ? { threadId: evt.threadId } : {}) });
+        }, { warn: (obj, msg) => logger?.warn(obj, msg) });
+        controller.start(evt.channelId);
+        proxyControllers.set(evt.runId, {
+            controller,
+            startedAt: systemNowMs(),
+        });
+        logger?.debug({
+            runId: evt.runId,
+            channelType: evt.channelType,
+            channelId: evt.channelId,
+            agentId: evt.agentId,
+        }, "Proxy typing started for sub-agent run");
+    });
+    // typing:proxy_stop — stop and remove controller
+    container.eventBus.on("typing:proxy_stop", (evt) => {
+        const entry = proxyControllers.get(evt.runId);
+        if (!entry)
+            return;
+        entry.controller.stop();
+        proxyControllers.delete(evt.runId);
+        logger?.debug({
+            runId: evt.runId,
+            reason: evt.reason,
+            durationMs: evt.durationMs,
+        }, "Proxy typing stopped for sub-agent run");
+    });
+    // TTL sweep timer — clean up leaked entries
+    const proxySweepTimer = systemSetInterval(() => {
+        const now = systemNowMs();
+        for (const [runId, entry] of proxyControllers) {
+            if (now - entry.startedAt > PROXY_TTL_MS) {
+                entry.controller.stop();
+                proxyControllers.delete(runId);
+                logger?.debug({ runId, reason: "ttl_expired" }, "Proxy typing TTL expired");
+            }
+        }
+    }, PROXY_SWEEP_INTERVAL_MS);
+    proxySweepTimer.unref(); // Do not prevent process exit
+    // Shutdown cleanup — stop all proxy controllers and clear sweep timer
+    container.eventBus.on("system:shutdown", () => {
+        systemClearInterval(proxySweepTimer);
+        for (const [, entry] of proxyControllers) {
+            entry.controller.stop();
+        }
+        proxyControllers.clear();
+    });
+}

package/node_modules/@comis/daemon/dist/wiring/setup-cross-session/setup-cross-session-graph.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Graph-execution wiring for cross-session sub-agent spawns.
+ *
+ * Hosts the `executeSubAgent` closure builder + graph-tree primitives:
+ * `resolveGraphCacheRetention` (depth-aware leaf-node retention), the
+ * `SUB_AGENT_TOOL_DENYLIST` ten-tool set (management tools that would
+ * trigger SIGUSR2 daemon restart), and `MIN_SUB_AGENT_STEPS` (the step
+ * budget floor that protects boot-sequence consumption).
+ *
+ * The runtime leaf wires the resulting executeSubAgent into createSubAgentRunner.
+ *
+ * @module
+ */
+import type { SessionKey, AppContainer, FileLockPort } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+/**
+ * Resolve cache retention for a graph sub-agent.
+ *
+ * Default "long" (1h TTL) — depth-aware "short" for root nodes was tried and
+ * caused regressions: final pipeline nodes running 10-15 min after root nodes
+ * got 0 cache reads because the shared prefix expired. The 1h write premium
+ * is far cheaper than the cache misses it prevents.
+ *
+ * Exception: **leaf nodes** (no downstream dependents) use "short". Their
+ * cache prefix has no consumers — no later node will read from it — so the
+ * 1h write premium is pure waste. Observed in NVDA trade-desk pipeline: the
+ * head-trader node wrote 16,663 1h tokens (~$0.17) that were never reused
+ * because the pipeline ends at that node.
+ *
+ * @param _graphNodeDepth unused — kept for interface stability
+ * @param isLeafNode true when no other graph node depends on this one
+ * @returns "short" for leaf nodes, "long" otherwise
+ */
+export declare function resolveGraphCacheRetention(_graphNodeDepth: number | undefined, isLeafNode?: boolean): "short" | "long";
+/** Minimum step budget for sub-agent spawns — prevents boot sequence from consuming all steps. */
+export declare const MIN_SUB_AGENT_STEPS = 30;
+/** Tools denied to sub-agents -- management tools that trigger SIGUSR2 daemon restart. */
+export declare const SUB_AGENT_TOOL_DENYLIST: Set<string>;
+/**
+ * Closure-captured deps for the executeSubAgent callback.
+ */
+export interface ExecuteSubAgentDeps {
+    container: AppContainer;
+    sessionStore: {
+        loadByFormattedKey(key: string): {
+            messages: unknown[];
+            metadata: Record<string, unknown>;
+        } | undefined;
+    };
+    assembleToolsForAgent: (agentId: string, options?: import("../setup-tools.js").AssembleToolsOptions) => Promise<any[]>;
+    getExecutor: (agentId: string) => {
+        execute: (...args: any[]) => Promise<any>;
+    };
+    fileLock: FileLockPort;
+    logger?: ComisLogger;
+}
+/**
+ * The executeSubAgent callback signature accepted by createSubAgentRunner.
+ */
+export type ExecuteSubAgentFn = (agentId: string, sessionKey: SessionKey, task: string, maxSteps?: number, callerAgentId?: string, graphOverrides?: {
+    graphId?: string;
+    nodeId?: string;
+    reuseSessionKey?: string;
+    graphNodeDepth?: number;
+}) => Promise<{
+    response: string;
+    tokensUsed: {
+        total: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    };
+    cost: {
+        total: number;
+        cacheSaved?: number;
+    };
+    finishReason: string;
+    stepsExecuted: number;
+    toolCallHistory?: string[];
+}>;
+/**
+ * Build the executeSubAgent callback wired into createSubAgentRunner. The
+ * closure captures the daemon container + session store + tool assembler +
+ * executor resolver, plus FileLockPort for the ephemeral session adapter.
+ *
+ * Covers spawn-packet construction, sub-agent tool intersection (parent →
+ * ceiling → denylist), graph tool sorting, parent context summarization,
+ * sub-agent model resolution, cache retention selection, ephemeral vs
+ * persistent session adapter, and runWithContext propagation.
+ */
+export declare function buildExecuteSubAgent(deps: ExecuteSubAgentDeps): ExecuteSubAgentFn;

package/node_modules/@comis/daemon/dist/wiring/setup-cross-session/setup-cross-session-graph.js

@@ -0,0 +1,419 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Graph-execution wiring for cross-session sub-agent spawns.
+ *
+ * Hosts the `executeSubAgent` closure builder + graph-tree primitives:
+ * `resolveGraphCacheRetention` (depth-aware leaf-node retention), the
+ * `SUB_AGENT_TOOL_DENYLIST` ten-tool set (management tools that would
+ * trigger SIGUSR2 daemon restart), and `MIN_SUB_AGENT_STEPS` (the step
+ * budget floor that protects boot-sequence consumption).
+ *
+ * The runtime leaf wires the resulting executeSubAgent into createSubAgentRunner.
+ *
+ * @module
+ */
+import { tryGetContext, runWithContext, formatSessionKey, safePath, systemNowMs, resolveWorkspaceDir } from "@comis/core";
+import { createStepCounter, createSpawnPacketBuilder, generateParentSummary, createEphemeralComisSessionManager, createComisSessionManager, getCacheSafeParams, resolveOperationModel, resolveProviderFamily, } from "@comis/agent";
+import { randomUUID } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Depth-aware graph cache retention
+// ---------------------------------------------------------------------------
+/**
+ * Resolve cache retention for a graph sub-agent.
+ *
+ * Default "long" (1h TTL) — depth-aware "short" for root nodes was tried and
+ * caused regressions: final pipeline nodes running 10-15 min after root nodes
+ * got 0 cache reads because the shared prefix expired. The 1h write premium
+ * is far cheaper than the cache misses it prevents.
+ *
+ * Exception: **leaf nodes** (no downstream dependents) use "short". Their
+ * cache prefix has no consumers — no later node will read from it — so the
+ * 1h write premium is pure waste. Observed in NVDA trade-desk pipeline: the
+ * head-trader node wrote 16,663 1h tokens (~$0.17) that were never reused
+ * because the pipeline ends at that node.
+ *
+ * @param _graphNodeDepth unused — kept for interface stability
+ * @param isLeafNode true when no other graph node depends on this one
+ * @returns "short" for leaf nodes, "long" otherwise
+ */
+export function resolveGraphCacheRetention(_graphNodeDepth, isLeafNode) {
+    if (isLeafNode === true)
+        return "short";
+    return "long";
+}
+// ---------------------------------------------------------------------------
+// Sub-agent tool denylist
+// ---------------------------------------------------------------------------
+/** Minimum step budget for sub-agent spawns — prevents boot sequence from consuming all steps. */
+export const MIN_SUB_AGENT_STEPS = 30;
+/** Tools denied to sub-agents -- management tools that trigger SIGUSR2 daemon restart. */
+export const SUB_AGENT_TOOL_DENYLIST = new Set([
+    "gateway", // config.patch, gateway.restart, config.rollback, env.set -> SIGUSR2
+    "channels_manage", // channels.restart, config.patch -> SIGUSR2
+    "agents_manage", // agent create/delete -> config persistence -> SIGUSR2
+    "models_manage", // model config changes -> config persistence -> SIGUSR2
+    "providers_manage", // provider CRUD -> config persistence -> SIGUSR2
+    "tokens_manage", // token CRUD -> config persistence -> SIGUSR2
+    "skills_manage", // skill config changes -> config persistence -> potential SIGUSR2
+    "sessions_manage", // session purge is destructive
+    "memory_manage", // memory purge is destructive
+    "heartbeat_manage", // heartbeat config -> config persistence -> potential SIGUSR2
+]);
+/**
+ * Build the executeSubAgent callback wired into createSubAgentRunner. The
+ * closure captures the daemon container + session store + tool assembler +
+ * executor resolver, plus FileLockPort for the ephemeral session adapter.
+ *
+ * Covers spawn-packet construction, sub-agent tool intersection (parent →
+ * ceiling → denylist), graph tool sorting, parent context summarization,
+ * sub-agent model resolution, cache retention selection, ephemeral vs
+ * persistent session adapter, and runWithContext propagation.
+ */
+export function buildExecuteSubAgent(deps) {
+    const { container, sessionStore, assembleToolsForAgent, getExecutor } = deps;
+    return async (agentId, sessionKey, task, maxSteps, callerAgentId, graphOverrides) => {
+        deps.logger?.debug({
+            agentId,
+            callerAgentId,
+            channelId: sessionKey.channelId,
+            maxSteps,
+            isGraphSpawn: !!graphOverrides?.graphId,
+            isReuseSession: !!graphOverrides?.reuseSessionKey,
+            graphNodeDepth: graphOverrides?.graphNodeDepth,
+        }, "executeSubAgent invoked");
+        // Read channelType from ALS DeliveryOrigin instead of hardcoding "gateway"
+        const ctx = tryGetContext();
+        const originChannelType = ctx?.deliveryOrigin?.channelType ?? ctx?.channelType ?? "gateway";
+        const msg = {
+            id: randomUUID(),
+            channelId: sessionKey.channelId,
+            channelType: originChannelType,
+            senderId: "parent-agent",
+            text: task,
+            timestamp: systemNowMs(),
+            attachments: [],
+            metadata: {},
+        };
+        // Fresh step counter per sub-agent spawn (isolated from parent/siblings).
+        // Per-spawn maxSteps is capped at config default (cannot exceed).
+        const configMaxSteps = container.config.security.agentToAgent.subAgentMaxSteps;
+        // Floor prevents boot sequence from consuming all steps (see MIN_SUB_AGENT_STEPS)
+        const effectiveMaxSteps = Math.max(MIN_SUB_AGENT_STEPS, maxSteps !== undefined ? Math.min(maxSteps, configMaxSteps) : configMaxSteps);
+        const freshStepCounter = createStepCounter(effectiveMaxSteps);
+        // Read spawn packet fields from session metadata
+        const formattedKey = formatSessionKey(sessionKey);
+        const sessionData = sessionStore.loadByFormattedKey(formattedKey);
+        const meta = sessionData?.metadata ?? {};
+        // Detect reuse-session spawns for persistent multi-round drivers
+        const isReuseSession = !!graphOverrides?.reuseSessionKey;
+        // Per-spawn toolGroups override config default (can only narrow, never widen)
+        const configToolGroups = container.config.security.agentToAgent.subAgentToolGroups;
+        const spawnToolGroups = Array.isArray(meta.toolGroups) && meta.toolGroups.length > 0
+            ? meta.toolGroups
+            : undefined;
+        const effectiveToolGroups = spawnToolGroups ?? configToolGroups;
+        // Read graphSharedDir from session metadata for shared pipeline folder access
+        const graphSharedDir = typeof meta.graphSharedDir === "string" && meta.graphSharedDir.length > 0
+            ? meta.graphSharedDir
+            : undefined;
+        deps.logger?.debug({
+            formattedKey,
+            graphSharedDir: graphSharedDir ?? "(none)",
+            isReuseSession,
+            metaKeys: Object.keys(meta),
+        }, "graphSharedDir propagation for sub-agent tool assembly");
+        // Read graphNodeDepth from session metadata for depth-aware cache retention
+        const graphNodeDepth = typeof meta.graphNodeDepth === "number" ? meta.graphNodeDepth : undefined;
+        // Leaf nodes (no downstream dependents) use "short" cache retention.
+        const isLeafNode = meta.isLeafNode === true;
+        // Read subAgentMcpTools config for MCP tool inheritance policy
+        const mcpPolicy = container.config.security.agentToAgent.subAgentMcpTools;
+        // WORKSPACE-INHERIT: When sub-agent has no dedicated config, inherit caller's
+        // config/workspace instead of falling back to default agent.
+        const effectiveAgentId = (agentId in container.config.agents)
+            ? agentId
+            : (callerAgentId && callerAgentId in container.config.agents ? callerAgentId : agentId);
+        if (effectiveAgentId !== agentId) {
+            deps.logger?.debug({
+                subAgentId: agentId,
+                effectiveAgentId,
+                callerAgentId,
+            }, "Sub-agent inheriting caller workspace (no dedicated config)");
+        }
+        let tools = await assembleToolsForAgent(effectiveAgentId, {
+            includePlatformTools: true,
+            toolGroups: effectiveToolGroups,
+            includeMcpTools: mcpPolicy === "inherit",
+            sharedPaths: graphSharedDir ? [graphSharedDir] : undefined,
+        });
+        // Intersect sub-agent tools with parent's resolved tool set.
+        // Sub-agent tools = intersection(parent resolved tools, ceiling-filtered tools).
+        // Prevents privilege escalation: sub-agent can never have a tool the parent doesn't have.
+        if (callerAgentId) {
+            const parentTools = await assembleToolsForAgent(callerAgentId);
+            const parentToolNames = new Set(parentTools.map((t) => t.name));
+            const ceilingCount = tools.length;
+            const beforeFilter = tools;
+            tools = tools.filter((t) => parentToolNames.has(t.name));
+            const droppedTools = beforeFilter
+                .filter((t) => !parentToolNames.has(t.name))
+                .map((t) => t.name);
+            deps.logger?.debug({
+                parentAgentId: callerAgentId,
+                parentToolCount: parentToolNames.size,
+                ceilingToolCount: ceilingCount,
+                effectiveToolCount: tools.length,
+                droppedTools,
+            }, "Sub-agent tool inheritance applied");
+            if (tools.length === 0 && ceilingCount > 0) {
+                deps.logger?.warn({
+                    parentAgentId: callerAgentId,
+                    parentToolCount: parentToolNames.size,
+                    ceilingToolCount: ceilingCount,
+                    hint: "All sub-agent tools dropped by parent intersection; sub-agent will have no tools.",
+                    errorKind: "config",
+                }, "Sub-agent tool inheritance: all tools dropped");
+            }
+        }
+        // Re-apply target agent's builtinTools ceiling after parent intersection.
+        const targetAgentConfig = container.config.agents[agentId];
+        if (targetAgentConfig?.skills?.builtinTools) {
+            const bt = targetAgentConfig.skills.builtinTools;
+            const beforeCeiling2 = tools.length;
+            const ceiling2Dropped = [];
+            tools = tools.filter((t) => {
+                if (t.name === "exec" && !bt.exec) {
+                    ceiling2Dropped.push("exec");
+                    return false;
+                }
+                if (t.name === "process" && !bt.process) {
+                    ceiling2Dropped.push("process");
+                    return false;
+                }
+                if (t.name === "browser" && !bt.browser) {
+                    ceiling2Dropped.push("browser");
+                    return false;
+                }
+                return true;
+            });
+            if (ceiling2Dropped.length > 0) {
+                deps.logger?.debug({
+                    agentId,
+                    builtinTools: { exec: bt.exec, process: bt.process, browser: bt.browser },
+                    beforeCount: beforeCeiling2,
+                    effectiveToolCount: tools.length,
+                    droppedByCeiling2: ceiling2Dropped,
+                }, "builtinTools ceiling defense-in-depth applied");
+            }
+        }
+        // Remove management tools that could trigger SIGUSR2 daemon restart.
+        const beforeDenylist = tools.length;
+        const deniedTools = [];
+        tools = tools.filter((t) => {
+            if (SUB_AGENT_TOOL_DENYLIST.has(t.name)) {
+                deniedTools.push(t.name);
+                return false;
+            }
+            return true;
+        });
+        if (deniedTools.length > 0) {
+            deps.logger?.debug({
+                deniedTools,
+                beforeCount: beforeDenylist,
+                effectiveToolCount: tools.length,
+            }, "Sub-agent tool denylist applied");
+        }
+        // Read graph tool superset from session metadata for cache prefix sharing
+        const graphToolNames = Array.isArray(meta.graphToolNames) && meta.graphToolNames.length > 0
+            ? meta.graphToolNames
+            : undefined;
+        // When graph tool superset is active, sort tools deterministically by name
+        // for byte-identical rendering across sibling graph nodes.
+        if (graphToolNames && graphToolNames.length > 0) {
+            const currentToolNames = new Set(tools.map((t) => t.name));
+            const missingNames = graphToolNames.filter(n => !currentToolNames.has(n));
+            if (missingNames.length > 0) {
+                deps.logger?.debug({
+                    missingToolCount: missingNames.length,
+                    missingTools: missingNames,
+                }, "Graph superset has tools not in current set (filtered by security policy)");
+            }
+            tools.sort((a, b) => a.name.localeCompare(b.name));
+            deps.logger?.debug({
+                graphToolCount: graphToolNames.length,
+                effectiveToolCount: tools.length,
+                sorted: true,
+            }, "Graph tool superset applied -- tools sorted for cache prefix sharing");
+        }
+        // Generate parent context summary when includeParentHistory is "summary"
+        let parentSummary;
+        if (meta.includeParentHistory === "summary" && meta.parentSessionKey) {
+            const parentSession = sessionStore.loadByFormattedKey(meta.parentSessionKey);
+            if (parentSession?.messages?.length) {
+                try {
+                    const subagentCtxConfig = container.config.security.agentToAgent.subagentContext;
+                    const agentConfig = container.config.agents[agentId] ?? container.config.agents["default"];
+                    const modelId = agentConfig?.model ?? "default";
+                    const providerId = agentConfig?.provider ?? "anthropic";
+                    const providerEntry = container.config.providers.entries[providerId];
+                    const apiKeyName = providerEntry?.apiKeyName || `${providerId.toUpperCase()}_API_KEY`;
+                    const apiKey = container.secretManager.get(apiKeyName) ?? "";
+                    if (apiKey) {
+                        parentSummary = await generateParentSummary({
+                            messages: parentSession.messages,
+                            model: { id: modelId, provider: providerId },
+                            maxTokens: subagentCtxConfig?.parentSummaryMaxTokens ?? 1000,
+                            apiKey,
+                        });
+                    }
+                    else {
+                        deps.logger?.warn({
+                            hint: "Cannot generate parent summary: no API key resolved for provider",
+                            errorKind: "config",
+                            providerId,
+                        }, "Parent summary generation skipped: missing API key");
+                    }
+                }
+                catch (err) {
+                    deps.logger?.warn({
+                        err,
+                        hint: "Parent summary generation failed; proceeding without summary",
+                        errorKind: "dependency",
+                    }, "generateParentSummary failed for parent context");
+                }
+            }
+        }
+        // Build SpawnPacket from session metadata if spawn fields are present
+        let spawnPacket;
+        if (meta.taskDescription && !isReuseSession) {
+            const spawnAgentConfig = container.config.agents[effectiveAgentId];
+            const workspaceDir = spawnAgentConfig
+                ? resolveWorkspaceDir(spawnAgentConfig, effectiveAgentId)
+                : resolveWorkspaceDir(container.config.agents["default"] ?? {}, effectiveAgentId);
+            const agentWorkspaces = {};
+            for (const [id, agentCfg] of Object.entries(container.config.agents)) {
+                agentWorkspaces[id] = resolveWorkspaceDir(agentCfg, id);
+            }
+            const builder = createSpawnPacketBuilder({
+                workspaceDir,
+                currentDepth: (meta.spawnDepth ?? 1) - 1,
+                maxSpawnDepth: meta.maxSpawnDepth ?? 3,
+                agentWorkspaces,
+            });
+            spawnPacket = builder.build({
+                task: meta.taskDescription,
+                artifactRefs: meta.artifactRefs ?? [],
+                objective: meta.objective ?? "",
+                toolGroups: meta.toolGroups ?? [],
+                includeParentHistory: (meta.includeParentHistory ?? "none"),
+                domainKnowledge: meta.domainKnowledge ?? [],
+            });
+            if (parentSummary) {
+                spawnPacket.parentSummary = parentSummary;
+            }
+            const discoveredDeferredTools = meta.discoveredDeferredTools;
+            if (Array.isArray(discoveredDeferredTools) && discoveredDeferredTools.length > 0) {
+                spawnPacket.discoveredDeferredTools = discoveredDeferredTools;
+            }
+            if (ctx?.sessionKey) {
+                const parentCacheSafe = getCacheSafeParams(ctx.sessionKey);
+                if (parentCacheSafe) {
+                    spawnPacket.cacheSafeParams = parentCacheSafe;
+                    deps.logger?.debug({
+                        callerAgentId: callerAgentId ?? "unknown",
+                        subAgentId: agentId,
+                        parentModel: parentCacheSafe.model,
+                        parentProvider: parentCacheSafe.provider,
+                    }, "Attached parent CacheSafeParams to SpawnPacket for prefix sharing");
+                }
+            }
+        }
+        // Read per-node model override from session metadata
+        const modelOverride = typeof meta.modelOverride === "string" && meta.modelOverride.length > 0
+            ? meta.modelOverride
+            : undefined;
+        // Resolve sub-agent model through 5-level priority chain
+        const subAgentConfig = container.config.agents[effectiveAgentId]
+            ?? container.config.agents["default"];
+        const parentResolvedModel = tryGetContext()?.resolvedModel;
+        const subagentResolution = subAgentConfig ? resolveOperationModel({
+            operationType: "subagent",
+            agentProvider: subAgentConfig.provider,
+            agentModel: subAgentConfig.model,
+            operationModels: subAgentConfig.operationModels ?? {},
+            providerFamily: resolveProviderFamily(subAgentConfig.provider),
+            invocationOverride: modelOverride,
+            parentModel: parentResolvedModel,
+            agentPromptTimeoutMs: subAgentConfig.promptTimeout?.promptTimeoutMs,
+        }) : undefined;
+        deps.logger?.debug({ agentId, model: subagentResolution?.model, source: subagentResolution?.source, operationType: "subagent", parentResolvedModel }, "Subagent model resolved");
+        const isGraphSpawn = typeof graphSharedDir === "string" && graphSharedDir.length > 0;
+        const GRAPH_PROMPT_TIMEOUT_MS = 600_000;
+        // Base subagent retention "short" (5m TTL); graph sub-agents get depth-aware.
+        const subAgentCacheRetention = graphSharedDir
+            ? resolveGraphCacheRetention(graphNodeDepth, isLeafNode)
+            : "short";
+        // Session adapter for sub-agents.
+        const subAgentPersistence = container.config.security?.agentToAgent?.subAgentSessionPersistence ?? false;
+        const spawnAgentConfigForSession = container.config.agents[effectiveAgentId];
+        const sessionCwd = spawnAgentConfigForSession
+            ? resolveWorkspaceDir(spawnAgentConfigForSession, effectiveAgentId)
+            : resolveWorkspaceDir(container.config.agents["default"] ?? {}, effectiveAgentId);
+        let ephemeralSessionAdapter;
+        if (isReuseSession || subAgentPersistence) {
+            // Reuse sessions MUST be disk-backed so conversation survives between rounds.
+            ephemeralSessionAdapter = createComisSessionManager({
+                sessionBaseDir: safePath(sessionCwd, "sessions"),
+                lockDir: safePath(sessionCwd, ".locks"),
+                cwd: sessionCwd,
+                fileLock: deps.fileLock,
+            });
+        }
+        else {
+            ephemeralSessionAdapter = createEphemeralComisSessionManager(sessionCwd);
+        }
+        // Wrap in runWithContext so sub-agent inherits parent's ALS context.
+        const executionOverrides = {
+            stepCounter: freshStepCounter,
+            spawnPacket,
+            model: subagentResolution?.model ?? modelOverride,
+            operationType: "subagent",
+            promptTimeout: (() => {
+                const effectiveTimeoutMs = isGraphSpawn
+                    ? GRAPH_PROMPT_TIMEOUT_MS
+                    : subagentResolution?.timeoutMs;
+                return effectiveTimeoutMs ? { promptTimeoutMs: effectiveTimeoutMs } : undefined;
+            })(),
+            cacheRetention: isReuseSession
+                ? "long"
+                : (graphSharedDir
+                    ? resolveGraphCacheRetention(graphOverrides?.graphNodeDepth, isLeafNode)
+                    : (subagentResolution?.cacheRetention ?? subAgentCacheRetention)),
+            ephemeralSessionAdapter,
+            skipRag: !!graphSharedDir,
+            graphId: graphOverrides?.graphId,
+            nodeId: graphOverrides?.nodeId,
+        };
+        const result = ctx
+            ? await runWithContext(ctx, () => getExecutor(effectiveAgentId).execute(msg, sessionKey, tools, undefined, agentId, undefined, undefined, executionOverrides))
+            : await getExecutor(effectiveAgentId).execute(msg, sessionKey, tools, undefined, agentId, undefined, undefined, executionOverrides);
+        deps.logger?.debug({
+            agentId,
+            callerAgentId,
+            finishReason: result.finishReason,
+            stepsExecuted: result.stepsExecuted,
+            tokensTotal: result.tokensUsed?.total,
+            costTotal: result.cost?.total,
+            toolCallCount: result.toolCallHistory?.length ?? 0,
+            responseLength: result.response?.length ?? 0,
+        }, "executeSubAgent completed");
+        return {
+            response: result.response,
+            tokensUsed: result.tokensUsed,
+            cost: result.cost,
+            finishReason: result.finishReason,
+            stepsExecuted: result.stepsExecuted,
+            toolCallHistory: result.toolCallHistory,
+        };
+    };
+}