@canonmsg/codex-plugin 0.28.0 → 0.29.0

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

@@ -21,6 +21,8 @@ export interface CodexAppToolRuntime {
     currentThreadId: string | null;
     currentCwd: string;
     workspaces: ReadonlyArray<CodexAppToolWorkspace>;
+    /** Whether detached work may see Canon's autonomous communication surface. */
+    communicationEnabled?: boolean;
     model?: string | null;
     effort?: string | null;
 }

package/dist/codex-app-tools.js

@@ -265,9 +265,11 @@ export const CODEX_SERVICE_AGENT_DYNAMIC_TOOLS = [
 ];
 /** 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;
+    const communicationEnabled = outboundPolicy === 'open'
+        || outboundPolicy === 'approval-required';
+    return communicationEnabled
+        ? tools
+        : tools.filter((entry) => entry.name !== CODEX_COMMUNICATE_TOOL_NAME);
 }
 /**
  * Tools exposed to detached Codex threads created through the bridge. Canon
@@ -465,7 +467,7 @@ async function createThread(runtime, args) {
     const started = await runtime.adapter.requestAppServer('thread/start', {
         cwd,
         ...(readString(args, 'model') ?? runtime.model ? { model: readString(args, 'model') ?? runtime.model } : {}),
-        dynamicTools: CODEX_DETACHED_THREAD_DYNAMIC_TOOLS,
+        dynamicTools: filterCodexCommunicationTools(CODEX_DETACHED_THREAD_DYNAMIC_TOOLS, runtime.communicationEnabled === true ? 'open' : null),
         experimentalRawEvents: false,
         persistExtendedHistory: true,
     });

package/dist/control-channel.d.ts

@@ -5,18 +5,14 @@
  * codex host characterization profile (the "codex host profile" describe
  * block in core's control-poller.test.ts is the contract):
  *
- * - Keys: `session` + `signal`, plus `primitive` when a primitive handler is
- *   configured; read sequentially per conversation, conversations polled one
- *   at a time.
+ * - Keys: `signal`, plus `primitive` when a primitive handler is configured;
+ *   read sequentially per conversation, conversations polled one at a time.
  * - Cadence: immediate first cycle, then active/idle delays + jitter with
  *   the activity probe sampled BEFORE the cycle runs.
- * - Session controls are always consumed once newer (default consume), even
- *   when no live session applied them; signals are NOT consumed when the
- *   handler throws (consumeOnError stays false).
  * - Dedupe is primed eagerly via `poller.baseline([conversationId])` at
- *   session creation — the second legacy poll site.
+ *   session creation.
  */
-import { ControlChannelPoller, type ControlChannelRTDB, type ControlHandlerResult, type ControlPollerError, type ControlPrimitiveEvent, type ControlSessionEvent, type ControlSignalEvent } from '@canonmsg/core';
+import { ControlChannelPoller, type ControlChannelRTDB, type ControlHandlerResult, type ControlPollerError, type ControlPrimitiveEvent, type ControlSignalEvent } from '@canonmsg/core';
 export declare const CONTROL_POLL_MS = 2000;
 export declare const IDLE_CONTROL_POLL_MS = 10000;
 export declare const CONTROL_POLL_JITTER_MS = 1000;
@@ -28,12 +24,6 @@ export interface CodexControlChannelInput {
     conversationIds: () => Iterable<string>;
     /** Sampled before each cycle to choose the active vs idle delay. */
     hasActiveWork: () => boolean;
-    /**
-     * Applies a newer `/session` control node. The node is always consumed
-     * after the handler resolves; a thrown error leaves it in place (with
-     * dedupe already advanced, so it is never retried).
-     */
-    onSessionControl: (event: ControlSessionEvent) => Promise<ControlHandlerResult> | ControlHandlerResult;
     /**
      * Handles a newer `/signal` node. Return `{ consume: false }` to leave the
      * node in place; thrown errors also leave it (consumeOnError stays false).

package/dist/control-channel.js

@@ -5,16 +5,12 @@
  * codex host characterization profile (the "codex host profile" describe
  * block in core's control-poller.test.ts is the contract):
  *
- * - Keys: `session` + `signal`, plus `primitive` when a primitive handler is
- *   configured; read sequentially per conversation, conversations polled one
- *   at a time.
+ * - Keys: `signal`, plus `primitive` when a primitive handler is configured;
+ *   read sequentially per conversation, conversations polled one at a time.
  * - Cadence: immediate first cycle, then active/idle delays + jitter with
  *   the activity probe sampled BEFORE the cycle runs.
- * - Session controls are always consumed once newer (default consume), even
- *   when no live session applied them; signals are NOT consumed when the
- *   handler throws (consumeOnError stays false).
  * - Dedupe is primed eagerly via `poller.baseline([conversationId])` at
- *   session creation — the second legacy poll site.
+ *   session creation.
  */
 import { ControlChannelPoller, } from '@canonmsg/core';
 export const CONTROL_POLL_MS = 2_000;
@@ -36,9 +32,6 @@ export function createCodexControlPoller(input) {
         pollOnStart: true,
         conversationConcurrency: 'sequential',
         handlers: {
-            session: {
-                handle: input.onSessionControl,
-            },
             signal: {
                 handle: input.onSignal,
             },

package/dist/host.d.ts

@@ -21,38 +21,9 @@ export declare function buildCodexInitialSessionState(input: {
     permissionMode?: string;
     effort?: string | null;
 }): HostSessionState;
-export declare function buildCodexLiveSessionConfig(input: {
-    model?: string;
-    permissionMode?: string;
-    effort?: string;
-    workspaceId?: string | null;
-    executionMode: ExecutionEnvironmentMode;
-    executionBranch?: string | null;
-}): {
-    executionMode: ExecutionEnvironmentMode;
-    executionBranch: string | null;
-    workspaceId?: string | undefined;
-    effort?: string | undefined;
-    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"];
 export declare function buildCodexSkillCommands(skills: ReadonlyArray<CodexSkillMetadata>): CanonRuntimeCommandDescriptor[];
 export declare function buildCodexRuntimeDescriptor(input: {
     models: CodexControlOption[];
@@ -86,14 +57,8 @@ export declare function getCodexRequestingUserId(message: {
     senderId: string;
     senderType?: 'human' | 'ai_agent';
 }): string | null;
-export declare function resolveSessionExecutionMode(config: {
-    executionMode?: 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;
-    retiredWorkspaceConfig?: boolean;
-} | null, serviceAgentMode?: boolean): string;
+export declare function resolveSessionExecutionMode(serviceAgentMode?: boolean, defaultExecutionMode?: ExecutionEnvironmentMode): ExecutionEnvironmentMode;
+export declare function resolveWorkspaceCwd(): string;
 interface CodexEffectiveRuntimePolicy {
     model?: string;
     permissionMode?: string;

package/dist/host.js

@@ -6,7 +6,7 @@ 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, 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 { 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, releaseConversationEnvironment, resolveLocalRuntimeSessionState, resolveCanonAgent, verifyResolvedAgentEnvironment, CanonApiError, loadRuntimeSessionState, sendMessageWithRetry, sendMessageWithRetryChunked, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveConfiguredWorkspaceCwd, 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';
@@ -69,36 +69,14 @@ export function buildCodexInitialSessionState(input) {
         state: 'idle',
     };
 }
-export function buildCodexLiveSessionConfig(input) {
-    return {
-        ...(input.model ? { model: input.model } : {}),
-        ...(input.permissionMode ? { permissionMode: input.permissionMode } : {}),
-        ...(input.effort ? { effort: input.effort } : {}),
-        ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
-        executionMode: input.executionMode,
-        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;
+const LOCAL_CONFIGURATION_REQUIRED_MESSAGE = 'This agent needs local runtime configuration before it can start this conversation. '
+    + 'Its operator must configure it and retry.';
 /** How Codex says it finished the work but Canon would not take the answer. */
 const CODEX_UNDELIVERABLE_FINAL_WORDING = {
     lead: 'The Codex host completed the turn, but Canon could not deliver the reply',
@@ -113,18 +91,13 @@ const CODEX_RUNTIME_CAPABILITIES = {
     supportsNonFinalPermanentMessages: false,
 };
 let workingDir = process.cwd();
-/**
- * Agent-developer setting, resolved once at startup. Deliberately NOT read from
- * `/session-config`: that path is the USER's per-conversation control plane,
- * and owner ruling 5 puts turn verbosity outside user control.
- */
+/** Turn verbosity is local agent-developer configuration, resolved at startup. */
 let configuredTurnVerbosity = null;
 let workspaceOptions = [];
 let workspaceRoots = [];
 let workspaceRootMetadata = [];
 /** Conservative fallback used only when native app-server discovery is unavailable. */
 export const CODEX_EFFORT_OPTIONS = FALLBACK_CODEX_EFFORT_OPTIONS;
-export const CODEX_SESSION_CONFIG_FIELDS = ['permissionMode', 'effort'];
 const MAX_CODEX_SKILL_COMMAND_CHOICES = 50;
 export function buildCodexSkillCommands(skills) {
     return skills
@@ -283,18 +256,10 @@ export function getCodexRequestingUserId(message) {
 async function publishAgentRuntime(agentId, runtime, rtdb) {
     await publishHostAgentRuntime(agentId, 'codex', runtime, rtdb);
 }
-async function loadSessionConfig(conversationId, agentId, rtdb) {
-    return loadHostSessionConfig({
-        conversationId,
-        agentId,
-        rtdb,
-        extraStringFields: CODEX_SESSION_CONFIG_FIELDS,
-    });
-}
-export function resolveSessionExecutionMode(config, serviceAgentMode = false, defaultExecutionMode = 'worktree') {
+export function resolveSessionExecutionMode(serviceAgentMode = false, defaultExecutionMode = 'worktree') {
     if (serviceAgentMode)
         return 'locked';
-    return config?.executionMode ?? defaultExecutionMode;
+    return defaultExecutionMode;
 }
 function resolveConfiguredDefaultExecutionMode(value) {
     if (value == null || value === '')
@@ -303,13 +268,10 @@ function resolveConfiguredDefaultExecutionMode(value) {
         return value;
     throw new Error('--default-execution-mode must be worktree or locked');
 }
-export function resolveCodexSessionConfig(config, serviceAgentMode = false) {
-    return serviceAgentMode ? null : config ?? null;
-}
-export function resolveWorkspaceCwd(config, serviceAgentMode = false) {
-    return resolveHostWorkspaceCwd({
+export function resolveWorkspaceCwd() {
+    return resolveConfiguredWorkspaceCwd({
         workspaceOptions,
-        config: serviceAgentMode ? null : config,
+        workspaceId: workspaceOptions[0]?.id,
         defaultCwd: workingDir,
     });
 }
@@ -736,7 +698,7 @@ export async function main() {
         }
         console.error(`[canon-codex] Authenticated as ${agentId}`);
     }
-    const codexDynamicTools = filterCodexCommunicationTools(baseCodexDynamicTools, outboundPolicy);
+    let 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
@@ -930,30 +892,8 @@ export async function main() {
         });
     }
     function writeState(session) {
-        const appliedAt = Date.now();
-        const controlState = {};
-        if (session.state.model !== undefined) {
-            controlState.model = { value: session.state.model, source: 'applied', appliedAt };
-        }
-        if (session.state.permissionMode !== undefined) {
-            controlState.permissionMode = { value: session.state.permissionMode, source: 'applied', appliedAt };
-        }
-        if (session.state.effort !== undefined) {
-            controlState.effort = { value: session.state.effort, source: 'applied', appliedAt };
-        }
         runtimeState.writeSessionState(session.conversationId, {
             lastError: session.state.lastError,
-            model: session.state.model,
-            permissionMode: session.state.permissionMode,
-            effort: session.state.effort,
-            controlState,
-            cwd: session.cwd,
-            executionMode: session.environment.mode,
-            ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
-            ...(session.environment.worktreePath ? { worktreePath: session.environment.worktreePath } : {}),
-            ...(resolveExecutionFallbackReason(session.environment)
-                ? { executionFallbackReason: resolveExecutionFallbackReason(session.environment) ?? undefined }
-                : {}),
             hostMode: true,
             clientType: 'codex',
             isActive: true,
@@ -1224,6 +1164,7 @@ export async function main() {
             session.currentTurnOpenedAt = null;
             session.currentTurnUpdatedAt = null;
             session.currentTurnCanUseCodexAppTools = false;
+            session.currentReplyAuthority = null;
             session.currentTurnSilenced = false;
             session.lastAcceptedIntent = null;
             session.resetRequested = false;
@@ -1261,20 +1202,47 @@ export async function main() {
             evictOldestIdle();
         }
         const creation = (async () => {
-            const config = resolveCodexSessionConfig(await loadSessionConfig(conversationId, agentId, rtdb), serviceAgentMode);
-            const sessionExecutionMode = resolveSessionExecutionMode(config, serviceAgentMode, defaultExecutionMode);
-            const workspaceCwd = resolveWorkspaceCwd(config, serviceAgentMode);
-            const environment = prepareConversationEnvironment({
+            const sessionExecutionMode = resolveSessionExecutionMode(serviceAgentMode, defaultExecutionMode);
+            const workspaceCwd = resolveWorkspaceCwd();
+            let environment = prepareConversationEnvironment({
                 agentId,
                 conversationId,
                 workspaceCwd,
                 allowWorktrees: sessionExecutionMode === 'worktree',
             });
             try {
+                const persistedMapping = resolveLocalRuntimeSessionState(runtimeId, {
+                    conversationId,
+                    baseCwd: environment.baseCwd,
+                    executionMode: environment.mode,
+                    resumeField: 'threadId',
+                    configuredBaseCwds: workspaceOptions.map((workspace) => workspace.cwd),
+                    availableExecutionModes: hostAvailableExecutionModes,
+                });
+                if (persistedMapping.status === 'configuration_required') {
+                    throw new ExecutionEnvironmentError(persistedMapping.message, LOCAL_CONFIGURATION_REQUIRED_MESSAGE);
+                }
+                if (persistedMapping.status === 'adopted'
+                    && (persistedMapping.state.baseCwd !== environment.baseCwd
+                        || persistedMapping.state.executionMode !== environment.mode)) {
+                    const restoredEnvironment = prepareConversationEnvironment({
+                        agentId,
+                        conversationId,
+                        workspaceCwd: persistedMapping.state.baseCwd,
+                        allowWorktrees: persistedMapping.state.executionMode === 'worktree',
+                    });
+                    if (restoredEnvironment.mode !== persistedMapping.state.executionMode) {
+                        releaseConversationEnvironment(restoredEnvironment);
+                        throw new ExecutionEnvironmentError(`Conversation ${conversationId} requires local execution mode ${persistedMapping.state.executionMode}, but workspace ${persistedMapping.state.baseCwd} can only be opened in ${restoredEnvironment.mode} mode.`, LOCAL_CONFIGURATION_REQUIRED_MESSAGE);
+                    }
+                    releaseConversationEnvironment(environment);
+                    environment = restoredEnvironment;
+                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Restoring saved local runtime → ${environment.mode} (${environment.baseCwd})`);
+                }
                 const sessionCwd = environment.cwd;
                 const policy = resolveCodexEffectiveRuntimePolicy({
                     args,
-                    config,
+                    config: null,
                     permissionEnvelope: codexPermissionEnvelope,
                     environment,
                     serviceAgentMode,
@@ -1283,12 +1251,17 @@ export async function main() {
                 if (modelGuard) {
                     throw new ExecutionEnvironmentError(modelGuard, modelGuard);
                 }
-                const storedThreadId = loadStoredThreadId(runtimeId, conversationId, environment.baseCwd, environment.mode, policy.fingerprint);
+                const storedThreadId = loadStoredThreadId(runtimeId, conversationId, environment.baseCwd, environment.mode, policy.fingerprint, {
+                    ...(persistedMapping.status === 'new' || !persistedMapping.state.workspaceId
+                        ? {}
+                        : { workspaceId: persistedMapping.state.workspaceId }),
+                    allowLegacyPolicyMigration: persistedMapping.status !== 'new',
+                });
                 const effectiveModel = policy.model ?? codexDefaultModel;
                 const initialEffortResolution = resolveCodexEffortForModel({
                     models: codexModels,
                     model: effectiveModel,
-                    requestedEffort: config?.effort ?? configuredCodexEffort,
+                    requestedEffort: configuredCodexEffort,
                 });
                 const initialEffort = initialEffortResolution.value;
                 const adapter = useAppServer
@@ -1336,6 +1309,7 @@ export async function main() {
                     currentTurnOpenedAt: null,
                     currentTurnUpdatedAt: null,
                     currentTurnCanUseCodexAppTools: false,
+                    currentReplyAuthority: null,
                     currentTurnAbortController: null,
                     // Corrected by the first turn that runs; a session with no turn
                     // publishes nothing anyway, and quiet is never an accident.
@@ -1353,6 +1327,10 @@ export async function main() {
                 };
                 sessions.set(conversationId, session);
                 await controlPoller.baseline([conversationId]);
+                await runtimeState.patchAgentSessionSnapshot(conversationId, {
+                    configurationStatus: 'ready',
+                    lastError: null,
+                });
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Environment → ${environment.mode} (${sessionCwd})`);
                 writeState(session);
                 writeTurn(session);
@@ -1384,6 +1362,7 @@ export async function main() {
             canUseCodexAppTools: turn.canUseCodexAppTools ?? false,
             ...(turn.turnVerbosity ? { turnVerbosity: turn.turnVerbosity } : {}),
             requestingUserId: turn.requestingUserId ?? null,
+            replyAuthority: turn.replyAuthority ?? null,
         };
         if (toFront) {
             session.queue.unshift(nextPrompt);
@@ -1454,6 +1433,9 @@ export async function main() {
                 if (!(session.adapter instanceof CodexAppServerAdapter)) {
                     return deniedCodexAppToolResult('This Codex transport does not support dynamic tools.');
                 }
+                if (outboundPolicy !== 'open' && outboundPolicy !== 'approval-required') {
+                    return deniedCodexAppToolResult('Outbound communication is not enabled by the agent operator.');
+                }
                 return handleCodexCommunicateToolCall(client, params);
             }
             if (serviceAgentMode && !isCodexServiceAgentToolCall(params)) {
@@ -1588,6 +1570,8 @@ export async function main() {
                 currentThreadId: session.adapter.getThreadId(),
                 currentCwd: session.cwd,
                 workspaces: workspaceOptions,
+                communicationEnabled: outboundPolicy === 'open'
+                    || outboundPolicy === 'approval-required',
                 model: session.state.model ?? null,
                 effort: session.state.effort ?? null,
             }, params);
@@ -1878,16 +1862,22 @@ export async function main() {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            const userMessage = error instanceof ExecutionEnvironmentError ? error.userMessage : message;
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to create session: ${message}`);
+            await runtimeState.patchAgentSessionSnapshot(input.conversationId, {
+                configurationStatus: 'configuration_required',
+                lastError: LOCAL_CONFIGURATION_REQUIRED_MESSAGE,
+            }).catch(() => { });
             await markQueuedMessageAccepted(input.conversationId, input.message.id, shouldMarkAccepted);
-            await sendMessageWithRetryChunked(client, input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
+            await sendMessageWithRetryChunked(client, input.conversationId, LOCAL_CONFIGURATION_REQUIRED_MESSAGE, {
                 messageId: `codex-start-failed-${input.message.id}`,
                 ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                 metadata: {
+                    turnId: `codex-start:${input.message.id}`,
+                    runtimeStatus: 'configuration_required',
                     turnSemantics: 'turn_complete',
                     replyBehavior: 'suppress_auto_reply',
                 },
+                ...(input.replyAuthority ? { replyAuthority: input.replyAuthority } : {}),
             }).catch(() => { });
             recoveryCheckpointsFor(input.conversationId).settle(input.message.id);
             return;
@@ -1906,7 +1896,10 @@ export async function main() {
             ...(useAppServer ? { noReplyToolName: CODEX_NO_REPLY_MODEL_TOOL_NAME } : {}),
         });
         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),
+                replyAuthority: input.replyAuthority ?? null,
+            });
             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(() => { });
@@ -1914,10 +1907,14 @@ 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),
+            replyAuthority: input.replyAuthority ?? null,
+        });
     }
     function sendTurnArtifactFile(session, file) {
         return sendMediaFileMessage(client, session.conversationId, file.path, '', {
+            ...(session.currentReplyAuthority ? { replyAuthority: session.currentReplyAuthority } : {}),
             ...(session.activeSelfContextId ? { selfContextId: session.activeSelfContextId } : {}),
             metadata: {
                 ...(session.currentTurnId ? { turnId: session.currentTurnId } : {}),
@@ -1945,6 +1942,7 @@ export async function main() {
         session.currentTurnOpenedAt = Date.now();
         session.currentTurnUpdatedAt = session.currentTurnOpenedAt;
         session.currentTurnCanUseCodexAppTools = nextTurn.canUseCodexAppTools === true;
+        session.currentReplyAuthority = nextTurn.replyAuthority;
         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.
@@ -2249,6 +2247,9 @@ export async function main() {
                 const turnTrail = buildFinalTurnTrail(session);
                 await sendMessageWithRetryChunked(client, session.conversationId, result.finalMessage, {
                     messageId: buildCodexMessageId(session, 'final'),
+                    ...(session.currentReplyAuthority
+                        ? { replyAuthority: session.currentReplyAuthority }
+                        : {}),
                     ...(session.activeSelfContextId
                         ? { selfContextId: session.activeSelfContextId }
                         : {}),
@@ -2274,6 +2275,9 @@ export async function main() {
                 const turnTrail = buildFinalTurnTrail(session);
                 await sendMessageWithRetryChunked(client, session.conversationId, userVisibleError, {
                     messageId: buildCodexMessageId(session, 'error'),
+                    ...(session.currentReplyAuthority
+                        ? { replyAuthority: session.currentReplyAuthority }
+                        : {}),
                     ...(session.activeSelfContextId
                         ? { selfContextId: session.activeSelfContextId }
                         : {}),
@@ -2330,6 +2334,9 @@ export async function main() {
             await routeArtifactsOnce();
             await sendMessageWithRetryChunked(client, session.conversationId, message, {
                 messageId: buildCodexMessageId(session, 'failure'),
+                ...(session.currentReplyAuthority
+                    ? { replyAuthority: session.currentReplyAuthority }
+                    : {}),
                 ...(session.activeSelfContextId
                     ? { selfContextId: session.activeSelfContextId }
                     : {}),
@@ -2358,6 +2365,7 @@ export async function main() {
             session.currentTurnOpenedAt = null;
             session.currentTurnUpdatedAt = null;
             session.currentTurnCanUseCodexAppTools = false;
+            session.currentReplyAuthority = null;
             session.currentTurnSilenced = false;
             session.lastAcceptedIntent = null;
             session.resetRequested = false;
@@ -2486,64 +2494,6 @@ export async function main() {
             probe.close();
         }
     }
-    function applySessionControl(conversationId, control) {
-        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)) {
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Ignoring model outside the discovered Codex catalog (${control.model})`);
-                writeState(session);
-                return;
-            }
-            const modelGuard = buildCodexModelGuardMessage(control.model, codexCliStatus);
-            if (modelGuard) {
-                session.state.lastError = modelGuard;
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${modelGuard}`);
-                writeState(session);
-                // The poller consumes the node; skip effort handling for this pass,
-                // matching the legacy loop.
-                return;
-            }
-            session.adapter.setModel(control.model);
-            session.state.model = control.model;
-            modelChanged = true;
-            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Model set for next turn -> ${control.model}`);
-        }
-        if (control.permissionMode) {
-            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] approval mode is session-creation-only; ignoring mid-session change request (${control.permissionMode})`);
-            // Convergence contract: a consumed session control must always be
-            // answered. Re-publish the currently applied state so clients settle on
-            // the authoritative value instead of holding the composer until timeout.
-        }
-        if (control.effort || modelChanged) {
-            const effortResolution = resolveCodexEffortForModel({
-                models: codexModels,
-                model: session.state.model,
-                requestedEffort: control.effort ?? session.state.effort,
-            });
-            if (effortResolution.value !== session.state.effort) {
-                session.adapter.setReasoningEffort(effortResolution.value);
-                session.state.effort = effortResolution.value ?? undefined;
-            }
-            if (control.effort && !effortResolution.accepted) {
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${control.effort} is unsupported by ${session.state.model ?? 'the active model'}; reset to ${effortResolution.value ?? 'the model default'}`);
-            }
-            else if (control.effort) {
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Reasoning effort set for next turn -> ${control.effort}`);
-            }
-            else if (modelChanged && effortResolution.value) {
-                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Reasoning effort for ${session.state.model} -> ${effortResolution.value}`);
-            }
-        }
-        writeState(session);
-    }
     async function handleControlSignal(event) {
         const { conversationId, type } = event;
         const session = sessions.get(conversationId);
@@ -2609,9 +2559,6 @@ export async function main() {
         conversationIds: () => sessions.keys(),
         hasActiveWork: () => [...sessions.values()].some((session) => !session.closed
             && (session.running || session.queue.length > 0 || session.turnState === 'waiting_input')),
-        onSessionControl: ({ conversationId, control }) => {
-            applySessionControl(conversationId, control);
-        },
         onSignal: handleControlSignal,
         onPrimitive: handleControlPrimitive,
         onError: (error) => {
@@ -2647,41 +2594,6 @@ export async function main() {
                 agentId,
                 rtdb,
                 clientType: 'codex',
-                runtime: runtimeDescriptor,
-                workspaceOptions,
-                defaultCwd: workingDir,
-                extraSessionConfigFields: CODEX_SESSION_CONFIG_FIELDS,
-                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 [
-                        conversationId,
-                        buildCodexLiveSessionConfig({
-                            model: session.state.model,
-                            permissionMode: session.state.permissionMode,
-                            effort: session.state.effort,
-                            workspaceId,
-                            executionMode: session.environment.mode,
-                            executionBranch: session.environment.branch ?? null,
-                        }),
-                    ];
-                })),
             }).catch((error) => {
                 console.error('[canon-codex] Failed to publish session snapshots:', error);
             });
@@ -2865,6 +2777,7 @@ export async function main() {
                     selfContexts: payload.selfContexts,
                     provenance: payload.provenance,
                     turnDispatch: payload.turnDispatch,
+                    replyAuthority: payload.replyAuthority,
                 }).then(() => settleInboundMessageId(message.id, true), (error) => {
                     settleInboundMessageId(message.id, false);
                     console.error(`[canon-codex] [${payload.conversationId.slice(0, 8)}] Failed to queue inbound message:`, error instanceof Error ? error.message : error);
@@ -2876,6 +2789,12 @@ export async function main() {
             onConversationUpdated: (payload) => {
                 handleConversationUpdated(payload);
             },
+            onAgentContext: (context) => {
+                ownerId = context.ownerId;
+                ownerName = context.ownerName;
+                outboundPolicy = context.outboundPolicy;
+                codexDynamicTools = filterCodexCommunicationTools(baseCodexDynamicTools, outboundPolicy);
+            },
             onConnected: () => {
                 streamConnected = true;
                 void publishRuntimeHeartbeat();

package/dist/register.js

@@ -12,6 +12,7 @@ REQUIRED
 
 FLAGS
   --profile <name>           Local profile name in ~/.canon/agents.json
+  --agent-id <id>            Reconnect this exact transferred agent identity
   --environment <id>        Canon environment ID (or CANON_ENVIRONMENT_ID; default: canon-prod-v1)
   --base-url <url>           Canon API base URL override
   --stream-url <url>         Canon stream URL override
@@ -23,6 +24,7 @@ FLAGS
 EXAMPLES
   canon-codex-register --name "My Codex" --description "Local coding agent" --phone "+15551234567"
   canon-codex-register --name "Frontend" --description "React work" --phone "+15551234567" --profile frontend
+  canon-codex-register --name "Sold Agent" --description "Existing agent" --phone "+15551234567" --agent-id <id>
 
 After approval, start it with CANON_AGENT=<profile> canon-codex --cwd /path/to/project.`;
 const OPTIONS = {

package/dist/session-store.d.ts

@@ -1,4 +1,5 @@
 import { type ExecutionEnvironmentMode } from '@canonmsg/core';
+export declare const CODEX_LOCAL_POLICY_FINGERPRINT_FORMAT: "local-v1";
 export declare function buildCodexThreadPolicyFingerprint(input: {
     baseCwd: string;
     executionMode?: ExecutionEnvironmentMode;
@@ -10,6 +11,9 @@ export declare function buildCodexThreadPolicyFingerprint(input: {
     fullAuto?: boolean;
     bypassApprovalsAndSandbox?: boolean;
 }): string;
-export declare function loadStoredThreadId(runtimeId: string, conversationId: string, baseCwd: string, executionMode?: ExecutionEnvironmentMode, policyFingerprint?: string): string | null;
+export declare function loadStoredThreadId(runtimeId: string, conversationId: string, baseCwd: string, executionMode?: ExecutionEnvironmentMode, policyFingerprint?: string, options?: {
+    workspaceId?: string;
+    allowLegacyPolicyMigration?: boolean;
+}): string | null;
 export declare function saveStoredThreadId(runtimeId: string, conversationId: string, baseCwd: string, threadId: string, executionMode?: ExecutionEnvironmentMode, policyFingerprint?: string): void;
 export declare function clearStoredThreadId(runtimeId: string, conversationId: string, baseCwd?: string, executionMode?: ExecutionEnvironmentMode): void;

package/dist/session-store.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { clearRuntimeSessionState, loadRuntimeSessionState, saveRuntimeSessionState, } from '@canonmsg/core';
+export const CODEX_LOCAL_POLICY_FINGERPRINT_FORMAT = 'local-v1';
 export function buildCodexThreadPolicyFingerprint(input) {
     return createHash('sha256').update(JSON.stringify({
         version: 2,
@@ -20,18 +21,24 @@ export function buildCodexThreadPolicyFingerprint(input) {
         bypassApprovalsAndSandbox: input.bypassApprovalsAndSandbox === true,
     })).digest('hex').slice(0, 24);
 }
-export function loadStoredThreadId(runtimeId, conversationId, baseCwd, executionMode, policyFingerprint) {
+export function loadStoredThreadId(runtimeId, conversationId, baseCwd, executionMode, policyFingerprint, options = {}) {
     const state = loadRuntimeSessionState(runtimeId, {
         conversationId,
         baseCwd,
         executionMode,
+        workspaceId: options.workspaceId,
     });
     if (state?.threadId) {
         if (policyFingerprint && state.codexPolicyFingerprint !== policyFingerprint) {
+            if (options.allowLegacyPolicyMigration === true
+                && state.codexPolicyFingerprintFormat === undefined) {
+                return state.threadId;
+            }
             clearRuntimeSessionState(runtimeId, {
                 conversationId,
                 baseCwd,
                 executionMode,
+                workspaceId: options.workspaceId,
             });
             return null;
         }
@@ -45,7 +52,12 @@ export function saveStoredThreadId(runtimeId, conversationId, baseCwd, threadId,
         baseCwd,
         executionMode,
         threadId,
-        ...(policyFingerprint ? { codexPolicyFingerprint: policyFingerprint } : {}),
+        ...(policyFingerprint
+            ? {
+                codexPolicyFingerprint: policyFingerprint,
+                codexPolicyFingerprintFormat: CODEX_LOCAL_POLICY_FINGERPRINT_FORMAT,
+            }
+            : {}),
     });
 }
 export function clearStoredThreadId(runtimeId, conversationId, baseCwd, executionMode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -29,11 +29,11 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^9.0.0",
-    "@canonmsg/agent-tools": "^0.7.0",
+    "@canonmsg/agent-sdk": "^10.0.0",
+    "@canonmsg/agent-tools": "^0.8.0",
     "@canonmsg/coding-agent-host": "^0.7.0",
-    "@canonmsg/core": "^11.0.0",
-    "@canonmsg/rich-cards": "^0.10.3"
+    "@canonmsg/core": "^12.0.0",
+    "@canonmsg/rich-cards": "^0.10.4"
   },
   "engines": {
     "node": ">=18.0.0"