@canonmsg/codex-plugin 0.26.2 → 0.28.0

package/dist/codex-app-tools.d.ts

@@ -1,4 +1,4 @@
-import { type NoReplyReportClient } from '@canonmsg/core';
+import { type CanonClient, type NoReplyReportClient } from '@canonmsg/core';
 type JsonRecord = Record<string, unknown>;
 interface DynamicToolSpec {
     [key: string]: unknown;
@@ -44,6 +44,7 @@ type DynamicToolCallResponse = {
  */
 export declare const CODEX_NO_REPLY_TOOL_NAME = "no_reply";
 export declare const CANON_RUNTIME_CONTROL_TOOL_NAME = "canon_runtime_control";
+export declare const CODEX_COMMUNICATE_TOOL_NAME = "communicate";
 /**
  * What the model actually sees for the tool above, for prompt text that names
  * it (the group posture cue). Only meaningful on the app-server transport —
@@ -53,6 +54,8 @@ export declare const CODEX_NO_REPLY_MODEL_TOOL_NAME = "codex_app.no_reply";
 export declare const CODEX_APP_DYNAMIC_TOOLS: ReadonlyArray<DynamicToolSpec>;
 /** The complete model-visible surface for non-coding service agents. */
 export declare const CODEX_SERVICE_AGENT_DYNAMIC_TOOLS: ReadonlyArray<DynamicToolSpec>;
+/** Closed agents are not shown the optional outbound communication surface. */
+export declare function filterCodexCommunicationTools(tools: ReadonlyArray<DynamicToolSpec>, outboundPolicy: 'open' | 'approval-required' | 'closed' | null): ReadonlyArray<DynamicToolSpec>;
 /**
  * Tools exposed to detached Codex threads created through the bridge. Canon
  * conversation controls belong only to the foreground turn that received the
@@ -65,7 +68,9 @@ export declare function successfulCodexAppToolResult(payload: unknown): DynamicT
 /** True when this dynamic-tool call is the deliberate-silence verb. */
 export declare function isCodexNoReplyToolCall(params: CodexAppToolCallParams): boolean;
 export declare function isCanonRuntimeControlToolCall(params: CodexAppToolCallParams): boolean;
+export declare function isCodexCommunicateToolCall(params: CodexAppToolCallParams): boolean;
 export declare function isCodexServiceAgentToolCall(params: CodexAppToolCallParams): boolean;
+export declare function handleCodexCommunicateToolCall(client: CanonClient, params: CodexAppToolCallParams): Promise<DynamicToolCallResponse>;
 export interface CanonRuntimeControlRequest {
     action: 'send_card' | 'request_card' | 'request_input';
     card?: unknown;

package/dist/codex-app-tools.js

@@ -1,4 +1,5 @@
-import { NO_REPLY_ACK_NOTE, reportNoReplyOutcome } from '@canonmsg/core';
+import { NO_REPLY_ACK_NOTE, reportNoReplyOutcome, } from '@canonmsg/core';
+import { canonCommunicateToolDefinition, createCanonCommunicationBinding, } from '@canonmsg/agent-tools';
 const emptyObjectSchema = {
     type: 'object',
     properties: {},
@@ -90,6 +91,7 @@ function tool(name, description, inputSchema, deferLoading = true) {
  */
 export const CODEX_NO_REPLY_TOOL_NAME = 'no_reply';
 export const CANON_RUNTIME_CONTROL_TOOL_NAME = 'canon_runtime_control';
+export const CODEX_COMMUNICATE_TOOL_NAME = 'communicate';
 /**
  * What the model actually sees for the tool above, for prompt text that names
  * it (the group posture cue). Only meaningful on the app-server transport —
@@ -121,6 +123,11 @@ const CANON_RUNTIME_CONTROL_TOOL = tool(CANON_RUNTIME_CONTROL_TOOL_NAME, 'Intera
     },
     required: ['action'],
 }, false);
+const communicationBinding = createCanonCommunicationBinding({
+    toolName: CODEX_COMMUNICATE_TOOL_NAME,
+});
+const communicateDefinition = canonCommunicateToolDefinition(CODEX_COMMUNICATE_TOOL_NAME);
+const CODEX_COMMUNICATE_TOOL = tool(communicateDefinition.name, communicateDefinition.description, communicateDefinition.inputSchema, false);
 const CODEX_NO_REPLY_TOOL = tool(CODEX_NO_REPLY_TOOL_NAME, 'End your turn without posting anything to the conversation. Use it in group '
     + 'chats when you have nothing to add — no message is created, so no other '
     + 'member or agent is triggered. Optional private reason (logged, never '
@@ -245,6 +252,7 @@ export const CODEX_APP_DYNAMIC_TOOLS = [
         required: ['threadId', 'title'],
     }),
     CANON_RUNTIME_CONTROL_TOOL,
+    CODEX_COMMUNICATE_TOOL,
     // Canon's `no_reply` verb, projected into the only model-visible tool surface
     // the Codex transport gives us. It is answered by the Canon host itself.
     CODEX_NO_REPLY_TOOL,
@@ -252,8 +260,15 @@ export const CODEX_APP_DYNAMIC_TOOLS = [
 /** The complete model-visible surface for non-coding service agents. */
 export const CODEX_SERVICE_AGENT_DYNAMIC_TOOLS = [
     CANON_RUNTIME_CONTROL_TOOL,
+    CODEX_COMMUNICATE_TOOL,
     CODEX_NO_REPLY_TOOL,
 ];
+/** Closed agents are not shown the optional outbound communication surface. */
+export function filterCodexCommunicationTools(tools, outboundPolicy) {
+    return outboundPolicy === 'closed'
+        ? tools.filter((entry) => entry.name !== CODEX_COMMUNICATE_TOOL_NAME)
+        : tools;
+}
 /**
  * Tools exposed to detached Codex threads created through the bridge. Canon
  * conversation controls belong only to the foreground turn that received the
@@ -294,9 +309,21 @@ export function isCodexNoReplyToolCall(params) {
 export function isCanonRuntimeControlToolCall(params) {
     return normalizeToolName(params.tool) === CANON_RUNTIME_CONTROL_TOOL_NAME;
 }
+export function isCodexCommunicateToolCall(params) {
+    return normalizeToolName(params.tool) === CODEX_COMMUNICATE_TOOL_NAME;
+}
 export function isCodexServiceAgentToolCall(params) {
     const toolName = normalizeToolName(params.tool);
-    return toolName === CANON_RUNTIME_CONTROL_TOOL_NAME || toolName === CODEX_NO_REPLY_TOOL_NAME;
+    return toolName === CANON_RUNTIME_CONTROL_TOOL_NAME
+        || toolName === CODEX_COMMUNICATE_TOOL_NAME
+        || toolName === CODEX_NO_REPLY_TOOL_NAME;
+}
+export async function handleCodexCommunicateToolCall(client, params) {
+    const result = await communicationBinding.execute(client, CODEX_COMMUNICATE_TOOL_NAME, parseToolArguments(params.arguments));
+    return {
+        success: result.isError !== true,
+        contentItems: result.content.map((item) => ({ type: 'inputText', text: item.text })),
+    };
 }
 export function parseCanonRuntimeControlRequest(params) {
     if (!isCanonRuntimeControlToolCall(params))

package/dist/host.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { type TurnArtifactRoutingDecision, type TurnArtifactRoutingMode } from '@canonmsg/coding-agent-host';
+import { type TurnArtifactRoutingDecision, type TurnArtifactRoutingMode, type RecoveryCheckpointTracker } from '@canonmsg/coding-agent-host';
 import { type CanonRuntimeCommandDescriptor, type CanonRuntimeDescriptor, type CanonRuntimePresentationPolicy, type ExecutionEnvironmentMode, type PreparedExecutionEnvironment, type WorkspaceOption, type CanonWorkspaceRootMetadata, type RuntimeStreamingPayload, type TurnLifecycleState, type TurnOutputBlock, type TurnVerbosity, type TurnVerbosityConfig } from '@canonmsg/core';
 import { type CodexSandboxMode } from './adapter.js';
 import { type CodexSkillMetadata } from './app-server-adapter.js';
@@ -49,6 +49,7 @@ export declare function buildCodexServiceSnapshotConfig(input: {
     executionMode: "locked";
     executionBranch: null;
 };
+export declare function createCodexRecoveryCheckpointTracker(persist: (messageId: string) => boolean): RecoveryCheckpointTracker;
 /** Conservative fallback used only when native app-server discovery is unavailable. */
 export declare const CODEX_EFFORT_OPTIONS: readonly CodexControlOption[];
 export declare const CODEX_SESSION_CONFIG_FIELDS: readonly ["permissionMode", "effort"];
@@ -60,6 +61,7 @@ export declare function buildCodexRuntimeDescriptor(input: {
     workspaces: WorkspaceOption[];
     workspaceRoots?: CanonWorkspaceRootMetadata[];
     executionModes: ExecutionEnvironmentMode[];
+    defaultExecutionMode?: ExecutionEnvironmentMode;
     permissionModes: Array<{
         value: string;
         label: string;
@@ -86,7 +88,7 @@ export declare function getCodexRequestingUserId(message: {
 }): string | null;
 export declare function resolveSessionExecutionMode(config: {
     executionMode?: ExecutionEnvironmentMode;
-} | null | undefined, serviceAgentMode?: boolean): ExecutionEnvironmentMode;
+} | null | undefined, serviceAgentMode?: boolean, defaultExecutionMode?: ExecutionEnvironmentMode): ExecutionEnvironmentMode;
 export declare function resolveCodexSessionConfig<T extends Record<string, unknown>>(config: T | null | undefined, serviceAgentMode?: boolean): T | null;
 export declare function resolveWorkspaceCwd(config: {
     workspaceId?: string;

package/dist/host.js

@@ -5,12 +5,12 @@ import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
 import { getCodexImagePath, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, } from '@canonmsg/agent-sdk';
-import { buildTrailBlockId, buildUndeliverableFinalNotice, captureTurnArtifactSnapshot, createTurnArtifactRouter, IDLE_TIMEOUT_MS, PLAN_BLOCK_TITLE, resolveTurnArtifactRouting, collectMissedInboundMessages, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from '@canonmsg/coding-agent-host';
+import { buildTrailBlockId, buildUndeliverableFinalNotice, captureTurnArtifactSnapshot, createTurnArtifactRouter, IDLE_TIMEOUT_MS, PLAN_BLOCK_TITLE, resolveTurnArtifactRouting, collectMissedInboundMessages, createRecoveryCheckpointTracker, createReconnectRecoveryCoordinator, STARTUP_RECOVERY_PAGE_SIZE, } from '@canonmsg/coding-agent-host';
 import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, resolveQuestionAllowOther, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, buildCanonInboundFrameV1, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, decideAutoReply, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, markLocalRuntimeStopped, normalizeTurnMetadata, parseTurnVerbosityConfig, RuntimeRequestManager, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, verifyResolvedAgentEnvironment, CanonApiError, loadRuntimeSessionState, sendMessageWithRetry, sendMessageWithRetryChunked, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, isSilentTurnSuppressed, resolveSilentTurnDelivery, resolveTurnVerbosity, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { validateCard } from '@canonmsg/rich-cards';
 import { CodexConversationAdapter, } from './adapter.js';
 import { CodexAppServerAdapter, } from './app-server-adapter.js';
-import { CODEX_APP_DYNAMIC_TOOLS, CODEX_NO_REPLY_MODEL_TOOL_NAME, CODEX_SERVICE_AGENT_DYNAMIC_TOOLS, answerCodexNoReply, classifyCodexAppToolRequest, deniedCodexAppToolResult, handleCodexAppToolCall, isCanonRuntimeControlToolCall, isCodexAppToolCall, isCodexServiceAgentToolCall, parseCanonRuntimeControlRequest, readCodexNoReplyReason, successfulCodexAppToolResult, } from './codex-app-tools.js';
+import { CODEX_APP_DYNAMIC_TOOLS, CODEX_NO_REPLY_MODEL_TOOL_NAME, CODEX_SERVICE_AGENT_DYNAMIC_TOOLS, answerCodexNoReply, classifyCodexAppToolRequest, deniedCodexAppToolResult, filterCodexCommunicationTools, handleCodexAppToolCall, handleCodexCommunicateToolCall, isCanonRuntimeControlToolCall, isCodexAppToolCall, isCodexCommunicateToolCall, isCodexServiceAgentToolCall, parseCanonRuntimeControlRequest, readCodexNoReplyReason, successfulCodexAppToolResult, } from './codex-app-tools.js';
 import { mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
 import { clearStoredThreadId, buildCodexThreadPolicyFingerprint, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
 import { deriveCodexPermissionEnvelope, mapCanonPermissionToCodex, } from './permission-mode.js';
@@ -30,6 +30,7 @@ COMMON FLAGS
   --cwd <path>                         Project directory to run Codex from
   --workspace <path>                   Additional project to expose in Canon
   --workspace-root <path>              Discover projects under an approved root
+  --default-execution-mode <mode>      New-conversation default: worktree or locked
   --model <model>                      Default Codex model for new turns
   --sandbox <mode>                     Codex sandbox mode
   --full-auto                          Allow non-interactive write access
@@ -93,6 +94,9 @@ export function buildCodexServiceSnapshotConfig(input) {
     };
 }
 const MAX_SESSIONS = 12;
+export function createCodexRecoveryCheckpointTracker(persist) {
+    return createRecoveryCheckpointTracker(persist);
+}
 // IDLE_TIMEOUT_MS (30 minutes) is shared with the other coding-agent hosts.
 const HEARTBEAT_MS = 30_000;
 /** How Codex says it finished the work but Canon would not take the answer. */
@@ -196,6 +200,7 @@ export function buildCodexRuntimeDescriptor(input) {
         workspaces: serviceAgentMode ? [] : input.workspaces,
         workspaceRoots: serviceAgentMode ? undefined : input.workspaceRoots,
         executionModes: serviceAgentMode ? [] : input.executionModes,
+        defaultExecutionMode: serviceAgentMode ? 'locked' : input.defaultExecutionMode,
         permissionModes: serviceAgentMode ? [] : input.permissionModes,
         defaultPermissionMode: serviceAgentMode ? undefined : input.defaultPermissionMode,
         permissionModeLabel: 'Execution policy',
@@ -286,12 +291,17 @@ async function loadSessionConfig(conversationId, agentId, rtdb) {
         extraStringFields: CODEX_SESSION_CONFIG_FIELDS,
     });
 }
-export function resolveSessionExecutionMode(config, serviceAgentMode = false) {
+export function resolveSessionExecutionMode(config, serviceAgentMode = false, defaultExecutionMode = 'worktree') {
     if (serviceAgentMode)
         return 'locked';
-    if (config?.executionMode)
-        return config.executionMode;
-    throw new ExecutionEnvironmentError('Session config is missing an execution mode.', 'Choose Isolated worktree or Use shared project before starting this coding session.');
+    return config?.executionMode ?? defaultExecutionMode;
+}
+function resolveConfiguredDefaultExecutionMode(value) {
+    if (value == null || value === '')
+        return 'worktree';
+    if (value === 'worktree' || value === 'locked')
+        return value;
+    throw new Error('--default-execution-mode must be worktree or locked');
 }
 export function resolveCodexSessionConfig(config, serviceAgentMode = false) {
     return serviceAgentMode ? null : config ?? null;
@@ -633,6 +643,7 @@ export async function main() {
             'add-dir': { type: 'string', multiple: true },
             workspace: { type: 'string', multiple: true },
             'workspace-root': { type: 'string', multiple: true },
+            'default-execution-mode': { type: 'string' },
             config: { type: 'string', multiple: true },
             'codex-bin': { type: 'string' },
             'runtime-visibility': { type: 'string' },
@@ -657,8 +668,11 @@ export async function main() {
         onWarning: (message) => console.error(`[canon-codex] ${message}`),
     });
     const serviceAgentMode = args['service-agent'] === true;
+    const defaultExecutionMode = serviceAgentMode
+        ? 'locked'
+        : resolveConfiguredDefaultExecutionMode(args['default-execution-mode']);
     const nativeVisionEnabled = args['no-native-vision'] !== true;
-    const codexDynamicTools = serviceAgentMode
+    const baseCodexDynamicTools = serviceAgentMode
         ? CODEX_SERVICE_AGENT_DYNAMIC_TOOLS
         : CODEX_APP_DYNAMIC_TOOLS;
     workingDir = (typeof args.cwd === 'string' ? args.cwd : null) || process.cwd();
@@ -703,11 +717,13 @@ export async function main() {
     let agentId;
     let ownerId = null;
     let ownerName = null;
+    let outboundPolicy = null;
     try {
         const ctx = await client.getAgentMe();
         agentId = ctx.agentId;
         ownerId = ctx.ownerId;
         ownerName = ctx.ownerName;
+        outboundPolicy = ctx.outboundPolicy;
         console.error(`[canon-codex] Connected as ${ctx.displayName || agentId}`);
     }
     catch {
@@ -720,6 +736,7 @@ export async function main() {
         }
         console.error(`[canon-codex] Authenticated as ${agentId}`);
     }
+    const codexDynamicTools = filterCodexCommunicationTools(baseCodexDynamicTools, outboundPolicy);
     // Shared poll/timeout engine. Built-in `input`/`card` descriptors own
     // create+poll (codex passes native/responder policy via payload/options).
     // Approval keeps codex's own resolution shape (no owner-authored outcome
@@ -816,7 +833,15 @@ export async function main() {
     });
     const sessions = new Map();
     const pendingSessionCreations = new Map();
-    let inboundRecoverySequence = 0;
+    const recoveryCheckpointTrackers = new Map();
+    function recoveryCheckpointsFor(conversationId) {
+        let tracker = recoveryCheckpointTrackers.get(conversationId);
+        if (!tracker) {
+            tracker = createCodexRecoveryCheckpointTracker((messageId) => persistInboundRecoveryCursor(conversationId, messageId));
+            recoveryCheckpointTrackers.set(conversationId, tracker);
+        }
+        return tracker;
+    }
     const conversationCache = new Map();
     const knownConversationIds = new Set();
     const promptedGroupContextConversationIds = new Set();
@@ -964,27 +989,20 @@ export async function main() {
     }
     function persistInboundRecoveryCursor(conversationId, messageId) {
         if (!messageId)
-            return;
+            return true;
         try {
             saveRuntimeSessionState(runtimeId, {
                 conversationId,
                 baseCwd: workingDir,
                 lastInboundMessageId: messageId,
             });
+            return true;
         }
         catch (error) {
             console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Failed to persist inbound recovery cursor:`, error instanceof Error ? error.message : error);
+            return false;
         }
     }
-    function persistInboundRecoveryCursorWhenIdle(conversationId, messageId) {
-        const session = sessions.get(conversationId);
-        // A later queued turn will advance past this non-triggering message. Do
-        // not write it ahead of earlier work and then let that work regress the
-        // cursor when it completes.
-        if (session?.running || (session?.queue.length ?? 0) > 0)
-            return;
-        persistInboundRecoveryCursor(conversationId, messageId);
-    }
     async function markQueuedPromptsRejected(conversationId, prompts) {
         await Promise.all(prompts.map((prompt) => {
             if (!prompt.markAccepted || !prompt.sourceMessageId)
@@ -992,27 +1010,21 @@ export async function main() {
             return client.updateMessageDisposition(conversationId, prompt.sourceMessageId, 'rejected').catch(() => { });
         }));
     }
-    function rememberDroppedRecoveryCursor(session, prompts) {
-        const latest = prompts.reduce((current, prompt) => (prompt.sourceMessageId && (!current || prompt.recoverySequence > current.recoverySequence)
-            ? prompt
-            : current), null)?.sourceMessageId;
-        if (!latest)
-            return;
-        if (session.running) {
-            session.pendingDroppedRecoveryCursor = latest;
-            return;
-        }
-        persistInboundRecoveryCursor(session.conversationId, latest);
+    function settleRejectedPromptCheckpoints(conversationId, prompts) {
+        const checkpoints = recoveryCheckpointsFor(conversationId);
+        for (const prompt of prompts)
+            checkpoints.settle(prompt.sourceMessageId);
     }
     function removeQueuedPrompt(conversationId, sourceMessageId) {
         const session = sessions.get(conversationId);
         if (!session || session.queue.length === 0)
             return;
-        const before = session.queue.length;
+        const removed = session.queue.filter((prompt) => prompt.sourceMessageId === sourceMessageId);
+        if (removed.length === 0)
+            return;
         session.queue = session.queue.filter((prompt) => prompt.sourceMessageId !== sourceMessageId);
-        if (session.queue.length !== before) {
-            writeTurn(session);
-        }
+        settleRejectedPromptCheckpoints(conversationId, removed);
+        writeTurn(session);
     }
     function clearStreaming(conversationId) {
         runtimeState.clearStreaming(conversationId).catch(() => { });
@@ -1196,7 +1208,7 @@ export async function main() {
         session.resetRequested = true;
         const droppedPrompts = session.queue.splice(0);
         await markQueuedPromptsRejected(conversationId, droppedPrompts);
-        rememberDroppedRecoveryCursor(session, droppedPrompts);
+        settleRejectedPromptCheckpoints(conversationId, droppedPrompts);
         clearStoredThreadId(runtimeId, conversationId, session.environment.baseCwd, session.environment.mode);
         session.adapter.clearThreadId();
         session.activeSelfContextId = null;
@@ -1250,7 +1262,7 @@ export async function main() {
         }
         const creation = (async () => {
             const config = resolveCodexSessionConfig(await loadSessionConfig(conversationId, agentId, rtdb), serviceAgentMode);
-            const sessionExecutionMode = resolveSessionExecutionMode(config, serviceAgentMode);
+            const sessionExecutionMode = resolveSessionExecutionMode(config, serviceAgentMode, defaultExecutionMode);
             const workspaceCwd = resolveWorkspaceCwd(config, serviceAgentMode);
             const environment = prepareConversationEnvironment({
                 agentId,
@@ -1331,7 +1343,6 @@ export async function main() {
                     currentTurnSilenced: false,
                     activeSelfContextId: null,
                     lastAcceptedIntent: null,
-                    pendingDroppedRecoveryCursor: null,
                     resetRequested: false,
                     lastActivity: Date.now(),
                     typingKeepaliveTimer: null,
@@ -1373,7 +1384,6 @@ export async function main() {
             canUseCodexAppTools: turn.canUseCodexAppTools ?? false,
             ...(turn.turnVerbosity ? { turnVerbosity: turn.turnVerbosity } : {}),
             requestingUserId: turn.requestingUserId ?? null,
-            recoverySequence: ++inboundRecoverySequence,
         };
         if (toFront) {
             session.queue.unshift(nextPrompt);
@@ -1440,6 +1450,12 @@ export async function main() {
         const params = request.params;
         const expiresAt = Date.now() + 30 * 60_000;
         if (request.method === 'item/tool/call' && isCodexAppToolCall(params)) {
+            if (isCodexCommunicateToolCall(params)) {
+                if (!(session.adapter instanceof CodexAppServerAdapter)) {
+                    return deniedCodexAppToolResult('This Codex transport does not support dynamic tools.');
+                }
+                return handleCodexCommunicateToolCall(client, params);
+            }
             if (serviceAgentMode && !isCodexServiceAgentToolCall(params)) {
                 return deniedCodexAppToolResult('This service agent exposes only Canon conversation tools.');
             }
@@ -1759,7 +1775,7 @@ export async function main() {
         knownConversationIds.add(input.conversationId);
         if (input.turnDispatch && input.turnDispatch.kind !== 'run_turn') {
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Suppressed server-dispatched turn: ${input.turnDispatch.reason}`);
-            persistInboundRecoveryCursorWhenIdle(input.conversationId, input.message.id);
+            recoveryCheckpointsFor(input.conversationId).settle(input.message.id);
             return;
         }
         if (input.message.metadata?.type === 'plan_approval_reply') {
@@ -1767,7 +1783,7 @@ export async function main() {
                 // A service agent never advertises or enters plan mode. Consume stale
                 // replies left by an older coding descriptor instead of turning them
                 // into hidden plan/implementation prompts after an upgrade or restart.
-                persistInboundRecoveryCursorWhenIdle(input.conversationId, input.message.id);
+                recoveryCheckpointsFor(input.conversationId).settle(input.message.id);
                 return;
             }
             const planId = readString(input.message.metadata, 'planId');
@@ -1775,7 +1791,7 @@ export async function main() {
                 senderId: input.message.senderId,
                 metadata: input.message.metadata,
             })) {
-                persistInboundRecoveryCursorWhenIdle(input.conversationId, input.message.id);
+                recoveryCheckpointsFor(input.conversationId).settle(input.message.id);
                 return;
             }
             const session = await getOrCreateSession(input.conversationId);
@@ -1849,7 +1865,7 @@ export async function main() {
             : decideAutoReply(participantContext, behavior);
         if (!autoReply.allow) {
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Suppressed auto-reply: ${autoReply.reason}`);
-            persistInboundRecoveryCursorWhenIdle(input.conversationId, input.message.id);
+            recoveryCheckpointsFor(input.conversationId).settle(input.message.id);
             return;
         }
         console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Message from ${input.senderName}: "${content.slice(0, 80)}" (${autoReply.reason})`);
@@ -1873,7 +1889,7 @@ export async function main() {
                     replyBehavior: 'suppress_auto_reply',
                 },
             }).catch(() => { });
-            persistInboundRecoveryCursor(input.conversationId, input.message.id);
+            recoveryCheckpointsFor(input.conversationId).settle(input.message.id);
             return;
         }
         session.activeSelfContextId = activeSelfContextId;
@@ -2333,11 +2349,7 @@ export async function main() {
         finally {
             session.currentTurnAbortController?.abort(new Error('Codex turn ended'));
             session.currentTurnAbortController = null;
-            persistInboundRecoveryCursor(session.conversationId, nextTurn.sourceMessageId);
-            if (session.pendingDroppedRecoveryCursor) {
-                persistInboundRecoveryCursor(session.conversationId, session.pendingDroppedRecoveryCursor);
-                session.pendingDroppedRecoveryCursor = null;
-            }
+            recoveryCheckpointsFor(session.conversationId).settle(nextTurn.sourceMessageId);
             stopVisibleWorkSignal(session);
             session.running = false;
             session.state.state = 'idle';
@@ -2404,6 +2416,7 @@ export async function main() {
     });
     let codexSkills = [];
     const buildCurrentRuntimeDescriptor = () => ({
+        defaultExecutionMode,
         ...(serviceAgentMode
             ? {}
             : {
@@ -2423,6 +2436,7 @@ export async function main() {
             workspaces: buildPublicWorkspaceOptions(workspaceOptions),
             workspaceRoots: workspaceRootMetadata,
             executionModes: hostAvailableExecutionModes,
+            defaultExecutionMode,
             permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
             defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
             presentation: runtimePresentation,
@@ -2550,7 +2564,7 @@ export async function main() {
         if (type === 'stop_and_drop') {
             const droppedPrompts = session.queue.splice(0);
             await markQueuedPromptsRejected(conversationId, droppedPrompts);
-            rememberDroppedRecoveryCursor(session, droppedPrompts);
+            settleRejectedPromptCheckpoints(conversationId, droppedPrompts);
         }
         if (session.running) {
             session.currentTurnAbortController?.abort(new Error(`Codex turn interrupted by ${type}`));
@@ -2745,6 +2759,84 @@ export async function main() {
             publishRuntimeDetailsInFlight = false;
         }
     };
+    let startupRecoveryComplete = false;
+    async function recoverInboundMessageGaps() {
+        // A reconnect can reveal conversations created while this host was
+        // offline. Refresh before sweeping cursors; this is one REST reconciliation
+        // pass, not an automatic retry loop.
+        const knownBeforeRefresh = new Set(knownConversationIds);
+        await refreshKnownConversationIds(true);
+        const conversationsDiscoveredWhileOffline = startupRecoveryComplete
+            ? new Set([...knownConversationIds].filter((id) => !knownBeforeRefresh.has(id)))
+            : new Set();
+        for (const conversationId of knownConversationIds) {
+            const recoveryCheckpoints = recoveryCheckpointsFor(conversationId);
+            const recoveryBatch = recoveryCheckpoints.reserveBatch();
+            try {
+                const cursor = loadRuntimeSessionState(runtimeId, {
+                    conversationId,
+                    baseCwd: workingDir,
+                })?.lastInboundMessageId ?? null;
+                const recovered = await collectMissedInboundMessages({
+                    fetchPage: (before) => client.getMessagesPage(conversationId, STARTUP_RECOVERY_PAGE_SIZE, before),
+                    cursor,
+                    agentId,
+                    requireContiguousCursor: true,
+                    noCursorMode: conversationsDiscoveredWhileOffline.has(conversationId)
+                        ? 'bounded-window'
+                        : 'latest-only',
+                });
+                recoveryBatch.commit(recovered.messages.map((message) => message.id), recovered.mode === 'incomplete-gap' ? recovered.recoveryCursor : null);
+                if (recovered.mode === 'incomplete-gap') {
+                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] recovery_incomplete_gap: cursor is missing; replaying ${recovered.messages.length} bounded inbound message(s) before advancing to ${recovered.recoveryCursor ?? 'no cursor'}`);
+                }
+                for (const message of recovered.messages) {
+                    const isPlanReply = isCodexPlanApprovalReply(message.metadata, serviceAgentMode);
+                    if (!isPlanReply && !shouldTriggerAgentTurn({
+                        senderType: message.senderType,
+                        metadata: message.metadata,
+                    }).allow) {
+                        recoveryCheckpoints.settle(message.id);
+                        continue;
+                    }
+                    if (!claimInboundMessageId(message.id))
+                        continue;
+                    try {
+                        await enqueueInboundMessage({
+                            conversationId,
+                            message,
+                            senderName: message.senderName || message.senderId,
+                            isOwner: message.senderId === ownerId,
+                            behavior: recovered.newestPage.behavior,
+                            activeSelfContextId: recovered.newestPage.activeSelfContextIdByMessageId?.[message.id] ?? null,
+                            selfContexts: recovered.newestPage.selfContexts,
+                            hydratedPage: recovered.newestPage,
+                        });
+                        settleInboundMessageId(message.id, true);
+                    }
+                    catch (error) {
+                        settleInboundMessageId(message.id, false);
+                        throw error;
+                    }
+                }
+                if (recovered.messages.length > 0) {
+                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Recovered ${recovered.messages.length} inbound message(s) (${recovered.mode})`);
+                }
+            }
+            catch (error) {
+                recoveryBatch.cancel();
+                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Recovery failed:`, error instanceof Error ? error.message : error);
+            }
+        }
+    }
+    const reconnectRecovery = createReconnectRecoveryCoordinator(recoverInboundMessageGaps);
+    const observeReconnectRecovery = (reason, recovery) => {
+        if (!recovery)
+            return;
+        void recovery.catch((error) => {
+            console.error(`[canon-codex] ${reason} recovery failed:`, error instanceof Error ? error.message : error);
+        });
+    };
     const stream = new CanonStream({
         apiKey,
         agentId,
@@ -2756,9 +2848,10 @@ export async function main() {
                     return;
                 if (!claimInboundMessageId(message.id))
                     return;
+                recoveryCheckpointsFor(payload.conversationId).track(message.id);
                 if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
                     console.error(`[canon-codex] [${payload.conversationId.slice(0, 8)}] Ignoring server-dispatched observe-only message: ${payload.turnDispatch.reason}`);
-                    persistInboundRecoveryCursorWhenIdle(payload.conversationId, message.id);
+                    recoveryCheckpointsFor(payload.conversationId).settle(message.id);
                     settleInboundMessageId(message.id, true);
                     return;
                 }
@@ -2786,6 +2879,7 @@ export async function main() {
             onConnected: () => {
                 streamConnected = true;
                 void publishRuntimeHeartbeat();
+                observeReconnectRecovery('reconnect', reconnectRecovery.onConnected());
                 console.error('[canon-codex] SSE connected');
             },
             onDisconnected: () => {
@@ -2793,6 +2887,7 @@ export async function main() {
                 runtimeState.clearAgentRuntime().catch(() => { });
                 console.error('[canon-codex] SSE disconnected');
             },
+            onReplayExpired: () => observeReconnectRecovery('replay-expired', reconnectRecovery.onReplayExpired()),
             onError: (error) => console.error(`[canon-codex] SSE error: ${error.message}`),
         },
     });
@@ -2811,57 +2906,10 @@ export async function main() {
     catch (error) {
         console.error('[canon-codex] Failed to load startup conversations:', error);
     }
-    for (const conversationId of knownConversationIds) {
-        try {
-            const cursor = loadRuntimeSessionState(runtimeId, {
-                conversationId,
-                baseCwd: workingDir,
-            })?.lastInboundMessageId ?? null;
-            const recovered = await collectMissedInboundMessages({
-                fetchPage: (before) => client.getMessagesPage(conversationId, STARTUP_RECOVERY_PAGE_SIZE, before),
-                cursor,
-                agentId,
-            });
-            if (recovered.mode === 'truncated-window') {
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Recovery cursor was not found within ${STARTUP_RECOVERY_MAX_MESSAGES} messages; replaying the bounded recent window`);
-            }
-            for (const message of recovered.messages) {
-                const isPlanReply = isCodexPlanApprovalReply(message.metadata, serviceAgentMode);
-                if (!isPlanReply && !shouldTriggerAgentTurn({
-                    senderType: message.senderType,
-                    metadata: message.metadata,
-                }).allow) {
-                    persistInboundRecoveryCursorWhenIdle(conversationId, message.id);
-                    continue;
-                }
-                if (!claimInboundMessageId(message.id))
-                    continue;
-                try {
-                    await enqueueInboundMessage({
-                        conversationId,
-                        message,
-                        senderName: message.senderName || message.senderId,
-                        isOwner: message.senderId === ownerId,
-                        behavior: recovered.newestPage.behavior,
-                        activeSelfContextId: recovered.newestPage.activeSelfContextIdByMessageId?.[message.id] ?? null,
-                        selfContexts: recovered.newestPage.selfContexts,
-                        hydratedPage: recovered.newestPage,
-                    });
-                    settleInboundMessageId(message.id, true);
-                }
-                catch (error) {
-                    settleInboundMessageId(message.id, false);
-                    throw error;
-                }
-            }
-            if (recovered.messages.length > 0) {
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Recovered ${recovered.messages.length} inbound message(s) (${recovered.mode})`);
-            }
-        }
-        catch (error) {
-            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Startup recovery failed:`, error instanceof Error ? error.message : error);
-        }
-    }
+    await reconnectRecovery.recoverNow().catch((error) => {
+        console.error('[canon-codex] Startup recovery failed:', error instanceof Error ? error.message : error);
+    });
+    startupRecoveryComplete = true;
     startCodexStreamInBackground(stream, (error) => {
         console.error('[canon-codex] SSE start error:', error instanceof Error ? error.message : error);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "scripts"
   ],
   "scripts": {
-    "prepare:workspace-deps": "node ../../scripts/run-workspace-prep.mjs ../core ../agent-sdk ../coding-agent-host ../rich-cards",
+    "prepare:workspace-deps": "node ../../scripts/run-workspace-prep.mjs ../core ../agent-sdk ../agent-tools ../coding-agent-host ../rich-cards",
     "build": "npm run prepare:workspace-deps && node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "npm run prepare:workspace-deps && tsc --watch",
     "smoke": "node scripts/smoke-test.mjs",
@@ -29,10 +29,11 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^8.3.0",
-    "@canonmsg/coding-agent-host": "^0.5.0",
-    "@canonmsg/core": "^10.3.1",
-    "@canonmsg/rich-cards": "^0.10.0"
+    "@canonmsg/agent-sdk": "^9.0.0",
+    "@canonmsg/agent-tools": "^0.7.0",
+    "@canonmsg/coding-agent-host": "^0.7.0",
+    "@canonmsg/core": "^11.0.0",
+    "@canonmsg/rich-cards": "^0.10.3"
   },
   "engines": {
     "node": ">=18.0.0"