@canonmsg/claude-code-plugin 0.33.0 → 0.34.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "Canon",
   "description": "Connect Claude Code to Canon — messaging where AI agents are first-class citizens",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "channels": [
     {
       "server": "canon-channel",

package/dist/agent-context-state.d.ts

@@ -0,0 +1,15 @@
+import type { AgentContext } from '@canonmsg/core';
+/** Coordinates first identity discovery with the MCP client's cached tool list. */
+export declare class AgentContextState {
+    private readonly onCommunicationAvailabilityChanged;
+    private resolveReady;
+    private settled;
+    private contextValue;
+    readonly ready: Promise<void>;
+    constructor(onCommunicationAvailabilityChanged: () => void);
+    get current(): AgentContext | null;
+    set(context: AgentContext): void;
+    /** Resolve tools/list even when startup cannot obtain a trusted identity. */
+    settleUnavailable(): void;
+    private settle;
+}

package/dist/agent-context-state.js

@@ -0,0 +1,35 @@
+import { isProactiveCommunicationEnabled } from './communication-policy.js';
+/** Coordinates first identity discovery with the MCP client's cached tool list. */
+export class AgentContextState {
+    onCommunicationAvailabilityChanged;
+    resolveReady;
+    settled = false;
+    contextValue = null;
+    ready = new Promise((resolve) => {
+        this.resolveReady = resolve;
+    });
+    constructor(onCommunicationAvailabilityChanged) {
+        this.onCommunicationAvailabilityChanged = onCommunicationAvailabilityChanged;
+    }
+    get current() {
+        return this.contextValue;
+    }
+    set(context) {
+        const wasEnabled = isProactiveCommunicationEnabled(this.contextValue?.outboundPolicy);
+        this.contextValue = context;
+        this.settle();
+        const isEnabled = isProactiveCommunicationEnabled(context.outboundPolicy);
+        if (wasEnabled !== isEnabled)
+            this.onCommunicationAvailabilityChanged();
+    }
+    /** Resolve tools/list even when startup cannot obtain a trusted identity. */
+    settleUnavailable() {
+        this.settle();
+    }
+    settle() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.resolveReady();
+    }
+}

package/dist/communication-policy.d.ts

@@ -0,0 +1,2 @@
+/** Fail closed until trusted `/agents/me` context enables proactive communication. */
+export declare function isProactiveCommunicationEnabled(policy: unknown): boolean;

package/dist/communication-policy.js

@@ -0,0 +1,4 @@
+/** Fail closed until trusted `/agents/me` context enables proactive communication. */
+export function isProactiveCommunicationEnabled(policy) {
+    return policy === 'open' || policy === 'approval-required';
+}

package/dist/host.d.ts

@@ -25,9 +25,7 @@ export declare function buildClaudePlanAllowResult(input: Record<string, unknown
  * through. Canon-injected aliases keep precedence over native names.
  */
 export declare function buildNativeSlashCommandDescriptors(native: SDKControlReloadPluginsResponse['commands'], reservedAliases: ReadonlySet<string>): CanonRuntimeCommandDescriptor[];
-export declare function resolveSessionExecutionMode(config: {
-    executionMode?: ExecutionEnvironmentMode;
-} | null | undefined, defaultExecutionMode?: ExecutionEnvironmentMode): ExecutionEnvironmentMode;
+export declare function resolveSessionExecutionMode(defaultExecutionMode?: ExecutionEnvironmentMode): ExecutionEnvironmentMode;
 export declare function createClaudeRecoveryCheckpointTracker(persist: (messageId: string) => boolean): RecoveryCheckpointTracker;
 export declare const NO_REPLY_TOOL_NAME: string;
 export declare function buildCanonPrompt(input: {

package/dist/host.js

@@ -29,13 +29,14 @@ import { query, } from '@anthropic-ai/claude-agent-sdk';
 import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, } from '@canonmsg/agent-sdk';
 import { captureTurnArtifactSnapshot, createTurnArtifactRouter, IDLE_TIMEOUT_MS, collectMissedInboundMessages, createRecoveryCheckpointTracker, createReconnectRecoveryCoordinator, STARTUP_RECOVERY_PAGE_SIZE, } from '@canonmsg/coding-agent-host';
 import { buildCanonUserContent, renderClaudeInboundContent, withClaudeReplyContextMediaReferences, } from './canon-user-content.js';
-import { EFFORT_OPTIONS, CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonInboundFrameV1, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, normalizeRuntimeCommandDescriptors, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, ControlChannelPoller, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ApprovalManager, RuntimeRequestManager, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, parseTurnVerbosityConfig, prepareConversationEnvironment, resolveCanonAgent, verifyResolvedAgentEnvironment, decideAutoReply, initRTDBAuth, isChunkedSendMessageError, sendMessageWithRetry, sendMessageWithRetryChunked, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, resolveTurnVerbosity, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { EFFORT_OPTIONS, CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonInboundFrameV1, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, normalizeRuntimeCommandDescriptors, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, ControlChannelPoller, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ApprovalManager, RuntimeRequestManager, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, parseTurnVerbosityConfig, prepareConversationEnvironment, resolveCanonAgent, verifyResolvedAgentEnvironment, decideAutoReply, initRTDBAuth, isChunkedSendMessageError, sendMessageWithRetry, sendMessageWithRetryChunked, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, resolveLocalRuntimeSessionState, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCodingHostInboundPrompt, resolveConfiguredWorkspaceCwd, resolveTurnVerbosity, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { runCli } from '@canonmsg/core';
 import { CANON_VERB_MCP_SERVER_NAME, createCanonVerbMcpServer } from '@canonmsg/agent-tools';
 import { synthesizeClaudeApprovalDiff } from './approval-diff.js';
 import { decideClaudeToolPermissionForMode, parseAllowedNonOwnerClaudeTools, } from './tool-policy.js';
-import { applyClaudeSessionControl, boundClaudeFinalMetadata, buildClaudeFinalChunkingOptions, buildClaudeFinalMessageId, buildClaudeFinalTurnMetadata, buildClaudePendingFinalDelivery, buildClaudeTurnFailureNotice, buildTruncatedFinalText, buildUndeliverableFinalNotice, canDrainClaudeQueuedInput, beginClaudeAssistantResponse, claimClaudeTextSegmentId, claudeFinalWillChunk, classifyFinalDeliveryFailure, claudeInputOwnsTurnSlot, createClaudeTurnActivityState, decideClaudeControlSignalAction, decideClaudeInboundDispatch, dispatchClaudeInput, endClaudeAssistantResponse, isClaudeTurnSlotReserved, readClaudeFinalDeliveryResume, releaseClaudeTurnSlot, runClaudeExhaustedFinalDelivery, shouldApplyClaudeEchoedSessionState, shouldReleaseClaudeTurnSlot, isClaudeMainTurnMessage, openClaudeTurn, planClaudeAssistantTrail, planClaudeStreamingWrite, planClaudeToolCallStart, planClaudeToolProgress, planClaudeToolResults, claudeFinalTurnTrail, publishedClaudeTurnState, rememberDispatchedClaudeInput, resetClaudeTurnActivityState, shouldOpenClaudeTurnOnRunning, shouldStopTypingDotsOnStreamedText, isOpenClaudeTurnState, takeClaudeResultOwner, takeClaudeToolBlockIdByIndex, claudeModelInfoToOption, claudeOriginForCanonSender, composeClaudeTurnFinal, describeUndeliveredClaudeFinal, confirmClaudeInterrupt, createClaudeInputEnvelope, deriveClaudeSupplementalModelProbes, formatClaudeCliVersion, formatClaudeControlError, isClaudeCustomModelOption, isSupportedClaudeCliVersion, mergeClaudeDiscoveredModelOptions, parseClaudeCliVersion, resolveClaudeTurnResponseRouting, resolveClaudeModelOptions, resetClaudeCompletedTurnState, shouldDeliverClaudeFinal, shouldRouteClaudeTurnArtifacts, MINIMUM_CLAUDE_CLI_VERSION, } from './session-state.js';
+import { boundClaudeFinalMetadata, buildClaudeFinalChunkingOptions, buildClaudeFinalMessageId, buildClaudeFinalTurnMetadata, buildClaudePendingFinalDelivery, buildClaudeTurnFailureNotice, buildTruncatedFinalText, buildUndeliverableFinalNotice, canDrainClaudeQueuedInput, beginClaudeAssistantResponse, claimClaudeTextSegmentId, claudeFinalWillChunk, classifyFinalDeliveryFailure, claudeInputOwnsTurnSlot, createClaudeTurnActivityState, decideClaudeControlSignalAction, decideClaudeInboundDispatch, dispatchClaudeInput, endClaudeAssistantResponse, isClaudeTurnSlotReserved, readClaudeFinalDeliveryResume, releaseClaudeTurnSlot, runClaudeExhaustedFinalDelivery, shouldApplyClaudeEchoedSessionState, shouldReleaseClaudeTurnSlot, isClaudeMainTurnMessage, openClaudeTurn, planClaudeAssistantTrail, planClaudeStreamingWrite, planClaudeToolCallStart, planClaudeToolProgress, planClaudeToolResults, claudeFinalTurnTrail, publishedClaudeTurnState, rememberDispatchedClaudeInput, resetClaudeTurnActivityState, shouldOpenClaudeTurnOnRunning, shouldStopTypingDotsOnStreamedText, isOpenClaudeTurnState, takeClaudeResultOwner, takeClaudeToolBlockIdByIndex, claudeModelInfoToOption, claudeOriginForCanonSender, composeClaudeTurnFinal, describeUndeliveredClaudeFinal, confirmClaudeInterrupt, createClaudeInputEnvelope, deriveClaudeSupplementalModelProbes, formatClaudeCliVersion, formatClaudeControlError, isClaudeCustomModelOption, isSupportedClaudeCliVersion, mergeClaudeDiscoveredModelOptions, parseClaudeCliVersion, resolveClaudeTurnResponseRouting, resolveClaudeModelOptions, resetClaudeCompletedTurnState, shouldDeliverClaudeFinal, shouldRouteClaudeTurnArtifacts, MINIMUM_CLAUDE_CLI_VERSION, } from './session-state.js';
 import { CLAUDE_SUPPORTED_DIALOG_KINDS, buildClaudeAskUserPermissionDenied, buildClaudeAskUserPermissionResult, createClaudeUserDialogCoordinator, parseClaudeAskUserDialog, parseClaudeAskUserToolInput, resolveClaudeUserDialogRequestId, } from './user-dialog.js';
+import { isProactiveCommunicationEnabled } from './communication-policy.js';
 function parseRuntimeVisibilityPreset(value) {
     return value === 'normal' || value === 'minimal' || value === 'full' ? value : undefined;
 }
@@ -88,12 +89,10 @@ let workspaceRoots = [];
 let workspaceRootMetadata = [];
 let runtimeModels = [];
 const CLAUDE_METADATA_TTL_MS = 5 * 60 * 1000;
+const LOCAL_CONFIGURATION_REQUIRED_MESSAGE = 'This agent needs local runtime configuration before it can start this conversation. '
+    + 'Its operator must configure it and retry.';
 const allowedNonOwnerClaudeTools = parseAllowedNonOwnerClaudeTools(process.env.CANON_CLAUDE_NON_OWNER_ALLOWED_TOOLS);
-/**
- * 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;
 /**
  * `--turn-verbosity` beats `CANON_TURN_VERBOSITY`; `null` means "unset, use the
@@ -418,24 +417,8 @@ function toModelOptions(models) {
 async function publishAgentRuntime(agentId, runtime, rtdb) {
     await publishHostAgentRuntime(agentId, 'claude-code', runtime, rtdb);
 }
-async function loadSessionConfig(conversationId, agentId, rtdb) {
-    const config = await loadHostSessionConfig({
-        conversationId,
-        agentId,
-        rtdb,
-        extraStringFields: ['permissionMode', 'effort'],
-    });
-    return {
-        ...config,
-        permissionMode: config?.permissionMode
-            ? parseClaudePermissionMode(config.permissionMode) ?? undefined
-            : undefined,
-        effort: normalizeClaudeEffortLevel(config?.effort),
-        ultracode: parseClaudeUltracodeMode(config?.runtimeControlValues?.ultracode),
-    };
-}
-export function resolveSessionExecutionMode(config, defaultExecutionMode = 'worktree') {
-    return config?.executionMode ?? defaultExecutionMode;
+export function resolveSessionExecutionMode(defaultExecutionMode = 'worktree') {
+    return defaultExecutionMode;
 }
 function resolveConfiguredDefaultExecutionMode(value) {
     if (value == null || value === '')
@@ -444,10 +427,10 @@ function resolveConfiguredDefaultExecutionMode(value) {
         return value;
     throw new Error('--default-execution-mode must be worktree or locked');
 }
-function resolveWorkspaceCwd(config) {
-    return resolveHostWorkspaceCwd({
+function resolveWorkspaceCwd() {
+    return resolveConfiguredWorkspaceCwd({
         workspaceOptions,
-        config,
+        workspaceId: workspaceOptions[0]?.id,
         defaultCwd: workingDir,
     });
 }
@@ -990,7 +973,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                     const turnKey = session.activeInput?.turnKey;
                     if (turnKey)
                         session.silencedTurnKeys.add(turnKey);
-                }, { communication: config.communicationEnabled !== false }),
+                }, { communication: config.communicationEnabled === true }),
             },
         },
         ...(claudeCliPath ? { pathToClaudeCodeExecutable: claudeCliPath } : {}),
@@ -1456,6 +1439,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                         deliveryIntent: session.lastAcceptedIntent,
                         suppressAutoReply: input.suppressAutoReply,
                     }),
+                    ...(input.turn.replyAuthority ? { replyAuthority: input.turn.replyAuthority } : {}),
                 });
                 console.error(`[canon-host] [${conversationId.slice(0, 8)}] `
                     + (degraded.length === input.finalText.length
@@ -1523,6 +1507,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                 messageId: finalMessageId,
                 ...(selfContextId ? { selfContextId } : {}),
                 metadata,
+                ...(deliverTurn.replyAuthority ? { replyAuthority: deliverTurn.replyAuthority } : {}),
             }, {}, buildClaudeFinalChunkingOptions(resume));
             markFinalTurnDelivered(deliverTurn);
             console.error(`[canon-host] [${conversationId.slice(0, 8)}] Sent final reply (${finalText.length} chars`
@@ -1585,6 +1570,9 @@ function createSession(conversationId, environment, agentId, client, typingSigna
     }
     function sendTurnArtifactFile(file) {
         return sendMediaFileMessage(client, conversationId, file.path, '', {
+            ...(session.activeInput?.replyAuthority
+                ? { replyAuthority: session.activeInput.replyAuthority }
+                : {}),
             ...(session.activeSelfContextId ? { selfContextId: session.activeSelfContextId } : {}),
             metadata: buildArtifactMediaMetadata(),
         });
@@ -1663,51 +1651,8 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         }, FINAL_DELIVERY_RETRY_MS);
     }
     function writeState() {
-        const runtimeControlErrors = Object.keys(session.runtimeControlErrors).length > 0
-            ? session.runtimeControlErrors
-            : null;
-        const controlState = {};
-        const appliedAt = Date.now();
-        if (session.state.model !== undefined) {
-            controlState.model = { value: session.state.model, source: 'applied', appliedAt };
-        }
-        else if (config.model !== undefined) {
-            controlState.model = { value: config.model, source: 'requested' };
-        }
-        if (session.state.permissionMode !== undefined) {
-            controlState.permissionMode = { value: session.state.permissionMode, source: 'applied', appliedAt };
-        }
-        else if (config.permissionMode !== undefined) {
-            controlState.permissionMode = { value: config.permissionMode, source: 'requested' };
-        }
-        if (session.state.effort !== undefined) {
-            controlState.effort = { value: session.state.effort, source: 'applied', appliedAt };
-        }
-        else if (config.effort !== undefined) {
-            controlState.effort = { value: config.effort, source: 'requested' };
-        }
-        if (session.state.ultracode !== undefined) {
-            controlState.ultracode = { value: session.state.ultracode, source: 'applied', appliedAt };
-        }
-        else if (config.ultracode !== undefined) {
-            controlState.ultracode = { value: config.ultracode, source: 'requested' };
-        }
         runtimeState.writeSessionState(conversationId, {
-            model: session.state.model,
-            permissionMode: session.state.permissionMode,
-            effort: session.state.effort,
-            ...(session.state.ultracode ? { runtimeControlValues: { ultracode: session.state.ultracode } } : {}),
-            controlState,
-            runtimeControlErrors,
             contextUsage: session.state.contextUsage,
-            ...(session.availableModels.length ? { availableModels: session.availableModels } : {}),
-            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,
             isActive: true,
         }).catch(() => { });
@@ -2484,13 +2429,13 @@ export async function main() {
     let agentId;
     let ownerId = null;
     let ownerName = null;
-    let communicationEnabled = true;
+    let communicationEnabled = false;
     try {
         const ctx = await client.getAgentMe();
         agentId = ctx.agentId;
         ownerId = ctx.ownerId;
         ownerName = ctx.ownerName;
-        communicationEnabled = ctx.outboundPolicy !== 'closed';
+        communicationEnabled = isProactiveCommunicationEnabled(ctx.outboundPolicy);
         console.error(`[canon-host] Connected as ${ctx.displayName || agentId}`);
     }
     catch {
@@ -2580,25 +2525,6 @@ export async function main() {
             agentId,
             rtdb,
             clientType: 'claude-code',
-            runtime: runtimeDescriptor,
-            workspaceOptions,
-            defaultCwd: workingDir,
-            extraSessionConfigFields: ['permissionMode', 'effort'],
-            liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
-                const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
-                return [
-                    session.conversationId,
-                    {
-                        ...(session.state.model ? { model: session.state.model } : {}),
-                        ...(session.state.permissionMode ? { permissionMode: session.state.permissionMode } : {}),
-                        ...(session.state.effort ? { effort: session.state.effort } : {}),
-                        ...(session.state.ultracode ? { runtimeControlValues: { ultracode: session.state.ultracode } } : {}),
-                        ...(workspaceId ? { workspaceId } : {}),
-                        executionMode: session.environment.mode,
-                        executionBranch: session.environment.branch ?? null,
-                    },
-                ];
-            })),
         }).catch((error) => {
             console.error('[canon-host] Failed to publish session snapshots:', error);
         });
@@ -2742,8 +2668,8 @@ export async function main() {
     // input descriptor via `request()` (see the AskUserQuestion canUseTool branch).
     const runtimeInputManager = new RuntimeRequestManager(client, { agentId, ownerId: ownerId ?? '' });
     const pendingSessionCreations = new Map();
-    // Shared /control channel poller (claude host profile): session + signal
-    // keys, sequential conversations, active/idle cadence + jitter sampled at
+    // Shared /control channel poller (claude host profile): signal keys,
+    // sequential conversations, active/idle cadence + jitter sampled at
     // cycle start, eager baselines at session creation, and nodes left in place
     // when a handler throws (consumeOnError defaults to false for both keys).
     const controlPoller = new ControlChannelPoller({
@@ -2765,7 +2691,6 @@ export async function main() {
         pollOnStart: true,
         conversationConcurrency: 'sequential',
         handlers: {
-            session: { handle: applyRuntimeSessionControl },
             signal: { handle: handleRuntimeControlSignal },
         },
         onError: ({ scope, key, conversationId, error }) => {
@@ -3000,22 +2925,47 @@ export async function main() {
             evictOldestIdle();
         }
         const creation = (async () => {
-            const config = await loadSessionConfig(conversationId, agentId, rtdb);
-            const sessionExecutionMode = resolveSessionExecutionMode(config, defaultExecutionMode);
-            const workspaceCwd = resolveWorkspaceCwd(config);
-            const environment = prepareConversationEnvironment({
+            const sessionExecutionMode = resolveSessionExecutionMode(defaultExecutionMode);
+            const workspaceCwd = resolveWorkspaceCwd();
+            let environment = prepareConversationEnvironment({
                 agentId,
                 conversationId,
                 workspaceCwd,
                 allowWorktrees: sessionExecutionMode === 'worktree',
             });
             try {
-                const resumeKey = buildConversationEnvironmentKey(conversationId, environment.baseCwd);
-                const persisted = loadRuntimeSessionState(runtimeId, {
+                const persistedMapping = resolveLocalRuntimeSessionState(runtimeId, {
                     conversationId,
                     baseCwd: environment.baseCwd,
                     executionMode: environment.mode,
+                    resumeField: 'claudeSessionId',
+                    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-host] [${conversationId.slice(0, 8)}] Restoring saved local runtime → ${environment.mode} (${environment.baseCwd})`);
+                }
+                const resumeKey = buildConversationEnvironmentKey(conversationId, environment.baseCwd);
+                const persisted = persistedMapping.status === 'new'
+                    ? null
+                    : persistedMapping.state;
                 const resumeId = savedSessionIds.get(resumeKey) ?? persisted?.claudeSessionId;
                 const session = createSession(conversationId, environment, agentId, client, typingSignals, runtimeState, (convoId, sdkSessionId) => {
                     // Called when session processing loop ends — save session ID for resume
@@ -3056,10 +3006,10 @@ export async function main() {
                     runtimeDescriptor = descriptor;
                     void publishRuntimeHeartbeat();
                 }, {
-                    model: config?.model ?? runtimeModels[0]?.value,
-                    permissionMode: config?.permissionMode ?? 'default',
-                    effort: config?.effort,
-                    ultracode: config?.ultracode,
+                    model: runtimeModels[0]?.value,
+                    permissionMode: 'default',
+                    effort: undefined,
+                    ultracode: undefined,
                     availableModels: runtimeModels,
                     availableExecutionModes: hostAvailableExecutionModes,
                     defaultExecutionMode,
@@ -3078,6 +3028,10 @@ export async function main() {
                 }, resumeId);
                 sessions.set(conversationId, session);
                 await controlPoller.baseline([conversationId]);
+                await runtimeState.patchAgentSessionSnapshot(conversationId, {
+                    configurationStatus: 'ready',
+                    lastError: null,
+                });
                 return session;
             }
             catch (error) {
@@ -3163,13 +3117,17 @@ 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-host] [${input.conversationId.slice(0, 8)}] Failed to create recovered session: ${message}`);
+            await runtimeState.patchAgentSessionSnapshot(input.conversationId, {
+                configurationStatus: 'configuration_required',
+                lastError: LOCAL_CONFIGURATION_REQUIRED_MESSAGE,
+            }).catch(() => { });
             await markQueuedMessageAcceptedForConversation(input.conversationId, m.id ?? null, shouldMarkAccepted);
-            await sendMessageWithRetry(client, input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
+            await sendMessageWithRetry(client, input.conversationId, LOCAL_CONFIGURATION_REQUIRED_MESSAGE, {
                 messageId: `claude-start-failed-${m.id}`,
                 ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                 metadata: {
+                    runtimeStatus: 'configuration_required',
                     turnSemantics: 'turn_complete',
                     replyBehavior: 'suppress_auto_reply',
                 },
@@ -3426,16 +3384,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-host] [${convoId.slice(0, 8)}] Failed to create session: ${message}`);
+                        await runtimeState.patchAgentSessionSnapshot(convoId, {
+                            configurationStatus: 'configuration_required',
+                            lastError: LOCAL_CONFIGURATION_REQUIRED_MESSAGE,
+                        }).catch(() => { });
                         await markQueuedMessageAcceptedForConversation(convoId, m.id ?? null, shouldMarkAccepted);
-                        await sendMessageWithRetry(client, convoId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
+                        await sendMessageWithRetry(client, convoId, LOCAL_CONFIGURATION_REQUIRED_MESSAGE, {
                             messageId: `claude-start-failed-${m.id}`,
                             ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                             metadata: {
+                                turnId: `claude-start:${m.id}`,
+                                runtimeStatus: 'configuration_required',
                                 turnSemantics: 'turn_complete',
                                 replyBehavior: 'suppress_auto_reply',
                             },
+                            ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
                         }).catch(() => { });
                         return false;
                     }
@@ -3455,7 +3419,10 @@ export async function main() {
                         promptText,
                         materialized: [...replyMedia.materialized, ...materialized],
                     });
-                    const turnModes = resolveClaudeTurnModes(participantContext);
+                    const turnModes = {
+                        ...resolveClaudeTurnModes(participantContext),
+                        replyAuthority: payload.replyAuthority ?? null,
+                    };
                     session.enqueueInbound({
                         type: 'user',
                         message: {
@@ -3513,39 +3480,6 @@ export async function main() {
     stream.start().catch((err) => {
         console.error('[canon-host] SSE start error:', err instanceof Error ? err.message : err);
     });
-    // ── Control signal watcher ──
-    // Session control signals (model, mode, effort). A missing/closed session
-    // leaves the node in place; lastSeen still advances, so a stale control is
-    // never replayed once a session exists.
-    async function applyRuntimeSessionControl(event) {
-        const convoId = event.conversationId;
-        const session = sessions.get(convoId);
-        if (!session || session.closed)
-            return { consume: false };
-        const ctrl = event.control;
-        console.error(`[canon-host] [${convoId.slice(0, 8)}] Control:`, ctrl);
-        await applyClaudeSessionControl({
-            model: ctrl.model,
-            permissionMode: ctrl.permissionMode,
-            effort: ctrl.effort,
-            ultracode: ctrl.runtimeControlValues?.ultracode,
-        }, {
-            state: session.state,
-            parsePermissionMode: parseClaudePermissionMode,
-            normalizeEffort: normalizeClaudeEffortLevel,
-            parseUltracode: parseClaudeUltracodeMode,
-            setModel: (model) => session.query.setModel(model),
-            setPermissionMode: (mode) => session.query.setPermissionMode(mode),
-            applyEffort: (level) => applyClaudeEffortLevel(session.query, level),
-            applyUltracode: (enabled) => applyClaudeUltracode(session.query, enabled),
-            setRuntimeControlError: (controlId, value, error) => session.setRuntimeControlError(controlId, value, error),
-            clearRuntimeControlError: (controlId) => session.clearRuntimeControlError(controlId),
-            // Publish the app-subscribed snapshot immediately so the control-pending
-            // gate clears now instead of at the next 30s heartbeat (lag fix).
-            publishSnapshot: () => { void publishSessionSnapshots([convoId]); },
-        });
-        session.writeState();
-    }
     // Stop/new-session signals remain pending until the Claude SDK confirms the
     // interrupt. `defer` deliberately makes the poller revisit the same node.
     async function handleRuntimeControlSignal(event) {

package/dist/inbound-reply-authority.d.ts

@@ -0,0 +1,42 @@
+import type { AgentReplyAuthorityV1 } from '@canonmsg/backend-contracts';
+export interface InboundReplySource {
+    conversationId: string;
+    sourceMessageId: string;
+    replyAuthority?: AgentReplyAuthorityV1;
+}
+export interface PendingInboundReplySource extends InboundReplySource {
+    readonly generation: number;
+}
+export declare class InboundReplyAuthorityError extends Error {
+    constructor();
+}
+/**
+ * One-shot authority for Claude channel replies.
+ *
+ * Every inbound message first supersedes the previous source. The caller then
+ * activates that exact source only after deciding the message is a real Claude
+ * turn (rather than, for example, an approval response consumed locally).
+ */
+export declare class InboundReplyAuthority {
+    private readonly ttlMs;
+    private readonly now;
+    private generation;
+    private active;
+    constructor(ttlMs?: number, now?: () => number);
+    /** Supersede any prior authority before filtering the new inbound message. */
+    beginInbound(source: InboundReplySource): PendingInboundReplySource;
+    /** Activate a pending source only if no newer inbound has superseded it. */
+    authorize(source: PendingInboundReplySource): boolean;
+    /** Revoke an exact source without disturbing a newer inbound message. */
+    revoke(source: PendingInboundReplySource): void;
+    /** Validate a non-final in-turn action without consuming reply authority. */
+    validate(source: InboundReplySource): boolean;
+    /** Consume the current source when the model deliberately chooses silence. */
+    consumeNoReply(source: InboundReplySource): boolean;
+    /**
+     * Atomically claim one visible reply. A failed operation restores the claim
+     * only while the same inbound is still current and unexpired.
+     */
+    sendVisibleReply<T>(source: InboundReplySource, operation: (replyAuthority: AgentReplyAuthorityV1 | undefined) => Promise<T>): Promise<T>;
+    private getLiveActive;
+}

package/dist/inbound-reply-authority.js

@@ -0,0 +1,107 @@
+const DEFAULT_REPLY_AUTHORITY_TTL_MS = 15 * 60 * 1000;
+export class InboundReplyAuthorityError extends Error {
+    constructor() {
+        super('This reply is not authorized for the current inbound Canon message.');
+        this.name = 'InboundReplyAuthorityError';
+    }
+}
+function validSource(source) {
+    return source.conversationId.length > 0 && source.sourceMessageId.length > 0;
+}
+function sameSource(a, b) {
+    return a.conversationId === b.conversationId
+        && a.sourceMessageId === b.sourceMessageId;
+}
+/**
+ * One-shot authority for Claude channel replies.
+ *
+ * Every inbound message first supersedes the previous source. The caller then
+ * activates that exact source only after deciding the message is a real Claude
+ * turn (rather than, for example, an approval response consumed locally).
+ */
+export class InboundReplyAuthority {
+    ttlMs;
+    now;
+    generation = 0;
+    active = null;
+    constructor(ttlMs = DEFAULT_REPLY_AUTHORITY_TTL_MS, now = Date.now) {
+        this.ttlMs = ttlMs;
+        this.now = now;
+        if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+            throw new TypeError('Reply authority TTL must be positive.');
+        }
+    }
+    /** Supersede any prior authority before filtering the new inbound message. */
+    beginInbound(source) {
+        if (!validSource(source)) {
+            throw new TypeError('Inbound reply authority requires a conversation and source message.');
+        }
+        this.generation += 1;
+        this.active = null;
+        return { ...source, generation: this.generation };
+    }
+    /** Activate a pending source only if no newer inbound has superseded it. */
+    authorize(source) {
+        if (source.generation !== this.generation)
+            return false;
+        this.active = {
+            ...source,
+            expiresAt: this.now() + this.ttlMs,
+            claimed: false,
+        };
+        return true;
+    }
+    /** Revoke an exact source without disturbing a newer inbound message. */
+    revoke(source) {
+        if (this.active?.generation === source.generation && sameSource(this.active, source)) {
+            this.active = null;
+        }
+    }
+    /** Validate a non-final in-turn action without consuming reply authority. */
+    validate(source) {
+        const active = this.getLiveActive();
+        return active !== null && sameSource(active, source);
+    }
+    /** Consume the current source when the model deliberately chooses silence. */
+    consumeNoReply(source) {
+        const active = this.getLiveActive();
+        if (!active || active.claimed || !sameSource(active, source))
+            return false;
+        this.active = null;
+        return true;
+    }
+    /**
+     * Atomically claim one visible reply. A failed operation restores the claim
+     * only while the same inbound is still current and unexpired.
+     */
+    async sendVisibleReply(source, operation) {
+        const active = this.getLiveActive();
+        if (!active || active.claimed || !sameSource(active, source)) {
+            throw new InboundReplyAuthorityError();
+        }
+        active.claimed = true;
+        try {
+            const result = await operation(active.replyAuthority);
+            if (this.active === active)
+                this.active = null;
+            return result;
+        }
+        catch (error) {
+            if (this.active === active) {
+                if (this.now() < active.expiresAt) {
+                    active.claimed = false;
+                }
+                else {
+                    this.active = null;
+                }
+            }
+            throw error;
+        }
+    }
+    getLiveActive() {
+        if (this.active && this.now() >= this.active.expiresAt) {
+            this.active = null;
+        }
+        return this.active;
+    }
+}