comisai 1.0.34 → 1.0.37

package/node_modules/@comis/agent/dist/executor/gemini-cache-injector.js

@@ -4,7 +4,7 @@
  *
  * Injects CachedContent name into Gemini API payloads and atomically strips
  * the three inherited fields (systemInstruction, tools, toolConfig) to avoid
- * double-billing. Operates inside the onPayload hook (post-buildParams) per D-04.
+ * double-billing. Operates inside the onPayload hook (post-buildParams).
  *
  * Handles cache injection, inherited field stripping, and staleness recovery.
  *
@@ -103,7 +103,7 @@ export function createGeminiCacheInjector(config, logger) {
                         config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
                         return resolvedParams;
                     }
-                    // D-03: Assertion -- all three fields must be present for stripping
+                    // Assertion -- all three fields must be present for stripping
                     if (configObj.systemInstruction === undefined ||
                         configObj.tools === undefined ||
                         configObj.toolConfig === undefined) {
@@ -112,7 +112,7 @@ export function createGeminiCacheInjector(config, logger) {
                             cacheName: entry.name,
                             hint: "Expected fields missing from config -- cache entry stale, evicting",
                             errorKind: "validation",
-                        }, "Gemini cache injector: stale cache detected (D-03)");
+                        }, "Gemini cache injector: stale cache detected");
                         suppressError(config.cacheManager.dispose(config.sessionKey), "stale-cache-eviction-d03");
                         config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
                         return resolvedParams;
@@ -129,7 +129,7 @@ export function createGeminiCacheInjector(config, logger) {
                     }, "Gemini cache injector: injected cached content");
                     // Notify caller of successful cache injection for observability
                     config.onCacheHit?.(entry);
-                    // D-07: Phase 1 cache break detection callback
+                    // Cache break detection callback
                     config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
                     return resolvedParams;
                 },

package/node_modules/@comis/agent/dist/executor/jit-guide-injector.d.ts

@@ -35,10 +35,19 @@ import type { AgentToolResult } from "@mariozechner/pi-agent-core";
  *
  * - If no guide exists for the tool, returns result unchanged.
  * - If guide was already delivered in this session, returns result unchanged.
- * - Always marks the tool as delivered (even on error).
- * - Skips injection when result has isError: true (but still marks delivered).
+ * - Skips injection when result has isError: true and does NOT mark delivered
+ *   (so a retry can fire — see regression coverage in `jit-guide-injector.test.ts`).
  * - Logs at INFO level when guide is injected.
  *
+ * **Re-injection de-dup contract.** The `deliveredGuides` Set is the single
+ * source of truth for which guide ids have been injected within the current
+ * scope (per-session by default; cleared on session reset by pi-executor).
+ * Within a single turn — even when the same tool fires multiple times via
+ * mid-turn discovery / retries — the same guide id is not re-injected
+ * because the early-return on `deliveredGuides.has(...)` fires on the
+ * second-and-later check. The existing Set IS the per-turn (and per-session)
+ * tracker; no second data structure is needed.
+ *
  * Note: AgentToolResult does not formally include isError (it is set by
  * the agent-loop on the message level), but some tools (MCP, discovery)
  * include it at runtime. We check for it defensively.

package/node_modules/@comis/agent/dist/executor/jit-guide-injector.js

@@ -42,10 +42,19 @@ const PRIVILEGED_SECTION_KEY = "section:privileged";
  *
  * - If no guide exists for the tool, returns result unchanged.
  * - If guide was already delivered in this session, returns result unchanged.
- * - Always marks the tool as delivered (even on error).
- * - Skips injection when result has isError: true (but still marks delivered).
+ * - Skips injection when result has isError: true and does NOT mark delivered
+ *   (so a retry can fire — see regression coverage in `jit-guide-injector.test.ts`).
  * - Logs at INFO level when guide is injected.
  *
+ * **Re-injection de-dup contract.** The `deliveredGuides` Set is the single
+ * source of truth for which guide ids have been injected within the current
+ * scope (per-session by default; cleared on session reset by pi-executor).
+ * Within a single turn — even when the same tool fires multiple times via
+ * mid-turn discovery / retries — the same guide id is not re-injected
+ * because the early-return on `deliveredGuides.has(...)` fires on the
+ * second-and-later check. The existing Set IS the per-turn (and per-session)
+ * tracker; no second data structure is needed.
+ *
  * Note: AgentToolResult does not formally include isError (it is set by
  * the agent-loop on the message level), but some tools (MCP, discovery)
  * include it at runtime. We check for it defensively.
@@ -67,6 +76,11 @@ export function wrapToolResultWithGuide(toolName, result, deliveredGuides, logge
     const wantsPrivileged = PRIVILEGED_TOOL_SET.has(toolName) &&
         !deliveredGuides.has(PRIVILEGED_SECTION_KEY) &&
         !!SYSTEM_PROMPT_GUIDES["__privileged_tools__"];
+    // Re-injection de-dup: when every candidate guide id is already in
+    // `deliveredGuides`, none of `wantsTool`/`wantsSection`/`wantsPrivileged`
+    // is true and we early-return without appending. This single check is the
+    // per-turn (and per-session) de-dup gate — the same `deliveredGuides` Set
+    // passed across calls within a turn IS the injectedGuideIds tracker.
     if (!wantsTool && !wantsSection && !wantsPrivileged)
         return result;
     // Skip on error — but DO NOT consume delivery slots so a retry can fire.

package/node_modules/@comis/agent/dist/executor/phase-filter.d.ts

@@ -25,13 +25,13 @@ export declare function isVisibleTextBlock(block: any): boolean;
  *   - cross-turn boundary (role === "user" encountered before a
  *     qualifying assistant) — return "" because the user message marks
  *     the start of the current execution window; assistants before it
- *     belong to prior turns (260501-gyy).
+ *     belong to prior turns.
  *
  * When the resulting last assistant contains commentary-phase text
  * blocks, drops them and returns only visible text. Otherwise returns
  * the visible (non-commentary) text blocks of the last assistant
  * directly — does NOT delegate to session.getLastAssistantText(),
  * which walks past empty messages and would re-introduce the
- * synthetic-leak (260501-egj).
+ * synthetic-leak.
  */
 export declare function getVisibleAssistantText(session: any): string;

package/node_modules/@comis/agent/dist/executor/phase-filter.js

@@ -41,21 +41,20 @@ export function isVisibleTextBlock(block) {
  *   - cross-turn boundary (role === "user" encountered before a
  *     qualifying assistant) — return "" because the user message marks
  *     the start of the current execution window; assistants before it
- *     belong to prior turns (260501-gyy).
+ *     belong to prior turns.
  *
  * When the resulting last assistant contains commentary-phase text
  * blocks, drops them and returns only visible text. Otherwise returns
  * the visible (non-commentary) text blocks of the last assistant
  * directly — does NOT delegate to session.getLastAssistantText(),
  * which walks past empty messages and would re-introduce the
- * synthetic-leak (260501-egj).
+ * synthetic-leak.
  */
 export function getVisibleAssistantText(session) {
     const messages = session?.messages;
     // Find last "real" assistant message in the CURRENT execution window —
     // skip aborted-empty, error-empty, and synthetic-injected; stop at the
-    // first user message (turn boundary) to avoid leaking prior-turn text
-    // (260501-gyy).
+    // first user message (turn boundary) to avoid leaking prior-turn text.
     const lastAssistant = (() => {
         if (!Array.isArray(messages))
             return undefined;
@@ -93,9 +92,8 @@ export function getVisibleAssistantText(session) {
     // No commentary — return lastAssistant's visible text directly.
     // Do NOT delegate to session.getLastAssistantText() because it walks
     // past empty messages (aborted/error/etc.) and re-introduces the
-    // synthetic-leak (production bug 260501-egj: post-restart-resumption
-    // rate-limit returned synthetic placeholder instead of the
-    // 260501-cur "Rate limit exceeded" terminal error).
+    // synthetic-leak (post-restart-resumption rate-limit returned synthetic
+    // placeholder instead of the "Rate limit exceeded" terminal error).
     if (!lastAssistant?.content || !Array.isArray(lastAssistant.content))
         return "";
     return lastAssistant.content

package/node_modules/@comis/agent/dist/executor/pi-executor.d.ts

@@ -21,7 +21,7 @@
  */
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 import type { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
-import { type PerAgentConfig, type TypedEventBus, type MemoryPort, type HookRunner, type SecretManager, type EnvelopeConfig, type OutputGuardPort, type InputValidationResult, type InputSecurityGuard, type InjectionRateLimiter, type SenderTrustDisplayConfig } from "@comis/core";
+import { type PerAgentConfig, type TypedEventBus, type MemoryPort, type HookRunner, type SecretManager, type EnvelopeConfig, type OutputGuardPort, type InputValidationResult, type InputSecurityGuard, type InjectionRateLimiter, type SenderTrustDisplayConfig, type ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import type { BudgetGuard } from "../budget/budget-guard.js";
@@ -33,6 +33,7 @@ import type { MessageSendLimiter } from "../safety/message-send-limiter.js";
 import type { ProviderHealthMonitor } from "../safety/provider-health-monitor.js";
 import type { ComisSessionManager } from "../session/comis-session-manager.js";
 import type { AuthRotationAdapter } from "../model/auth-rotation-adapter.js";
+import type { OAuthTokenManager } from "../model/oauth-token-manager.js";
 import type { ActiveRunRegistry } from "./active-run-registry.js";
 import type { GeminiCacheManager } from "./gemini-cache-manager.js";
 import type { BackgroundTaskManager, NotifyFn } from "../background/index.js";
@@ -52,7 +53,7 @@ import type { AgentExecutor } from "./types.js";
  */
 export declare function createBeforeToolCallGuard(stepCounter: StepCounter, budgetGuard: BudgetGuard, circuitBreaker: CircuitBreaker, toolRetryBreaker?: ToolRetryBreaker, messageSendLimiter?: MessageSendLimiter): (context: unknown, _signal?: AbortSignal) => Promise<import("../safety/message-send-limiter.js").MessageSendVerdict | undefined>;
 /**
- * Merge SDK session stats into execution result for token totals (R-13).
+ * Merge SDK session stats into execution result for token totals.
  *
  * Token counts (input, output, cacheRead, cacheWrite, total) are sourced
  * from the SDK's cumulative session stats -- single source of truth.
@@ -120,6 +121,18 @@ export interface PiExecutorDeps {
     fallbackModels?: string[];
     /** Optional auth rotation adapter for multi-key providers. */
     authRotation?: AuthRotationAdapter;
+    /**
+     * Optional OAuth token manager. When provided, the per-LLM-call
+     * dispatch hook in execute() resolves the OAuth token via the resolver
+     * chain (agent-config -> lastGood -> first available) and sets it into
+     * authStorage's runtime override Map for pi-coding-agent's outbound LLM
+     * call.
+     *
+     * Single hook per execute() — long-running execute()s
+     * (>= 1 hour) may see token expire mid-loop; revisit if observed
+     * in production.
+     */
+    oauthManager?: OAuthTokenManager;
     /** Active run registry for mid-execution steering. */
     activeRunRegistry?: ActiveRunRegistry;
     /** Daemon-level tracing defaults for rotation. */
@@ -156,6 +169,12 @@ export interface PiExecutorDeps {
     embeddingEnqueue?: (entryId: string, content: string) => void;
     /** Optional embedding port for semantic search in discover_tools. */
     embeddingPort?: import("@comis/core").EmbeddingPort;
+    /**
+     * Tool-capability port for the per-turn capability-index renderer.
+     * Daemon wiring injects createNoOpCapabilityPort() from @comis/core
+     * until the live adapter ships.
+     */
+    toolCapabilityPort: ToolCapabilityPort;
     /** Sender trust display config from AppConfig. */
     senderTrustDisplayConfig?: SenderTrustDisplayConfig;
     /** Documentation config from AppConfig. */

package/node_modules/@comis/agent/dist/executor/pi-executor.js

@@ -27,6 +27,7 @@ tryGetContext, ContextEngineConfigSchema, } from "@comis/core";
 import { suppressError } from "@comis/shared";
 import { createToolRetryBreaker } from "../safety/tool-retry-breaker.js";
 import { createMessageSendLimiter } from "../safety/message-send-limiter.js";
+import { resolveProviderApiKey } from "../model/resolve-provider-api-key.js";
 import { repairOrphanedMessages, scrubPoisonedThinkingBlocks } from "../session/orphaned-message-repair.js";
 import { scrubRedactedToolCalls } from "../session/scrub-redacted-tool-calls.js";
 import { createPiEventBridge } from "../bridge/pi-event-bridge.js";
@@ -51,7 +52,7 @@ import { validateInput } from "./executor-input-guard.js";
 import { scanWithOutputGuard } from "./executor-response-filter.js";
 import { normalizeModelCompat } from "../provider/model-compat.js";
 import { normalizeModelId } from "../provider/model-id-normalize.js";
-import { isAnthropicFamily, isGoogleFamily } from "../provider/capabilities.js";
+import { isAnthropicFamily, isGoogleFamily, resolveProviderCapabilities } from "../provider/capabilities.js";
 import { detectOnboardingState } from "../workspace/onboarding-detector.js";
 import { PromptTimeoutError } from "./prompt-timeout.js";
 import { classifyError, classifyPromptTimeout } from "./error-classifier.js";
@@ -66,7 +67,7 @@ import { randomUUID } from "node:crypto";
 /** Number of turns to restrict breakpoints after server eviction. */
 const EVICTION_COOLDOWN_TURNS = 2;
 // ---------------------------------------------------------------------------
-// R-12: Proactive tool-call safety guard
+// Proactive tool-call safety guard
 // ---------------------------------------------------------------------------
 /**
  * Create a beforeToolCall guard that proactively blocks tool execution when
@@ -123,10 +124,10 @@ export function createBeforeToolCallGuard(stepCounter, budgetGuard, circuitBreak
     };
 }
 // ---------------------------------------------------------------------------
-// R-13: Session stats delegation helper
+// Session stats delegation helper
 // ---------------------------------------------------------------------------
 /**
- * Merge SDK session stats into execution result for token totals (R-13).
+ * Merge SDK session stats into execution result for token totals.
  *
  * Token counts (input, output, cacheRead, cacheWrite, total) are sourced
  * from the SDK's cumulative session stats -- single source of truth.
@@ -197,6 +198,27 @@ export function createPiExecutor(config, deps) {
         async execute(msg, sessionKey, tools, onDelta, agentId, _directives, _prevTimestamp, overrides) {
             // a. Record execution start time
             const executionStartMs = Date.now();
+            // a-bis. Pre-resolve OAuth token before any pi-coding-agent
+            // dispatch. The setRuntimeApiKey side-effect inside resolveProviderApiKey
+            // carries the token into pi-coding-agent's outbound LLM request via the
+            // runtime-override priority path. For OAuth-eligible
+            // providers (openai-codex, anthropic, github-copilot via pi-ai's
+            // built-in registry) the resolver chain (agent-config -> lastGood ->
+            // first available) runs and refreshes the token if expired. For
+            // non-OAuth providers the helper falls through to authStorage.getApiKey.
+            //
+            // Throw-propagation: on OAuthError the helper throws
+            // an Error containing the OAuthError.message. Outer async callers
+            // (gateway routes via Hono, channel handlers via try/catch) lift the
+            // throw into a user-facing error response. OAuthError
+            // is fatal — no env-var fallback, no retry, no silent rotation.
+            // CLAUDE.md "no empty catch" honored because we don't add a catch
+            // here at all; the resolver itself logs via the oauth-resolver module.
+            await resolveProviderApiKey(config.provider, {
+                authStorage: deps.authStorage,
+                oauthManager: deps.oauthManager,
+                agentConfig: config,
+            });
             // b. Initialize result
             const result = {
                 response: "",
@@ -378,7 +400,7 @@ export function createPiExecutor(config, deps) {
                 provider: resolvedModel.provider,
                 id: resolvedModel.id,
             }) : undefined;
-            // f. Execute within session adapter (R-11: use ephemeral adapter if provided)
+            // f. Execute within session adapter (use ephemeral adapter if provided)
             const sessionAdapter = overrides?.ephemeralSessionAdapter ?? deps.sessionAdapter;
             const lockResult = await sessionAdapter.withSession(sessionKey, async (sm) => {
                 // Repair orphaned messages
@@ -428,6 +450,7 @@ export function createPiExecutor(config, deps) {
                 const stableGetPromptSkillsXml = frozenPromptSkillsXml !== undefined
                     ? () => frozenPromptSkillsXml
                     : deps.getPromptSkillsXml;
+                // toolCapabilityPort flows through frozenDeps spread — no explicit re-assignment.
                 const frozenDeps = { ...deps, getPromptSkillsXml: stableGetPromptSkillsXml };
                 // Tool assembly pipeline: merge, settings, prompt, deferral, JIT, pruning, snapshot, normalization, serializer
                 // Extracted to executor-tool-assembly.ts
@@ -437,7 +460,7 @@ export function createPiExecutor(config, deps) {
                     resolvedModel, modelCompat, agentId, safetyReinforcement, _directives,
                 });
                 const { mergedCustomTools, } = toolAssembly;
-                const { deferralResult, deferredContext, modelTier, discoveryTracker, settingsManager, resourceLoaderOptions, promptResult, cachedSystemTokensEstimate, } = toolAssembly;
+                const { deferralResult, deferredContext, capabilityIndexResult, modelTier, discoveryTracker, settingsManager, resourceLoaderOptions, promptResult, cachedSystemTokensEstimate, } = toolAssembly;
                 const currentDiscoveryTracker = toolAssembly.currentDiscoveryTracker;
                 const { systemPrompt, systemPromptBlocks, dynamicPreamble, inlineMemory } = promptResult;
                 // DAG ingestion hook -- install BEFORE microcompaction
@@ -515,8 +538,8 @@ export function createPiExecutor(config, deps) {
                 const messageSendLimiter = createMessageSendLimiter({
                     maxSendsPerExecution: deps.maxSendsPerExecution ?? 3,
                 });
-                // R-12: Proactive safety -- block tool execution before it starts
-                // when safety limits are already reached. Existing reactive checks in
+                // Proactive safety -- block tool execution before it starts when
+                // safety limits are already reached. Existing reactive checks in
                 // pi-event-bridge remain as fallback for limits crossed during execution.
                 // NOTE: beforeToolCall replaces the extension runner's hook. Comis does
                 // not load pi-mono extensions, so this override is safe.
@@ -641,6 +664,18 @@ export function createPiExecutor(config, deps) {
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     session.agent.transformContext = ceSetup.contextEngine.transformContext;
                 }
+                // Align register/deregister key shape with
+                // BackgroundSessionResolver.formatComposite so production lookups via
+                // resolveActiveSession({agentId, channelType, channelId}) find the
+                // handle this execute() call registers. session-resolver.test.ts
+                // locks the formula — drift on either side breaks that test.
+                // NormalizedMessageSchema enforces channelType / channelId are
+                // non-empty (z.string().min(1)), so this composition is unconditional.
+                const resolverRegisterKey = formatSessionKey({
+                    tenantId: agentId ?? "default",
+                    channelId: `${msg.channelType}:${msg.channelId}`,
+                    userId: msg.channelId,
+                });
                 // Register active run for mid-execution steering
                 if (deps.activeRunRegistry) {
                     const handle = {
@@ -650,9 +685,9 @@ export function createPiExecutor(config, deps) {
                         isStreaming: () => session.isStreaming,
                         isCompacting: () => session.isCompacting,
                     };
-                    const registered = deps.activeRunRegistry.register(formattedKey, handle);
+                    const registered = deps.activeRunRegistry.register(resolverRegisterKey, handle);
                     if (!registered) {
-                        deps.logger.warn({ sessionKey: formattedKey, hint: "Session already has an active run; concurrent execution may cause issues", errorKind: "resource" }, "Active run already registered");
+                        deps.logger.warn({ sessionKey: resolverRegisterKey, hint: "Session already has an active run; concurrent execution may cause issues", errorKind: "resource" }, "Active run already registered");
                     }
                 }
                 // SDK tool management validation and introspection.
@@ -726,7 +761,7 @@ export function createPiExecutor(config, deps) {
                     deps.logger.debug({ err: sdkSkillError, hint: "SDK skill population failed, Comis discovery still active", errorKind: "dependency" }, "SDK skill population non-fatal error");
                 }
                 // session.sendCustomMessage() is available for operator annotations.
-                // REQUIREMENTS.md refers to appendCustomEntry() which is the SessionManager-level API;
+                // Note: appendCustomEntry() is the SessionManager-level API;
                 // the AgentSession wrapper exposes this as sendCustomMessage({ customType, content, display, details }).
                 // Future commands or hooks can call this to inject custom entries into the JSONL session.
                 // Apply command directives (thinking, compact, model, export, fork, branch)
@@ -775,7 +810,7 @@ export function createPiExecutor(config, deps) {
                         session.abortCompaction();
                         suppressError(session.abort(), "session abort on compaction cancel");
                     },
-                    // 260501-dkl: cancel the SDK's internal auto-retry loop when the
+                    // Cancel the SDK's internal auto-retry loop when the
                     // bridge classifies the auto_retry_start error as `rate_limited`.
                     // Rate-limit windows (per-minute) outlast the SDK's retry budget
                     // (~30s), so retrying within the window cannot succeed.
@@ -820,7 +855,7 @@ export function createPiExecutor(config, deps) {
                     sepConfig: sepEnabled ? { maxSteps: config.sep?.maxSteps ?? 15, minSteps: config.sep?.minSteps ?? 3 } : undefined,
                     sepMessageText: sepEnabled ? (msg.text ?? "") : undefined,
                     sepExecutionStartMs: sepEnabled ? executionStartMs : undefined,
-                    // Cache break detection Phase 2 callback.
+                    // Cache break detection post-call callback.
                     // Enrich with elapsed time for tiered server-side attribution.
                     checkCacheBreak: (input) => cacheBreakDetector.checkResponseForCacheBreak({
                         ...input,
@@ -841,7 +876,7 @@ export function createPiExecutor(config, deps) {
                             timestamp: Date.now(),
                         };
                     },
-                    // 260428-hoy: pre-LLM-call hook -- runs once per `turn_start`,
+                    // Pre-LLM-call hook -- runs once per `turn_start`,
                     // BEFORE pi-ai serializes the next request. Asserts the
                     // cross-turn hash invariant (logs ERROR per mutated block, with
                     // module:"agent.bridge.hash-invariant"), then heals any mutated
@@ -893,7 +928,7 @@ export function createPiExecutor(config, deps) {
                         }
                         return live;
                     },
-                    // 260428-iag wire-edge diagnostic: resolves the per-session JSONL
+                    // Wire-edge diagnostic: resolves the per-session JSONL
                     // path on demand. The bridge invokes this only after detecting the
                     // signed-replay rejection signature on a 400 — never on the happy
                     // path. Path comes from the same sessionAdapter that already
@@ -996,12 +1031,46 @@ export function createPiExecutor(config, deps) {
                 // Applied AFTER sideEffects so the background placeholder is returned instead of
                 // waiting for sideEffects processing. When the tool completes in background,
                 // the sideEffects are still processed by the original wrapped execute.
+                // Capture origin at wrap-time via explicit threading.
+                // The closure reads runPrompt-scope variables synchronously each invocation
+                // so the captured origin reflects the originating session, not the
+                // background-continuation context (which lacks these locals).
                 if (deps.backgroundTaskManager && config.backgroundTasks?.enabled !== false) {
                     const bgConfig = BackgroundTasksConfigSchema.parse(config.backgroundTasks ?? {});
+                    const resolvedAgentId = agentId ?? "default";
+                    const originResolver = () => {
+                        // Defensive: if any required field is unexpectedly missing, fall through
+                        // to foreground execution (no background promotion). Promotion requires
+                        // a complete origin.
+                        if (!formattedKey || formattedKey.length === 0)
+                            return undefined;
+                        if (!msg.channelType || msg.channelType.length === 0)
+                            return undefined;
+                        if (!msg.channelId || msg.channelId.length === 0)
+                            return undefined;
+                        // Read incoming hop count off msg.metadata so the runner can enforce
+                        // the recursion bound. Top-level user messages have no
+                        // metadata.backgroundHopCount -> default to 0.
+                        // Cast metadata defensively because NormalizedMessageSchema.metadata
+                        // is z.record(z.string(), z.unknown()).
+                        const meta = msg.metadata;
+                        const rawHopCount = meta?.backgroundHopCount;
+                        const incomingHopCount = typeof rawHopCount === "number" && Number.isFinite(rawHopCount) && rawHopCount >= 0
+                            ? Math.floor(rawHopCount)
+                            : 0;
+                        return {
+                            agentId: resolvedAgentId,
+                            sessionKey: formattedKey,
+                            channelType: msg.channelType,
+                            channelId: msg.channelId,
+                            traceId: executionId ?? null,
+                            backgroundHopCount: incomingHopCount,
+                        };
+                    };
                     for (const tool of mergedCustomTools) {
                         const wrapped = wrapToolForAutoBackground(
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK interop boundary
-                        tool, deps.backgroundTaskManager, bgConfig, deps.backgroundNotifyFn ?? (async () => { }), agentId ?? "default");
+                        tool, deps.backgroundTaskManager, bgConfig, deps.backgroundNotifyFn ?? (async () => { }), originResolver);
                         tool.execute = wrapped.execute;
                     }
                 }
@@ -1011,7 +1080,7 @@ export function createPiExecutor(config, deps) {
                     const promptRunResult = await runPrompt({
                         msg, session, config, sessionKey, formattedKey, agentId, result,
                         executionOverrides, executionStartMs, effectiveTimeout, executionId,
-                        bridge, dynamicPreamble, deferredContext, inlineMemory,
+                        bridge, dynamicPreamble, deferredContext, capabilityIndexResult, inlineMemory,
                         systemPrompt,
                         mergedCustomTools,
                         cmdResult, sepEnabled, executionPlanRef,
@@ -1088,13 +1157,22 @@ export function createPiExecutor(config, deps) {
                     // Post-execution cleanup: stats merge, cache metrics, memory persist, session cleanup
                     // Extracted to executor-post-execution.ts
                     await postExecution({
-                        result, session, sm, config, msg, sessionKey, formattedKey, agentId,
+                        result, session, sm, config, msg, sessionKey, formattedKey, resolverRegisterKey, agentId,
                         executionStartMs, executionId, executionOverrides,
                         bridge, unsubscribe,
                         contextEngineRef, ceSetup, streamSetup,
                         getTruncationSummary, getTurnBudgetSummary,
                         executionPlanRef, sepEnabled, isOnboarding,
                         geminiCacheHit, geminiCachedTokens, modelTier,
+                        // Provider attribution tag for the bookend log.
+                        // resolvedModel?.provider is the post-resolution / post-override
+                        // provider; falling back to config.provider records operator
+                        // INTENT on the silent-fallback misconfig path (resolvedModel
+                        // undefined). resolveProviderCapabilities is computed once here
+                        // to keep executor-post-execution.ts free of capability-cascade
+                        // imports.
+                        provider: resolvedModel?.provider ?? config.provider,
+                        providerFamily: resolveProviderCapabilities(resolvedModel?.provider ?? config.provider).providerFamily,
                         deferralResult, mergedCustomTools, deliveredGuides,
                         deps: {
                             eventBus: deps.eventBus,

package/node_modules/@comis/agent/dist/executor/post-batch-continuation.js

@@ -15,7 +15,7 @@ import { fromPromise, ok, err } from "@comis/shared";
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
-const MODULE = "agent.executor.post-batch-continuation";
+const SUBMODULE = "executor.post-batch-continuation";
 /* eslint-disable @typescript-eslint/no-explicit-any */
 function isToolCallBlock(block) {
     return block?.type === "toolCall" || block?.type === "tool_use";
@@ -84,7 +84,7 @@ export async function runPostBatchContinuation(deps) {
     const { session, messages, config, logger, agentId, getVisibleAssistantText } = deps;
     // Step 1: disable check.
     if (!config.enabled || config.maxRetries === 0) {
-        logger.info({ module: MODULE, agentId, decision: "skip", reason: "disabled" }, "Post-batch continuation skipped");
+        logger.info({ submodule: SUBMODULE, agentId, decision: "skip", reason: "disabled" }, "Post-batch continuation skipped");
         return ok({
             recovered: false,
             attempts: 0,
@@ -97,7 +97,7 @@ export async function runPostBatchContinuation(deps) {
     /* eslint-disable @typescript-eslint/no-explicit-any */
     const msgs = messages;
     if (!Array.isArray(msgs) || msgs.length === 0) {
-        logger.info({ module: MODULE, agentId, decision: "skip", reason: "non_empty_final" }, "Post-batch continuation skipped");
+        logger.info({ submodule: SUBMODULE, agentId, decision: "skip", reason: "non_empty_final" }, "Post-batch continuation skipped");
         return ok({
             recovered: false,
             attempts: 0,
@@ -113,7 +113,7 @@ export async function runPostBatchContinuation(deps) {
         !hasThinkingBlock(last.content) &&
         !hasToolCallBlock(last.content);
     if (!lastIsEmpty) {
-        logger.info({ module: MODULE, agentId, decision: "skip", reason: "non_empty_final" }, "Post-batch continuation skipped");
+        logger.info({ submodule: SUBMODULE, agentId, decision: "skip", reason: "non_empty_final" }, "Post-batch continuation skipped");
         return ok({
             recovered: false,
             attempts: 0,
@@ -141,7 +141,7 @@ export async function runPostBatchContinuation(deps) {
     /* eslint-enable @typescript-eslint/no-explicit-any */
     const priorToolNames = [...priorToolNamesSet];
     if (priorToolCallCount === 0) {
-        logger.info({ module: MODULE, agentId, decision: "skip", reason: "no_tool_calls" }, "Post-batch continuation skipped");
+        logger.info({ submodule: SUBMODULE, agentId, decision: "skip", reason: "no_tool_calls" }, "Post-batch continuation skipped");
         return ok({
             recovered: false,
             attempts: 0,
@@ -152,7 +152,7 @@ export async function runPostBatchContinuation(deps) {
     }
     // Step 4: decision-log fire.
     logger.info({
-        module: MODULE,
+        submodule: SUBMODULE,
         agentId,
         decision: "fire",
         reason: "empty_after_tool_batch",
@@ -170,7 +170,7 @@ export async function runPostBatchContinuation(deps) {
         const text = getVisibleAssistantText(session);
         const outcomeForLog = text && text.length > 0 ? "recovered" : "still_empty";
         logger.info({
-            module: MODULE,
+            submodule: SUBMODULE,
             agentId,
             attempt,
             maxAttempts: config.maxRetries,

package/node_modules/@comis/agent/dist/executor/prompt-assembly.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { SessionKey, NormalizedMessage, PerAgentConfig, MemoryPort, HookRunner, SecretManager, EnvelopeConfig, WrapExternalContentOptions, TypedEventBus, SenderTrustDisplayConfig, SpawnPacket, DeliveryMirrorPort, ModelOperationType } from "@comis/core";
+import type { SessionKey, NormalizedMessage, PerAgentConfig, MemoryPort, HookRunner, SecretManager, EnvelopeConfig, WrapExternalContentOptions, TypedEventBus, SenderTrustDisplayConfig, SpawnPacket, DeliveryMirrorPort, ModelOperationType, ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 import type { BootstrapContextFile } from "../bootstrap/types.js";
@@ -130,6 +130,14 @@ export interface PromptAssemblyParams {
         }>;
         /** Platform message character limit for auto verbosity mode. Resolved by caller from channelRegistry. */
         channelMaxChars?: number;
+        /**
+         * Tool-capability port for the gate flag.
+         * Only `port.isCapabilityIndexEnabled()` is read from this file — live-runtime
+         * port accessors (skill catalog, connected MCP servers, deferred-tool state)
+         * are FORBIDDEN here per the cache-fence invariant. Architecture-grep tests
+         * statically enforce this restriction.
+         */
+        toolCapabilityPort: ToolCapabilityPort;
     };
     msg: NormalizedMessage;
     sessionKey: SessionKey;

package/node_modules/@comis/agent/dist/executor/prompt-assembly.js

@@ -331,7 +331,7 @@ export async function assembleExecutionPrompt(params) {
     // Consolidated lightContext flag: heartbeat implies light-context regardless
     // of the explicit msg.metadata.lightContext flag. Callers that only set the
     // metadata flag OR only set operationType="heartbeat" produce identical
-    // prompt output (design-doc §Risks: "Heartbeat lightContext and operationType drift").
+    // prompt output.
     const effectiveLightContext = msg.metadata?.lightContext === true || params.operationType === "heartbeat";
     // 2. Load workspace bootstrap files (skip for "none" mode)
     let bootstrapContextFiles = [];
@@ -522,6 +522,13 @@ export async function assembleExecutionPrompt(params) {
     const isOnboarding = await detectOnboardingState(deps.workspaceDir);
     // Shared params for both assembleRichSystemPrompt and assembleRichSystemPromptBlocks.
     // Using a single variable guarantees identity by construction.
+    //
+    // Hot-flip safety: the capability-index gate value is read once per
+    // assembleExecutionPrompt call via
+    // `deps.toolCapabilityPort.isCapabilityIndexEnabled()`. The flag is
+    // restart-required and stable across the session by config contract, so the
+    // cached system-prompt prefix is NOT retroactively rewritten when the
+    // underlying YAML changes mid-session.
     const assemblerParams = {
         agentName: config.name,
         promptMode,
@@ -554,6 +561,13 @@ export async function assembleExecutionPrompt(params) {
         subagentRole: undefined, // relocated to dynamic preamble for sub-agent cache sharing
         excludeBootstrapFromContext: true, // BOOTSTRAP.md is either elevated (onboarding) or dead weight (post-onboarding); never useful in Project Context
         workspaceProfile: config.workspace?.profile,
+        /**
+         * Read once per call. The value is config-derived / restart-required,
+         * so it's stable across all turns in this session. Reading it via the
+         * port (rather than from config directly) isolates this code from the
+         * config-schema shape and matches the live adapter contract.
+         */
+        capabilityIndexEnabled: deps.toolCapabilityPort.isCapabilityIndexEnabled(),
         sepEnabled: params.sepEnabled,
     };
     let systemPrompt = assembleRichSystemPrompt(assemblerParams);

package/node_modules/@comis/agent/dist/executor/stream-wrappers/request-body-injector.d.ts

@@ -40,7 +40,7 @@ export interface RequestBodyInjectorConfig {
      *  but system prompt + tools are still worth caching. */
     getMinTokensOverride?: () => number | undefined;
     /** Callback invoked with the API-ready payload after cache breakpoint
-     *  placement. Used by cache break detector Phase 1 to extract prompt state for
+     *  placement. Used by the cache break detector to extract prompt state for
      *  change detection. Receives the mutated params, the model, and (for Anthropic) the HTTP headers. */
     onPayloadForCacheDetection?: (params: Record<string, unknown>, model: {
         id: string;

package/node_modules/@comis/agent/dist/executor/stream-wrappers/request-body-injector.js

@@ -1484,7 +1484,7 @@ export function createRequestBodyInjector(config, logger) {
                             mergedHeaders["anthropic-beta"] = allBetas.join(", ");
                         }
                     }
-                    // Feed payload to cache break detector Phase 1 (after breakpoint placement)
+                    // Feed payload to cache break detector (after breakpoint placement)
                     if (config.onPayloadForCacheDetection) {
                         config.onPayloadForCacheDetection(result, model, mergedHeaders);
                     }