@canonmsg/codex-plugin 0.26.1 → 0.27.0

package/README.md

@@ -79,6 +79,10 @@ model cannot select another user, conversation, or responder. It can display a
 card with `send_card`, wait for an action card with `request_card`, or ask one
 standalone question with `request_input`.
 
+Service-agent sessions use the configured shared workspace and read-only local
+filesystem automatically. They do not ask conversation members to choose a
+coding workspace, execution mode, model, reasoning level, or permission mode.
+
 Authorized conversation members may use a service agent even when they do not
 own its Canon identity. Normal coding-host sessions keep their existing
 owner-only execution boundary.
@@ -105,6 +109,23 @@ discovery it also offers no model picker and a fixed effort list. It registers
 no dynamic tools either, so `no_reply` is unavailable there, the same way rich
 cards are.
 
+On the app-server transport, an owner-started foreground turn also receives a
+small Canon communication surface: `codex_app.canon_send_to`, contact/request
+and conversation listing, and `codex_app.canon_cancel_contact_request` for the
+agent's own pending DM requests. `canon_send_to` accepts one stable contact
+target and visible text; the host supplies trusted source-turn routing. These
+tools are withheld from non-owner turns, service-agent mode, detached threads,
+and the exec fallback. Contact cards only claim reach-out support when this
+exact surface is mounted.
+
+When a reach-out needs target-owner setup or approval, Canon parks the visible
+opener. Terminal request outcomes enter a deduplicated local lifecycle inbox and
+are supplied as trusted context on the next natural owner turn; they never start
+a synthetic model turn. A connected outcome means Canon already delivered the
+opener. After an SSE reconnect or expired replay window, the host refreshes
+memberships, reconciles outbound request phases, and recovers unseen messages
+from its persisted cursors before resuming live delivery.
+
 Set `CANON_CODEX_TRANSPORT=exec` or `CANON_CODEX_TRANSPORT=app-server` to skip
 the probe when it misfires.
 

package/dist/app-server-adapter.js

@@ -638,7 +638,13 @@ function isForegroundCanonToolCall(params) {
     const tool = rawTool.startsWith('codex_app.')
         ? rawTool.slice('codex_app.'.length)
         : rawTool;
-    return tool === 'canon_runtime_control' || tool === 'no_reply';
+    return tool === 'canon_runtime_control'
+        || tool === 'canon_send_to'
+        || tool === 'canon_list_contacts'
+        || tool === 'canon_list_contact_requests'
+        || tool === 'canon_list_conversations'
+        || tool === 'canon_cancel_contact_request'
+        || tool === 'no_reply';
 }
 function parseJson(line) {
     try {

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

@@ -1,4 +1,5 @@
-import { type NoReplyReportClient } from '@canonmsg/core';
+import { type CanonClient, type CanonVerbName, type NoReplyReportClient } from '@canonmsg/core';
+import { type OwnerBoundCanonContactTarget } from '@canonmsg/agent-tools';
 type JsonRecord = Record<string, unknown>;
 interface DynamicToolSpec {
     [key: string]: unknown;
@@ -44,6 +45,11 @@ 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_CANON_SEND_TO_TOOL_NAME = "canon_send_to";
+export declare const CODEX_CANON_LIST_CONTACTS_TOOL_NAME = "canon_list_contacts";
+export declare const CODEX_CANON_LIST_CONTACT_REQUESTS_TOOL_NAME = "canon_list_contact_requests";
+export declare const CODEX_CANON_LIST_CONVERSATIONS_TOOL_NAME = "canon_list_conversations";
+export declare const CODEX_CANON_CANCEL_CONTACT_REQUEST_TOOL_NAME = "canon_cancel_contact_request";
 /**
  * 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 —
@@ -65,7 +71,26 @@ 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 codexCanonVerbForToolCall(params: CodexAppToolCallParams): CanonVerbName | null;
+export declare function isCodexCanonVerbToolCall(params: CodexAppToolCallParams): boolean;
 export declare function isCodexServiceAgentToolCall(params: CodexAppToolCallParams): boolean;
+export interface CodexCanonVerbTrustedContext {
+    conversationId: string;
+    sourceMessageId: string | null;
+    turnId: string | null;
+    replyContactTarget?: OwnerBoundCanonContactTarget;
+}
+/**
+ * Execute the deliberately filtered canonical-verb projection. The model can
+ * author only the destination and visible copy. Provenance and turn metadata
+ * come exclusively from the active host turn, so a prompt cannot forge its
+ * source or make an outbound message look like an unrelated event.
+ */
+export declare function answerCodexCanonVerb(input: {
+    client: CanonClient;
+    params: CodexAppToolCallParams;
+    context: CodexCanonVerbTrustedContext;
+}): 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 { createOwnerBoundCanonCommunicationBinding, } from '@canonmsg/agent-tools';
 const emptyObjectSchema = {
     type: 'object',
     properties: {},
@@ -90,6 +91,21 @@ 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_CANON_SEND_TO_TOOL_NAME = 'canon_send_to';
+export const CODEX_CANON_LIST_CONTACTS_TOOL_NAME = 'canon_list_contacts';
+export const CODEX_CANON_LIST_CONTACT_REQUESTS_TOOL_NAME = 'canon_list_contact_requests';
+export const CODEX_CANON_LIST_CONVERSATIONS_TOOL_NAME = 'canon_list_conversations';
+export const CODEX_CANON_CANCEL_CONTACT_REQUEST_TOOL_NAME = 'canon_cancel_contact_request';
+const CODEX_CANON_COMMUNICATION_BINDING = createOwnerBoundCanonCommunicationBinding({
+    toolNames: {
+        send_to: CODEX_CANON_SEND_TO_TOOL_NAME,
+        list_contacts: CODEX_CANON_LIST_CONTACTS_TOOL_NAME,
+        list_contact_requests: CODEX_CANON_LIST_CONTACT_REQUESTS_TOOL_NAME,
+        list_conversations: CODEX_CANON_LIST_CONVERSATIONS_TOOL_NAME,
+        cancel_contact_request: CODEX_CANON_CANCEL_CONTACT_REQUEST_TOOL_NAME,
+    },
+});
+const CODEX_CANON_FOREGROUND_TOOL_NAMES = new Set(CODEX_CANON_COMMUNICATION_BINDING.tools.map((definition) => definition.name));
 /**
  * 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 +137,7 @@ const CANON_RUNTIME_CONTROL_TOOL = tool(CANON_RUNTIME_CONTROL_TOOL_NAME, 'Intera
     },
     required: ['action'],
 }, false);
+const CODEX_CANON_COMMUNICATION_TOOLS = CODEX_CANON_COMMUNICATION_BINDING.tools.map((definition) => tool(definition.name, definition.description, definition.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 '
@@ -244,6 +261,7 @@ export const CODEX_APP_DYNAMIC_TOOLS = [
         },
         required: ['threadId', 'title'],
     }),
+    ...CODEX_CANON_COMMUNICATION_TOOLS,
     CANON_RUNTIME_CONTROL_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.
@@ -260,7 +278,8 @@ export const CODEX_SERVICE_AGENT_DYNAMIC_TOOLS = [
  * human message; a child thread has neither that turn nor its responder.
  */
 export const CODEX_DETACHED_THREAD_DYNAMIC_TOOLS = CODEX_APP_DYNAMIC_TOOLS.filter((entry) => (entry.name !== CANON_RUNTIME_CONTROL_TOOL_NAME
-    && entry.name !== CODEX_NO_REPLY_TOOL_NAME));
+    && entry.name !== CODEX_NO_REPLY_TOOL_NAME
+    && !CODEX_CANON_FOREGROUND_TOOL_NAMES.has(entry.name)));
 const CODEX_APP_TOOL_NAMES = new Set(CODEX_APP_DYNAMIC_TOOLS.map((entry) => String(entry.name)));
 const UNSUPPORTED_TOOLS = new Map([
     ['automation_update', 'Canon does not manage Codex Desktop automations.'],
@@ -294,10 +313,53 @@ export function isCodexNoReplyToolCall(params) {
 export function isCanonRuntimeControlToolCall(params) {
     return normalizeToolName(params.tool) === CANON_RUNTIME_CONTROL_TOOL_NAME;
 }
+export function codexCanonVerbForToolCall(params) {
+    const toolName = normalizeToolName(params.tool);
+    return toolName ? CODEX_CANON_COMMUNICATION_BINDING.verbForToolName(toolName) : null;
+}
+export function isCodexCanonVerbToolCall(params) {
+    return codexCanonVerbForToolCall(params) !== null;
+}
 export function isCodexServiceAgentToolCall(params) {
     const toolName = normalizeToolName(params.tool);
     return toolName === CANON_RUNTIME_CONTROL_TOOL_NAME || toolName === CODEX_NO_REPLY_TOOL_NAME;
 }
+/**
+ * Execute the deliberately filtered canonical-verb projection. The model can
+ * author only the destination and visible copy. Provenance and turn metadata
+ * come exclusively from the active host turn, so a prompt cannot forge its
+ * source or make an outbound message look like an unrelated event.
+ */
+export async function answerCodexCanonVerb(input) {
+    const verb = codexCanonVerbForToolCall(input.params);
+    if (!verb)
+        return toolResult(false, { error: 'Unsupported Canon verb tool.' });
+    try {
+        const result = await CODEX_CANON_COMMUNICATION_BINDING.execute({
+            client: input.client,
+            toolName: normalizeToolName(input.params.tool) ?? '',
+            arguments: input.params.arguments,
+            context: input.context.sourceMessageId ? {
+                isOwnerTurn: true,
+                conversationId: input.context.conversationId,
+                sourceMessageId: input.context.sourceMessageId,
+                ...(input.context.turnId ? { turnId: input.context.turnId } : {}),
+                ...(input.context.replyContactTarget
+                    ? { replyContactTarget: input.context.replyContactTarget }
+                    : {}),
+            } : null,
+        });
+        return {
+            success: result.isError !== true,
+            contentItems: result.content.map((item) => ({ type: 'inputText', text: item.text })),
+        };
+    }
+    catch (error) {
+        return toolResult(false, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 export function parseCanonRuntimeControlRequest(params) {
     if (!isCanonRuntimeControlToolCall(params))
         return null;
@@ -386,6 +448,12 @@ export async function handleCodexAppToolCall(runtime, params) {
             error: 'canon_runtime_control is answered by the Canon host, not the app-tool bridge.',
         });
     }
+    if (CODEX_CANON_FOREGROUND_TOOL_NAMES.has(toolName)) {
+        return toolResult(false, {
+            tool: toolName,
+            error: `${toolName} is answered by the Canon host, not the app-tool bridge.`,
+        });
+    }
     const unsupportedReason = UNSUPPORTED_TOOLS.get(toolName);
     if (unsupportedReason) {
         return toolResult(false, { tool: toolName, error: unsupportedReason });
@@ -634,6 +702,21 @@ function parseToolArguments(value) {
     }
     return {};
 }
+function parseToolArgumentsStrict(value) {
+    if (value === undefined || value === null || value === '')
+        return {};
+    if (isRecord(value))
+        return value;
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 function normalizeToolName(value) {
     if (typeof value !== 'string' || !value.trim())
         return null;

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';
@@ -36,6 +36,20 @@ export declare function buildCodexLiveSessionConfig(input: {
     permissionMode?: string | undefined;
     model?: string | undefined;
 };
+export declare function buildCodexServiceSnapshotConfig(input: {
+    model?: string;
+    permissionMode?: string;
+    effort?: string;
+    workspaceId?: string;
+}): {
+    model: string | undefined;
+    permissionMode: string | undefined;
+    effort: string | undefined;
+    workspaceId: string | undefined;
+    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"];
@@ -56,7 +70,9 @@ export declare function buildCodexRuntimeDescriptor(input: {
     supportsPlanMode: boolean;
     supportsCompact?: boolean;
     supportsRichCards?: boolean;
+    supportsCanonCommunicationTools?: boolean;
     skills?: ReadonlyArray<CodexSkillMetadata>;
+    serviceAgentMode?: boolean;
 }): CanonRuntimeDescriptor;
 export declare function buildCodexTurnResponseRouting(input: {
     requestingUserId?: string | null;
@@ -73,6 +89,7 @@ export declare function getCodexRequestingUserId(message: {
 export declare function resolveSessionExecutionMode(config: {
     executionMode?: ExecutionEnvironmentMode;
 } | null | undefined, serviceAgentMode?: boolean): 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;
     retiredWorkspaceConfig?: boolean;
@@ -95,6 +112,19 @@ export declare function resolveCodexEffectiveRuntimePolicy(input: {
     environment: Pick<PreparedExecutionEnvironment, 'baseCwd' | 'mode'>;
     serviceAgentMode?: boolean;
 }): CodexEffectiveRuntimePolicy;
+export declare function resolveCodexPlanCommand(input: {
+    content: string;
+    requestedPlanMode: boolean;
+    useAppServer: boolean;
+    serviceAgentMode: boolean;
+}): {
+    planMode: boolean;
+    content: string;
+};
+export declare function isCodexPlanApprovalReply(metadata: unknown, serviceAgentMode?: boolean): metadata is Record<string, unknown> & {
+    type: 'plan_approval_reply';
+    decision: string;
+};
 /**
  * `--turn-verbosity` beats `CANON_TURN_VERBOSITY`; `null` means "unset, use the
  * per-conversation-type default".

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 { 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 { 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, HOST_ADMISSION_ACTIONS_DISABLED, 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, formatPendingContactLifecycleContext, heartbeatLocalRuntimeEntry, markLocalRuntimeStopped, normalizeTurnMetadata, parseTurnVerbosityConfig, RuntimeRequestManager, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, verifyResolvedAgentEnvironment, CanonApiError, loadRuntimeSessionState, sendMessageWithRetry, sendMessageWithRetryChunked, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, readLocalRuntimeEntry, reconcileContactLifecycleEvents, recordLocalRuntimeContactLifecycleEvent, saveLocalRuntimeContactLifecycleCursor, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, isSilentTurnSuppressed, resolveSilentTurnDelivery, resolveTurnVerbosity, shouldTriggerAgentTurn, takeLocalRuntimeContactLifecycleEvents, 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, answerCodexCanonVerb, answerCodexNoReply, classifyCodexAppToolRequest, deniedCodexAppToolResult, handleCodexAppToolCall, isCanonRuntimeControlToolCall, isCodexAppToolCall, isCodexCanonVerbToolCall, 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';
@@ -78,7 +78,24 @@ export function buildCodexLiveSessionConfig(input) {
         executionBranch: input.executionBranch ?? null,
     };
 }
+export function buildCodexServiceSnapshotConfig(input) {
+    // Keep every setup key present, including keys whose host value is
+    // undefined. `publishHostSessionSnapshots` merges this over any persisted
+    // coding config, so an absent host value clears rather than resurrects a
+    // stale member-selected value.
+    return {
+        model: input.model,
+        permissionMode: input.permissionMode,
+        effort: input.effort,
+        workspaceId: input.workspaceId,
+        executionMode: 'locked',
+        executionBranch: null,
+    };
+}
 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. */
@@ -138,6 +155,7 @@ export function buildCodexSkillCommands(skills) {
     });
 }
 export function buildCodexRuntimeDescriptor(input) {
+    const serviceAgentMode = input.serviceAgentMode === true;
     const commands = [
         {
             id: 'runtime-status',
@@ -157,7 +175,7 @@ export function buildCodexRuntimeDescriptor(input) {
         RUNTIME_STOP_ACTION,
         RUNTIME_STOP_AND_DROP_ACTION,
     ];
-    if (input.supportsCompact) {
+    if (input.supportsCompact && !serviceAgentMode) {
         commands.push({
             id: 'codex-compact-context',
             label: 'Compact',
@@ -177,20 +195,25 @@ export function buildCodexRuntimeDescriptor(input) {
     }
     const descriptor = buildFirstPartyCodingRuntimeDescriptor({
         clientType: 'codex',
-        models: input.models,
-        workspaces: input.workspaces,
-        workspaceRoots: input.workspaceRoots,
-        executionModes: input.executionModes,
-        permissionModes: input.permissionModes,
-        defaultPermissionMode: input.defaultPermissionMode,
+        models: serviceAgentMode ? [] : input.models,
+        workspaces: serviceAgentMode ? [] : input.workspaces,
+        workspaceRoots: serviceAgentMode ? undefined : input.workspaceRoots,
+        executionModes: serviceAgentMode ? [] : input.executionModes,
+        permissionModes: serviceAgentMode ? [] : input.permissionModes,
+        defaultPermissionMode: serviceAgentMode ? undefined : input.defaultPermissionMode,
         permissionModeLabel: 'Execution policy',
         modelLiveBehavior: 'next_turn',
-        effortOptions: input.effortOptions ?? [...CODEX_EFFORT_OPTIONS],
-        defaultEffort: input.defaultEffort ?? 'medium',
+        effortOptions: serviceAgentMode
+            ? []
+            : input.effortOptions ?? [...CODEX_EFFORT_OPTIONS],
+        defaultEffort: serviceAgentMode ? undefined : input.defaultEffort ?? 'medium',
         effortLiveBehavior: 'next_turn',
         presentation: input.presentation,
         streamingTextMode: 'snapshot',
-        ...(input.supportsPlanMode
+        admissionActions: input.supportsCanonCommunicationTools && !serviceAgentMode
+            ? { ...HOST_ADMISSION_ACTIONS_DISABLED, requestContact: true, reachOut: true }
+            : HOST_ADMISSION_ACTIONS_DISABLED,
+        ...(input.supportsPlanMode && !serviceAgentMode
             ? {
                 turnModes: [
                     {
@@ -220,7 +243,7 @@ export function buildCodexRuntimeDescriptor(input) {
                     rich: {
                         schema: 'canon.card.v1',
                         lifecycle: 'blocking_requires_action',
-                        responder: 'agent_owner',
+                        ...(serviceAgentMode ? {} : { responder: 'agent_owner' }),
                         result: 'action_or_values',
                         maxTimeoutMs: 30 * 60_000,
                         blockKinds: ['summary', 'metricGrid', 'chart', 'table', 'list', 'callout', 'actions'],
@@ -231,6 +254,13 @@ export function buildCodexRuntimeDescriptor(input) {
             }
             : {}),
     });
+    if (serviceAgentMode) {
+        const { runtimeControls: _runtimeControls, ...serviceDescriptor } = descriptor;
+        return {
+            ...serviceDescriptor,
+            coreControls: [],
+        };
+    }
     if (input.models.length > 0) {
         return descriptor;
     }
@@ -254,12 +284,13 @@ export function getCodexRequestingUserId(message) {
 async function publishAgentRuntime(agentId, runtime, rtdb) {
     await publishHostAgentRuntime(agentId, 'codex', runtime, rtdb);
 }
-async function loadSessionConfig(conversationId, agentId, rtdb) {
+async function loadSessionConfig(conversationId, agentId, rtdb, retryMissing = true) {
     return loadHostSessionConfig({
         conversationId,
         agentId,
         rtdb,
         extraStringFields: CODEX_SESSION_CONFIG_FIELDS,
+        retryMissingMs: retryMissing ? 3_000 : 0,
     });
 }
 export function resolveSessionExecutionMode(config, serviceAgentMode = false) {
@@ -269,6 +300,9 @@ export function resolveSessionExecutionMode(config, serviceAgentMode = false) {
         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.');
 }
+export function resolveCodexSessionConfig(config, serviceAgentMode = false) {
+    return serviceAgentMode ? null : config ?? null;
+}
 export function resolveWorkspaceCwd(config, serviceAgentMode = false) {
     return resolveHostWorkspaceCwd({
         workspaceOptions,
@@ -311,6 +345,9 @@ export function resolveCodexEffectiveRuntimePolicy(input) {
         baseCwd: input.environment.baseCwd,
         executionMode: input.environment.mode,
         permissionMode: permissionMode ?? null,
+        ...(input.serviceAgentMode
+            ? { serviceAgentMode: true, model: model ?? null }
+            : {}),
         sandbox,
         // `--ask-for-approval` is rejected at startup, so this was always null.
         // The key must stay: it is hashed into every persisted thread fingerprint.
@@ -340,8 +377,8 @@ function buildCanonPrompt(input) {
         message: input.message,
     })), input.noReplyToolName ? { noReplyToolName: input.noReplyToolName } : {});
 }
-function renderInboundContent(message, materialized) {
-    return renderCanonHostInboundContent(message, materialized);
+function renderInboundContent(message, materialized, options) {
+    return renderCanonHostInboundContent(message, materialized, options);
 }
 async function materializePromptReplyContext(input) {
     if (!input.replyContext?.found || !input.replyContext.attachments?.length) {
@@ -358,6 +395,16 @@ async function materializePromptReplyContext(input) {
         return { replyContext: input.replyContext, materialized: [] };
     }
 }
+function ownerBoundReplyContactTarget(replyContext) {
+    const card = replyContext?.found ? replyContext.contactCard : undefined;
+    if (!card?.userId)
+        return undefined;
+    return {
+        targetUserId: card.userId,
+        ...(card.canonContactId ? { canonContactId: card.canonContactId } : {}),
+        sourceCardMessageId: replyContext.messageId,
+    };
+}
 function summarizeCommand(command) {
     const trimmed = command.trim();
     if (!trimmed)
@@ -400,6 +447,14 @@ function parsePlanCommand(content) {
         content: rest || 'Please inspect the request and propose a plan before making changes.',
     };
 }
+export function resolveCodexPlanCommand(input) {
+    if (!input.useAppServer || input.serviceAgentMode) {
+        return { planMode: false, content: input.content };
+    }
+    return input.requestedPlanMode
+        ? { planMode: true, content: input.content }
+        : parsePlanCommand(input.content);
+}
 function mapCodexQuestions(value) {
     if (!Array.isArray(value))
         return undefined;
@@ -453,6 +508,12 @@ function mapCodexQuestions(value) {
 function isRecord(value) {
     return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
+export function isCodexPlanApprovalReply(metadata, serviceAgentMode = false) {
+    return !serviceAgentMode
+        && isRecord(metadata)
+        && metadata.type === 'plan_approval_reply'
+        && typeof metadata.decision === 'string';
+}
 function readString(record, key) {
     const value = record[key];
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
@@ -772,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();
@@ -858,6 +927,7 @@ export async function main() {
             ownerName,
             membershipChange: pendingMembershipChanges.get(input.conversationId) ?? null,
             groupContextMode: getGroupContextMode(input.conversationId, conversation),
+            renderOptions: input.renderOptions,
         });
     }
     function writeState(session) {
@@ -920,27 +990,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)
@@ -948,27 +1011,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(() => { });
@@ -1152,7 +1209,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;
@@ -1168,6 +1225,7 @@ export async function main() {
             session.currentTurnOpenedAt = null;
             session.currentTurnUpdatedAt = null;
             session.currentTurnCanUseCodexAppTools = false;
+            session.currentTurnCanUseCodexCanonTools = false;
             session.currentTurnSilenced = false;
             session.lastAcceptedIntent = null;
             session.resetRequested = false;
@@ -1205,7 +1263,7 @@ export async function main() {
             evictOldestIdle();
         }
         const creation = (async () => {
-            const config = await loadSessionConfig(conversationId, agentId, rtdb);
+            const config = resolveCodexSessionConfig(await loadSessionConfig(conversationId, agentId, rtdb, !serviceAgentMode), serviceAgentMode);
             const sessionExecutionMode = resolveSessionExecutionMode(config, serviceAgentMode);
             const workspaceCwd = resolveWorkspaceCwd(config, serviceAgentMode);
             const environment = prepareConversationEnvironment({
@@ -1280,6 +1338,8 @@ export async function main() {
                     currentTurnOpenedAt: null,
                     currentTurnUpdatedAt: null,
                     currentTurnCanUseCodexAppTools: false,
+                    currentTurnCanUseCodexCanonTools: false,
+                    currentTurnReplyContactTarget: null,
                     currentTurnAbortController: null,
                     // Corrected by the first turn that runs; a session with no turn
                     // publishes nothing anyway, and quiet is never an accident.
@@ -1287,7 +1347,6 @@ export async function main() {
                     currentTurnSilenced: false,
                     activeSelfContextId: null,
                     lastAcceptedIntent: null,
-                    pendingDroppedRecoveryCursor: null,
                     resetRequested: false,
                     lastActivity: Date.now(),
                     typingKeepaliveTimer: null,
@@ -1327,9 +1386,10 @@ export async function main() {
             planMode,
             artifactRoutingMode: turn.artifactRoutingMode ?? 'disabled',
             canUseCodexAppTools: turn.canUseCodexAppTools ?? false,
+            canUseCodexCanonTools: turn.canUseCodexCanonTools ?? false,
             ...(turn.turnVerbosity ? { turnVerbosity: turn.turnVerbosity } : {}),
             requestingUserId: turn.requestingUserId ?? null,
-            recoverySequence: ++inboundRecoverySequence,
+            ...(turn.replyContactTarget ? { replyContactTarget: turn.replyContactTarget } : {}),
         };
         if (toFront) {
             session.queue.unshift(nextPrompt);
@@ -1360,6 +1420,38 @@ export async function main() {
             requestingUserId: responseUserId,
         });
     }
+    function recordContactLifecycleEvent(request) {
+        if (request.requesterId !== agentId || !request.sourceConversationId)
+            return false;
+        return recordLocalRuntimeContactLifecycleEvent(runtimeId, request);
+    }
+    async function reconcileContactLifecycleInbox() {
+        let cursor = readLocalRuntimeEntry(runtimeId)?.contactLifecycleCursor ?? null;
+        let recorded = 0;
+        let duplicate = 0;
+        let ignored = 0;
+        for (let pageNumber = 0; pageNumber < 10; pageNumber += 1) {
+            const page = await client.listContactRequestLifecyclePage({
+                cursor,
+                limit: 100,
+            });
+            const result = await reconcileContactLifecycleEvents({
+                requests: page.requests,
+                requesterId: agentId,
+                record: (request) => recordLocalRuntimeContactLifecycleEvent(runtimeId, request),
+            });
+            recorded += result.recorded;
+            duplicate += result.duplicate;
+            ignored += result.ignored;
+            cursor = page.nextCursor;
+            saveLocalRuntimeContactLifecycleCursor(runtimeId, cursor);
+            if (!page.hasMore)
+                break;
+        }
+        if (recorded > 0) {
+            console.error(`[canon-codex] Contact lifecycle recovery: recorded=${recorded} duplicate=${duplicate} ignored=${ignored}`);
+        }
+    }
     function resolveArtifactRoutingMode(participantContext) {
         return participantContext.conversationType === 'direct' && participantContext.isOwner
             ? 'workspace-generated'
@@ -1371,15 +1463,19 @@ export async function main() {
      * so a prompt that waits behind another still runs under the answer it
      * arrived with.
      */
-    function resolveCodexTurnModes(participantContext, message) {
+    function resolveCodexTurnModes(participantContext, message, replyContext) {
         return {
             artifactRoutingMode: resolveArtifactRoutingMode(participantContext),
             canUseCodexAppTools: participantContext.isOwner || serviceAgentMode,
+            canUseCodexCanonTools: participantContext.isOwner && !serviceAgentMode,
             turnVerbosity: resolveTurnVerbosity({
                 configured: configuredTurnVerbosity,
                 conversationType: participantContext.conversationType,
             }),
             requestingUserId: getCodexRequestingUserId(message),
+            ...(participantContext.isOwner && replyContext
+                ? { replyContactTarget: ownerBoundReplyContactTarget(replyContext) }
+                : {}),
         };
     }
     function runtimeCardRequestPayload(method, params) {
@@ -1421,6 +1517,23 @@ export async function main() {
             if (disposition === 'denied-non-owner') {
                 return deniedCodexAppToolResult('Only the Canon owner can use codex_app tools.');
             }
+            if (isCodexCanonVerbToolCall(params)) {
+                if (!session.currentTurnCanUseCodexCanonTools) {
+                    return deniedCodexAppToolResult('Canon contact and conversation tools require a real owner-authored inbound turn.');
+                }
+                return await answerCodexCanonVerb({
+                    client,
+                    params,
+                    context: {
+                        conversationId: session.conversationId,
+                        sourceMessageId,
+                        turnId: session.currentTurnId,
+                        ...(session.currentTurnReplyContactTarget
+                            ? { replyContactTarget: session.currentTurnReplyContactTarget }
+                            : {}),
+                    },
+                });
+            }
             if (isCanonRuntimeControlToolCall(params)) {
                 const command = parseCanonRuntimeControlRequest(params);
                 if (!command) {
@@ -1715,18 +1828,23 @@ 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 (isRecord(input.message.metadata)
-            && input.message.metadata.type === 'plan_approval_reply'
-            && typeof input.message.metadata.decision === 'string') {
+        if (input.message.metadata?.type === 'plan_approval_reply') {
+            if (!isCodexPlanApprovalReply(input.message.metadata, serviceAgentMode)) {
+                // 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.
+                recoveryCheckpointsFor(input.conversationId).settle(input.message.id);
+                return;
+            }
             const planId = readString(input.message.metadata, 'planId');
             if (planId && runtimeRequests.handleMessage(input.conversationId, {
                 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);
@@ -1755,14 +1873,16 @@ export async function main() {
                 console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to materialize media:`, error instanceof Error ? error.message : error);
             }
         }
-        const renderedContent = renderInboundContent(input.message, materialized);
+        const renderOptions = resolveInboundContentRenderOptions(input.isOwner);
+        const renderedContent = renderInboundContent(input.message, materialized, renderOptions);
         const turnMetadata = normalizeTurnMetadata(input.message.metadata);
         const requestedPlanMode = turnMetadata?.requestedTurnMode === 'plan';
-        const planCommand = useAppServer
-            ? requestedPlanMode
-                ? { planMode: true, content: renderedContent }
-                : parsePlanCommand(renderedContent)
-            : { planMode: false, content: renderedContent };
+        const planCommand = resolveCodexPlanCommand({
+            content: renderedContent,
+            requestedPlanMode,
+            useAppServer,
+            serviceAgentMode,
+        });
         const content = planCommand.content;
         const hydrated = await loadHydratedInboundContext({
             conversationId: input.conversationId,
@@ -1773,6 +1893,7 @@ export async function main() {
             selfContexts: input.selfContexts,
             provenance: input.provenance,
             hydratedPage: input.hydratedPage,
+            renderOptions,
         });
         const behavior = input.behavior ?? hydrated.behavior;
         const activeSelfContextId = hydrated.activeSelfContextId;
@@ -1799,7 +1920,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})`);
@@ -1823,11 +1944,11 @@ 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;
-        const prompt = buildCanonPrompt({
+        const basePrompt = buildCanonPrompt({
             content,
             conversationId: input.conversationId,
             participantContext,
@@ -1839,8 +1960,12 @@ export async function main() {
             message: input.message,
             ...(useAppServer ? { noReplyToolName: CODEX_NO_REPLY_MODEL_TOOL_NAME } : {}),
         });
+        const lifecycleContext = input.isOwner
+            ? formatPendingContactLifecycleContext(takeLocalRuntimeContactLifecycleEvents(runtimeId, input.conversationId))
+            : null;
+        const prompt = lifecycleContext ? `${basePrompt}\n\n${lifecycleContext}` : basePrompt;
         if (session.running && deliveryIntent === 'interrupt') {
-            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, resolveCodexTurnModes(participantContext, input.message));
+            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, resolveCodexTurnModes(participantContext, input.message, replyContext));
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Interrupting current turn for explicit human send-now`);
             session.currentTurnAbortController?.abort(new Error('Codex turn interrupted by a newer message'));
             await session.adapter.interrupt().catch(() => { });
@@ -1848,7 +1973,7 @@ export async function main() {
             typingSignals.clear(input.conversationId).catch(() => { });
             return;
         }
-        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, resolveCodexTurnModes(participantContext, input.message));
+        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, resolveCodexTurnModes(participantContext, input.message, replyContext));
     }
     function sendTurnArtifactFile(session, file) {
         return sendMediaFileMessage(client, session.conversationId, file.path, '', {
@@ -1879,6 +2004,8 @@ export async function main() {
         session.currentTurnOpenedAt = Date.now();
         session.currentTurnUpdatedAt = session.currentTurnOpenedAt;
         session.currentTurnCanUseCodexAppTools = nextTurn.canUseCodexAppTools === true;
+        session.currentTurnCanUseCodexCanonTools = nextTurn.canUseCodexCanonTools === true;
+        session.currentTurnReplyContactTarget = nextTurn.replyContactTarget ?? null;
         session.currentTurnAbortController = new AbortController();
         // A continuation prompt (a plan-review result) carries none, and keeps the
         // conversation's last answer rather than silently reverting to verbose.
@@ -2283,11 +2410,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';
@@ -2296,6 +2419,8 @@ export async function main() {
             session.currentTurnOpenedAt = null;
             session.currentTurnUpdatedAt = null;
             session.currentTurnCanUseCodexAppTools = false;
+            session.currentTurnCanUseCodexCanonTools = false;
+            session.currentTurnReplyContactTarget = null;
             session.currentTurnSilenced = false;
             session.lastAcceptedIntent = null;
             session.resetRequested = false;
@@ -2354,14 +2479,18 @@ export async function main() {
     });
     let codexSkills = [];
     const buildCurrentRuntimeDescriptor = () => ({
-        defaultWorkspaceId: workspaceOptions[0]?.id,
+        ...(serviceAgentMode
+            ? {}
+            : {
+                defaultWorkspaceId: workspaceOptions[0]?.id,
+                availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                availableExecutionModes: hostAvailableExecutionModes,
+                availablePermissionModes: [...codexPermissionEnvelope.availablePermissionModes],
+                ...(codexPermissionEnvelope.defaultPermissionMode
+                    ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
+                    : {}),
+            }),
         ...(codexDefaultModel ? { defaultModel: codexDefaultModel } : {}),
-        availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
-        availableExecutionModes: hostAvailableExecutionModes,
-        availablePermissionModes: [...codexPermissionEnvelope.availablePermissionModes],
-        ...(codexPermissionEnvelope.defaultPermissionMode
-            ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
-            : {}),
         runtimeDescriptor: buildCodexRuntimeDescriptor({
             models: codexModelOptions,
             effortOptions: codexEffortOptions,
@@ -2375,10 +2504,25 @@ export async function main() {
             supportsPlanMode: useAppServer,
             supportsCompact: useAppServer,
             supportsRichCards: useAppServer,
+            supportsCanonCommunicationTools: useAppServer,
             skills: codexSkills,
+            serviceAgentMode,
         }),
     });
     let runtimeDescriptor = buildCurrentRuntimeDescriptor();
+    const resolveInboundContentRenderOptions = (isOwnerTurn) => {
+        const descriptorActions = runtimeDescriptor.runtimeDescriptor?.admissionActions
+            ?? HOST_ADMISSION_ACTIONS_DISABLED;
+        const admissionActions = isOwnerTurn && useAppServer && !serviceAgentMode
+            ? descriptorActions
+            : HOST_ADMISSION_ACTIONS_DISABLED;
+        return {
+            admissionActions,
+            ...(admissionActions.reachOut
+                ? { reachOutToolName: 'codex_app.canon_send_to' }
+                : {}),
+        };
+    };
     async function refreshCodexSkillInventory(forceReload = false) {
         if (!useAppServer)
             return;
@@ -2421,6 +2565,11 @@ export async function main() {
         const session = sessions.get(conversationId);
         if (!session || session.closed)
             return;
+        if (serviceAgentMode) {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Ignoring user session controls for service-agent runtime`);
+            writeState(session);
+            return;
+        }
         let modelChanged = false;
         if (control.model && control.model !== session.state.model) {
             if (codexModelOptions.length > 0 && !codexModelOptions.some((option) => option.value === control.model)) {
@@ -2490,7 +2639,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}`));
@@ -2577,10 +2726,27 @@ export async function main() {
                 workspaceOptions,
                 defaultCwd: workingDir,
                 extraSessionConfigFields: CODEX_SESSION_CONFIG_FIELDS,
-                liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
+                liveSessionConfigByConversation: new Map(Array.from(serviceAgentMode ? knownConversationIds : sessions.keys()).map((conversationId) => {
+                    const session = sessions.get(conversationId);
+                    if (serviceAgentMode) {
+                        return [
+                            conversationId,
+                            buildCodexServiceSnapshotConfig({
+                                model: codexDefaultModel ?? session?.state.model ?? undefined,
+                                permissionMode: codexPermissionEnvelope.defaultPermissionMode,
+                                effort: codexDefaultEffort ?? session?.state.effort ?? undefined,
+                                workspaceId: resolveWorkspaceIdForBaseCwd(workingDir) ?? undefined,
+                            }),
+                        ];
+                    }
+                    if (!session) {
+                        // Non-service snapshots are published only for live sessions,
+                        // but keep this branch total if that invariant changes.
+                        return [conversationId, {}];
+                    }
                     const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
                     return [
-                        session.conversationId,
+                        conversationId,
                         buildCodexLiveSessionConfig({
                             model: session.state.model,
                             permissionMode: session.state.permissionMode,
@@ -2668,6 +2834,90 @@ 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();
+        try {
+            await reconcileContactLifecycleInbox();
+        }
+        catch (error) {
+            console.error('[canon-codex] Contact lifecycle recovery failed:', error instanceof Error ? error.message : error);
+        }
+        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,
@@ -2679,9 +2929,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;
                 }
@@ -2706,9 +2957,13 @@ export async function main() {
             onConversationUpdated: (payload) => {
                 handleConversationUpdated(payload);
             },
+            onContactRequestUpdated: (payload) => {
+                recordContactLifecycleEvent(payload);
+            },
             onConnected: () => {
                 streamConnected = true;
                 void publishRuntimeHeartbeat();
+                observeReconnectRecovery('reconnect', reconnectRecovery.onConnected());
                 console.error('[canon-codex] SSE connected');
             },
             onDisconnected: () => {
@@ -2716,6 +2971,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}`),
         },
     });
@@ -2734,57 +2990,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 = message.metadata?.type === 'plan_approval_reply';
-                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/dist/register.js

@@ -28,6 +28,7 @@ After approval, start it with CANON_AGENT=<profile> canon-codex --cwd /path/to/p
 const OPTIONS = {
     moduleUrl: import.meta.url,
     clientType: 'codex',
+    sessionSetupPolicy: 'runtime_descriptor_required',
     cliName: 'canon-codex-register',
     hostBinName: 'canon-codex',
     developerInfo: 'Codex host plugin',

package/dist/session-store.d.ts

@@ -3,6 +3,8 @@ export declare function buildCodexThreadPolicyFingerprint(input: {
     baseCwd: string;
     executionMode?: ExecutionEnvironmentMode;
     permissionMode?: string | null;
+    model?: string | null;
+    serviceAgentMode?: boolean;
     sandbox?: string | null;
     approvalPolicy?: string | null;
     fullAuto?: boolean;

package/dist/session-store.js

@@ -6,6 +6,14 @@ export function buildCodexThreadPolicyFingerprint(input) {
         baseCwd: input.baseCwd,
         executionMode: input.executionMode ?? null,
         permissionMode: input.permissionMode ?? null,
+        // Service agents make the model a host-owned runtime choice. Include it,
+        // plus an explicit service-mode marker, so the first service-agent
+        // release drops coding threads that may retain a member-selected model
+        // and later host model changes start a clean thread. Ordinary Codex host
+        // fingerprints intentionally remain byte-for-byte compatible.
+        ...(input.serviceAgentMode
+            ? { serviceAgentMode: true, model: input.model ?? null }
+            : {}),
         sandbox: input.sandbox ?? null,
         approvalPolicy: input.approvalPolicy ?? null,
         fullAuto: input.fullAuto === true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.26.1",
+  "version": "0.27.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,9 +29,10 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^8.3.0",
-    "@canonmsg/coding-agent-host": "^0.5.0",
-    "@canonmsg/core": "^10.3.1",
+    "@canonmsg/agent-sdk": "^8.9.0",
+    "@canonmsg/agent-tools": "^0.6.0",
+    "@canonmsg/coding-agent-host": "^0.6.0",
+    "@canonmsg/core": "^10.7.0",
     "@canonmsg/rich-cards": "^0.10.0"
   },
   "engines": {