@canonmsg/claude-code-plugin 0.12.4 → 0.12.5

package/dist/cli-entry.d.ts

@@ -1,2 +1,2 @@
-export declare function isDirectExecution(moduleUrl: string): boolean;
-export declare function runCli(moduleUrl: string, main: () => void | Promise<void>, onError: (error: unknown) => void): void;
+export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, runCli, } from '@canonmsg/core';
+export type { CliMetadata, RunCliMetadataOptions, } from '@canonmsg/core';

package/dist/cli-entry.js

@@ -1,26 +1 @@
-import { realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-export function isDirectExecution(moduleUrl) {
-    const entry = process.argv[1];
-    if (!entry)
-        return false;
-    const abs = resolve(entry);
-    let real = abs;
-    try {
-        real = realpathSync(abs);
-    }
-    catch {
-        // argv[1] may not exist on disk in rare harnesses; fall back to abs
-    }
-    return (pathToFileURL(real).href === moduleUrl ||
-        pathToFileURL(abs).href === moduleUrl);
-}
-export function runCli(moduleUrl, main, onError) {
-    if (!isDirectExecution(moduleUrl)) {
-        return;
-    }
-    Promise.resolve()
-        .then(() => main())
-        .catch(onError);
-}
+export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, runCli, } from '@canonmsg/core';

package/dist/host.js

@@ -30,6 +30,28 @@ import { CLAUDE_PERMISSION_MODE_OPTIONS, buildCanonHostPrompt, buildConfiguredWo
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { createStreamingBuffer } from './streaming-buffer.js';
 import { runCli } from './cli-entry.js';
+import { buildClaudeFinalMessageId, createClaudeInputEnvelope, formatClaudeControlError, mergeClaudeModelOptions, shouldDeliverClaudeFinal, } from './session-state.js';
+const HELP = `canon-claude — run a local Claude Code agent host for Canon
+
+USAGE
+  canon-claude [flags]
+
+COMMON FLAGS
+  --cwd <path>             Project directory to run Claude Code from
+  --workspace <path>       Additional project to expose in Canon
+  --workspace-root <path>  Discover projects under an approved root
+  --help, -h               Show this help
+  --version, -V            Show package version
+
+AUTH
+  CANON_AGENT=<profile> canon-claude --cwd /path/to/project
+  CANON_API_KEY=agk_live_... canon-claude --cwd /path/to/project
+
+EXAMPLES
+  canon-claude --cwd ~/dev/canon
+  canon-claude --cwd ~/dev/canon --workspace-root ~/dev
+
+Keep this terminal open while you want Canon to reach the agent.`;
 let workingDir = process.cwd();
 let workspaceOptions = [];
 let workspaceRoots = [];
@@ -465,12 +487,40 @@ const CLAUDE_RUNTIME_CAPABILITIES = {
     supportsNonFinalPermanentMessages: false,
 };
 function buildCanonPrompt(input) {
+    const { session, ...promptInput } = input;
     return buildCanonHostPrompt({
         hostLabel: 'Claude Code',
         buildInboundContextLines,
-        ...input,
+        sessionContextLines: session ? buildClaudeSessionContextLines(session) : undefined,
+        ...promptInput,
     });
 }
+function optionLabel(value, options) {
+    if (!value)
+        return null;
+    const label = options.find((option) => option.value === value)?.label ?? value;
+    return label === value ? value : `${label} (${value})`;
+}
+function buildClaudeSessionContextLines(session) {
+    const workspace = workspaceOptions.find((option) => option.cwd === session.environment.baseCwd);
+    const permissionMode = optionLabel(session.state.permissionMode, CLAUDE_PERMISSION_MODE_OPTIONS);
+    const effort = optionLabel(session.state.effort, [
+        { value: 'low', label: 'Low' },
+        { value: 'medium', label: 'Medium' },
+        { value: 'high', label: 'High' },
+    ]);
+    const model = optionLabel(session.state.model, session.availableModels);
+    return [
+        model ? `Selected model: ${model}` : null,
+        permissionMode ? `Permission mode: ${permissionMode}` : null,
+        effort ? `Thinking level: ${effort}` : null,
+        workspace ? `Project: ${workspace.label} (${workspace.id})` : null,
+        `Execution mode: ${session.environment.mode}`,
+        `Working directory: ${session.cwd}`,
+        session.environment.branch ? `Git branch: ${session.environment.branch}` : null,
+        session.environment.worktreePath ? `Worktree: ${session.environment.worktreePath}` : null,
+    ].filter((line) => Boolean(line));
+}
 function renderInboundContent(message, materialized) {
     return renderCanonHostInboundContent(message, materialized);
 }
@@ -501,19 +551,25 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
     let resolveInput = null;
     let inputDone = false;
     const messageQueue = [];
-    const sendInput = (msg) => {
+    const sendInput = (input) => {
         if (resolveInput) {
             const r = resolveInput;
             resolveInput = null;
-            r(msg);
+            r(input);
         }
         else {
             // Queue if iterator isn't waiting yet (e.g., during init)
-            messageQueue.push(msg);
+            messageQueue.push(input);
         }
     };
-    let enqueueInboundMessage = (msg, _intent = 'queue', _sourceMessageId, _markAccepted = false) => {
-        sendInput(msg);
+    let enqueueInboundMessage = (msg, intent = 'queue', sourceMessageId, markAccepted = false) => {
+        sendInput(createClaudeInputEnvelope({
+            kind: 'canon',
+            msg,
+            intent,
+            sourceMessageId,
+            markAccepted,
+        }));
     };
     const inputStream = {
         [Symbol.asyncIterator]() {
@@ -523,10 +579,15 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
                         return Promise.resolve({ done: true, value: undefined });
                     // Drain queued messages first (sent before iterator was ready)
                     if (messageQueue.length > 0) {
-                        return Promise.resolve({ done: false, value: messageQueue.shift() });
+                        const next = messageQueue.shift();
+                        session.activeInput = next;
+                        return Promise.resolve({ done: false, value: next.msg });
                     }
                     return new Promise((resolve) => {
-                        resolveInput = (msg) => resolve({ done: false, value: msg });
+                        resolveInput = (input) => {
+                            session.activeInput = input;
+                            resolve({ done: false, value: input.msg });
+                        };
                     });
                 },
                 return() {
@@ -669,6 +730,7 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         state: {
             model: config.model,
             permissionMode: config.permissionMode,
+            effort: config.effort,
             state: 'idle',
         },
         availableModels: config.availableModels,
@@ -678,8 +740,12 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         finalDeliveryTimer: null,
         seedResponseHandled: !!resumeSessionId, // Resumed sessions don't need seed handling
         pendingInputs: [],
+        activeInput: null,
+        finalizedTurnKeys: new Set(),
+        interruptedTurnKeys: new Set(),
         pendingFinalText: null,
-        pendingFinalDeliveryText: null,
+        pendingFinalDelivery: null,
+        runtimeControlErrors: {},
         toolInProgress: false,
         turnState: 'idle',
         currentTurnId: null,
@@ -690,6 +756,10 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         closed: false,
         sdkSessionId: resumeSessionId || null,
         pendingReply: null,
+        writeState: () => writeState(),
+        writeTurn: () => writeTurn(),
+        setRuntimeControlError: (controlId, value, error) => setRuntimeControlError(controlId, value, error),
+        clearRuntimeControlError: (controlId) => clearRuntimeControlError(controlId),
     };
     const streamingBuffer = createStreamingBuffer({
         throttleMs: STREAMING_THROTTLE_MS,
@@ -739,7 +809,8 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         session.currentTurnOpenedAt = null;
         session.lastAcceptedIntent = null;
         session.pendingFinalText = null;
-        session.pendingFinalDeliveryText = null;
+        session.pendingFinalDelivery = null;
+        session.activeInput = null;
         session.toolInProgress = false;
         session.turnState = 'idle';
         stopVisibleWorkSignal();
@@ -755,10 +826,18 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
             resetTurnToIdle();
         }, FINAL_MESSAGE_HANDOFF_MS);
     }
-    function markPendingFinalDelivery(finalText) {
+    function markPendingFinalDelivery(finalText, turn) {
         clearIdleResetTimer();
         session.pendingFinalText = finalText;
-        session.pendingFinalDeliveryText = finalText;
+        session.pendingFinalDelivery = {
+            turnKey: turn.turnKey,
+            text: finalText,
+            messageId: buildClaudeFinalMessageId({
+                agentId,
+                conversationId,
+                turnKey: turn.turnKey,
+            }),
+        };
         session.state.state = 'running';
         session.turnState = 'streaming';
         stopVisibleWorkSignal();
@@ -767,49 +846,75 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         writeTurn();
         client.setTyping(conversationId, true, 'typing').catch(() => { });
     }
-    async function deliverFinalReply(finalText) {
+    async function deliverFinalReply(finalText, turn = session.activeInput) {
+        if (!shouldDeliverClaudeFinal({
+            turn,
+            finalizedTurnKeys: session.finalizedTurnKeys,
+            interruptedTurnKeys: session.interruptedTurnKeys,
+        })) {
+            return true;
+        }
+        const deliverTurn = turn;
+        if (!deliverTurn)
+            return true;
+        const finalMessageId = buildClaudeFinalMessageId({
+            agentId,
+            conversationId,
+            turnKey: deliverTurn.turnKey,
+        });
         try {
             await client.sendMessage(conversationId, finalText, {
+                messageId: finalMessageId,
                 metadata: {
                     turnId: session.currentTurnId,
+                    turnKey: deliverTurn.turnKey,
+                    sourceMessageId: deliverTurn.sourceMessageId ?? undefined,
                     turnSemantics: 'turn_complete',
                     turnComplete: true,
                     deliveryIntent: session.lastAcceptedIntent ?? undefined,
                 },
             });
+            session.finalizedTurnKeys.add(deliverTurn.turnKey);
             session.state.state = 'idle';
-            session.pendingFinalDeliveryText = null;
+            session.pendingFinalDelivery = null;
             clearFinalDeliveryTimer();
             writeState();
             console.error(`[canon-host] [${conversationId.slice(0, 8)}] Sent final reply (${finalText.length} chars)`);
             return true;
         }
         catch (err) {
-            markPendingFinalDelivery(finalText);
+            markPendingFinalDelivery(finalText, deliverTurn);
             console.error(`[canon-host] [${conversationId.slice(0, 8)}] Failed to send final reply:`, err);
             return false;
         }
     }
-    function scheduleFinalDeliveryRetry(finalText) {
-        if (session.closed || session.pendingFinalDeliveryText !== finalText)
+    function scheduleFinalDeliveryRetry(pending = session.pendingFinalDelivery) {
+        if (!pending || session.closed || session.pendingFinalDelivery?.turnKey !== pending.turnKey)
             return;
         clearFinalDeliveryTimer();
         session.finalDeliveryTimer = setTimeout(() => {
             session.finalDeliveryTimer = null;
-            void deliverFinalReply(finalText).then((sent) => {
+            const retryTurn = session.activeInput?.turnKey === pending.turnKey
+                ? session.activeInput
+                : null;
+            void deliverFinalReply(pending.text, retryTurn).then((sent) => {
                 if (sent) {
                     scheduleFinalHandoffReset();
                     return;
                 }
-                scheduleFinalDeliveryRetry(finalText);
+                scheduleFinalDeliveryRetry();
             });
         }, FINAL_DELIVERY_RETRY_MS);
     }
     function writeState() {
+        const runtimeControlErrors = Object.keys(session.runtimeControlErrors).length > 0
+            ? session.runtimeControlErrors
+            : null;
         runtimeState.writeSessionState(conversationId, {
             model: session.state.model,
             permissionMode: session.state.permissionMode,
             effort: session.state.effort,
+            runtimeControlErrors,
             contextUsage: session.state.contextUsage,
             ...(session.availableModels.length ? { availableModels: session.availableModels } : {}),
             cwd,
@@ -823,6 +928,25 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
             isActive: true,
         }).catch(() => { });
     }
+    function setRuntimeControlError(controlId, value, error) {
+        session.runtimeControlErrors = {
+            ...session.runtimeControlErrors,
+            [controlId]: {
+                value,
+                message: formatClaudeControlError(error),
+                updatedAt: Date.now(),
+            },
+        };
+        writeState();
+    }
+    function clearRuntimeControlError(controlId) {
+        if (!(controlId in session.runtimeControlErrors))
+            return;
+        const next = { ...session.runtimeControlErrors };
+        delete next[controlId];
+        session.runtimeControlErrors = next;
+        writeState();
+    }
     function writeTurn() {
         runtimeState.writeTurnState(conversationId, {
             turnId: session.currentTurnId,
@@ -870,22 +994,32 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         session.lastAcceptedIntent = next.intent;
         writeTurn();
         void markQueuedMessageAccepted(next.sourceMessageId, next.markAccepted)
-            .finally(() => sendInput(next.msg));
+            .finally(() => sendInput(next));
     }
     enqueueInboundMessage = (msg, intent = 'queue', sourceMessageId = null, markAccepted = false) => {
         session.lastActivity = Date.now();
-        if (session.pendingFinalDeliveryText) {
-            session.pendingInputs.push({ msg, intent, sourceMessageId, markAccepted });
+        const input = createClaudeInputEnvelope({
+            kind: 'canon',
+            msg,
+            intent,
+            sourceMessageId,
+            markAccepted,
+        });
+        if (session.pendingFinalDelivery) {
+            session.pendingInputs.push(input);
             writeTurn();
             return;
         }
         if (session.state.state === 'running' && intent !== 'interrupt') {
-            session.pendingInputs.push({ msg, intent, sourceMessageId, markAccepted });
+            session.pendingInputs.push(input);
             writeTurn();
             return;
         }
         if (session.state.state === 'running' && intent === 'interrupt') {
-            session.pendingInputs.unshift({ msg, intent, sourceMessageId, markAccepted });
+            if (session.activeInput) {
+                session.interruptedTurnKeys.add(session.activeInput.turnKey);
+            }
+            session.pendingInputs.unshift(input);
             session.turnState = 'interrupted';
             stopVisibleWorkSignal();
             writeTurn();
@@ -895,7 +1029,7 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         session.lastAcceptedIntent = intent;
         writeTurn();
         void markQueuedMessageAccepted(sourceMessageId, markAccepted)
-            .finally(() => sendInput(msg));
+            .finally(() => sendInput(input));
     };
     writeTurn();
     // ── Process SDK output messages ──
@@ -991,12 +1125,22 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
                         const resultSessionId = msg.session_id;
                         if (resultSessionId)
                             session.sdkSessionId = resultSessionId;
+                        const completedInput = session.activeInput;
                         console.error(`[canon-host] [${conversationId.slice(0, 8)}] Turn complete (${msg.subtype})`);
                         const resultText = typeof msg.result === 'string'
                             ? msg.result.trim()
                             : '';
                         const finalText = resultText || session.pendingFinalText?.trim() || null;
-                        const finalDelivered = finalText ? await deliverFinalReply(finalText) : true;
+                        const shouldDeliverFinal = finalText
+                            ? shouldDeliverClaudeFinal({
+                                turn: completedInput,
+                                finalizedTurnKeys: session.finalizedTurnKeys,
+                                interruptedTurnKeys: session.interruptedTurnKeys,
+                            })
+                            : false;
+                        const finalDelivered = finalText && shouldDeliverFinal
+                            ? await deliverFinalReply(finalText, completedInput)
+                            : true;
                         try {
                             const usage = await q.getContextUsage();
                             session.state.contextUsage = {
@@ -1011,10 +1155,19 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
                             // Non-fatal
                         }
                         if (finalDelivered) {
-                            scheduleFinalHandoffReset();
+                            if (completedInput?.turnKey === session.activeInput?.turnKey) {
+                                session.activeInput = null;
+                            }
+                            session.pendingFinalText = null;
+                            if (shouldDeliverFinal && finalText) {
+                                scheduleFinalHandoffReset();
+                            }
+                            else {
+                                resetTurnToIdle();
+                            }
                         }
                         else if (finalText) {
-                            scheduleFinalDeliveryRetry(finalText);
+                            scheduleFinalDeliveryRetry();
                         }
                         break;
                     }
@@ -1056,19 +1209,26 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
         }
         if (!resumeSessionId) {
             // New session — send seed message to activate streaming input mode
-            sendInput({
-                type: 'user',
-                message: {
-                    role: 'user',
-                    content: 'You are connected to Canon messaging. Follow-up messages in this session come from Canon participants, and your text responses will be sent back to the conversation. You have full Claude Code capabilities (file read/write, bash, etc).',
+            sendInput(createClaudeInputEnvelope({
+                kind: 'seed',
+                msg: {
+                    type: 'user',
+                    message: {
+                        role: 'user',
+                        content: 'You are connected to Canon messaging. Follow-up messages in this session come from Canon participants, and your text responses will be sent back to the conversation. You have full Claude Code capabilities (file read/write, bash, etc).',
+                    },
+                    parent_tool_use_id: null,
                 },
-                parent_tool_use_id: null,
-            });
+            }));
         }
         // Refresh the canonical runtime descriptor after Claude reports supported models.
         try {
             const models = await q.supportedModels();
-            const modelList = toModelOptions(models);
+            const modelList = mergeClaudeModelOptions({
+                previous: runtimeModels,
+                next: toModelOptions(models),
+                selectedModel: session.state.model,
+            });
             session.availableModels = modelList;
             runtimeModels = modelList;
             onRuntimeDescriptorUpdate({
@@ -1085,21 +1245,7 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
                     executionModes: config.availableExecutionModes,
                 }),
             });
-            runtimeState.writeSessionState(conversationId, {
-                model: session.state.model,
-                permissionMode: session.state.permissionMode,
-                effort: session.state.effort,
-                contextUsage: session.state.contextUsage,
-                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(() => { });
+            writeState();
             console.error(`[canon-host] [${conversationId.slice(0, 8)}] Models: ${models.map((m) => m.displayName).join(', ')}`);
         }
         catch {
@@ -1513,7 +1659,10 @@ export async function main() {
                     availableExecutionModes: hostAvailableExecutionModes,
                 }, resumeId);
                 sessions.set(conversationId, session);
-                await baselineControlSignal(conversationId);
+                await Promise.all([
+                    baselineControlSignal(conversationId),
+                    baselineSessionControl(conversationId),
+                ]);
                 return session;
             }
             catch (error) {
@@ -1540,6 +1689,17 @@ export async function main() {
             lastSeenSignal.set(conversationId, timestamp);
         }
     }
+    async function baselineSessionControl(conversationId) {
+        if (lastSeenControl.has(conversationId))
+            return;
+        const raw = await rtdbRead(`/control/${conversationId}/${agentId}/session`).catch(() => null);
+        if (!raw || typeof raw !== 'object')
+            return;
+        const timestamp = Number(raw.updatedAt ?? 0);
+        if (timestamp > 0) {
+            lastSeenControl.set(conversationId, timestamp);
+        }
+    }
     async function enqueueRecoveredInboundMessage(input) {
         const m = input.message;
         if (m.senderId === agentId)
@@ -1599,6 +1759,7 @@ export async function main() {
             behavior,
             workSession: m.workSession,
             workSessions,
+            session,
         });
         const messageContent = await buildCanonUserContent({ promptText, materialized });
         session.enqueueInbound({
@@ -1747,6 +1908,7 @@ export async function main() {
                         behavior,
                         workSession: m.workSession,
                         workSessions,
+                        session,
                     });
                     const messageContent = await buildCanonUserContent({ promptText, materialized });
                     session.enqueueInbound({
@@ -1801,9 +1963,11 @@ export async function main() {
                                     try {
                                         await session.query.setModel(ctrl.model);
                                         session.state.model = ctrl.model;
+                                        session.clearRuntimeControlError('model');
                                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Model → ${ctrl.model}`);
                                     }
                                     catch (err) {
+                                        session.setRuntimeControlError('model', ctrl.model, err);
                                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set model:`, err);
                                     }
                                 }
@@ -1811,9 +1975,11 @@ export async function main() {
                                     try {
                                         await session.query.setPermissionMode(ctrl.permissionMode);
                                         session.state.permissionMode = ctrl.permissionMode;
+                                        session.clearRuntimeControlError('permissionMode');
                                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Mode → ${ctrl.permissionMode}`);
                                     }
                                     catch (err) {
+                                        session.setRuntimeControlError('permissionMode', ctrl.permissionMode, err);
                                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set mode:`, err);
                                     }
                                 }
@@ -1822,27 +1988,19 @@ export async function main() {
                                     try {
                                         await session.query.applyFlagSettings({ effortLevel: nextEffort });
                                         session.state.effort = nextEffort;
+                                        session.clearRuntimeControlError('effort');
                                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Effort → ${nextEffort}`);
                                     }
                                     catch (err) {
+                                        session.setRuntimeControlError('effort', nextEffort, err);
                                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set effort:`, err);
                                     }
                                 }
-                                runtimeState.writeSessionState(convoId, {
-                                    model: session.state.model,
-                                    permissionMode: session.state.permissionMode,
-                                    effort: session.state.effort,
-                                    contextUsage: session.state.contextUsage,
-                                    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,
-                                    isActive: true,
-                                }).catch(() => { });
+                                else if (ctrl.effort && !nextEffort) {
+                                    session.setRuntimeControlError('effort', String(ctrl.effort), new Error('Unsupported Claude thinking level.'));
+                                }
+                                session.writeState();
+                                await rtdbWrite(`/control/${convoId}/${agentId}/session`, null).catch(() => { });
                             }
                         }
                     }
@@ -1866,6 +2024,10 @@ export async function main() {
                                         const droppedInputs = session.pendingInputs.splice(0);
                                         await markSessionPendingInputsRejected(convoId, droppedInputs);
                                     }
+                                    if (session.activeInput) {
+                                        session.interruptedTurnKeys.add(session.activeInput.turnKey);
+                                    }
+                                    session.pendingFinalText = null;
                                     session.turnState = 'interrupted';
                                     runtimeState.writeTurnState(convoId, {
                                         turnId: session.currentTurnId,
@@ -1907,30 +2069,8 @@ export async function main() {
     // ── Heartbeat (per-session) ──
     const heartbeat = setInterval(() => {
         for (const session of sessions.values()) {
-            runtimeState.writeSessionState(session.conversationId, {
-                model: session.state.model,
-                permissionMode: session.state.permissionMode,
-                effort: session.state.effort,
-                contextUsage: session.state.contextUsage,
-                cwd: session.cwd,
-                executionMode: session.environment.mode,
-                ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
-                ...(session.environment.worktreePath ? { worktreePath: session.environment.worktreePath } : {}),
-                hostMode: true,
-                isActive: true,
-            }).catch(() => { });
-            runtimeState.writeTurnState(session.conversationId, {
-                turnId: session.currentTurnId,
-                state: session.turnState,
-                queueDepth: session.pendingInputs.length,
-                currentSpeakerId: agentId,
-                lastAcceptedIntent: session.lastAcceptedIntent,
-                capabilities: CLAUDE_RUNTIME_CAPABILITIES,
-                ...(session.currentTurnOpenedAt ? { openedAt: session.currentTurnOpenedAt } : {}),
-                ...(session.turnState === 'idle' || session.turnState === 'completed' || session.turnState === 'interrupted'
-                    ? { completedAt: { '.sv': 'timestamp' } }
-                    : {}),
-            }).catch(() => { });
+            session.writeState();
+            session.writeTurn();
         }
         void publishRuntimeHeartbeat();
     }, HEARTBEAT_MS);
@@ -1971,7 +2111,11 @@ export async function main() {
 }
 // ── Entry ───────────────────────────────────────────────────────────
 runCli(import.meta.url, main, (err) => {
-    console.error('[canon-host] Fatal error:', err);
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[canon-host] ${message}`);
     getActiveProfileLock()?.release();
     process.exit(1);
+}, {
+    name: 'canon-claude',
+    help: HELP,
 });

package/dist/register.js

@@ -13,6 +13,27 @@ import { ackRegistrationApproval, clearPendingRegistration, getOrCreatePendingRe
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { runCli } from './cli-entry.js';
+const HELP = `canon-register — register or reconnect a Claude Code agent in Canon
+
+USAGE
+  canon-register --name <name> --description <text> --phone <e164> [flags]
+
+REQUIRED
+  --name <name>              Agent display name shown in Canon
+  --description <text>       Short profile description
+  --phone <e164>             Owner phone number, for example +15551234567
+
+FLAGS
+  --profile <name>           Local profile name in ~/.canon/agents.json
+  --base-url <url>           Canon API base URL override
+  --help, -h                 Show this help
+  --version, -V              Show package version
+
+EXAMPLES
+  canon-register --name "My Claude" --description "Claude Code agent" --phone "+15551234567"
+  canon-register --name "Frontend" --description "React work" --phone "+15551234567" --profile frontend
+
+After approval, start it with CANON_AGENT=<profile> canon-claude --cwd /path/to/project.`;
 export async function main() {
     setDefaultResultOrder('ipv4first');
     const { values } = parseArgs({
@@ -102,4 +123,7 @@ export async function main() {
 runCli(import.meta.url, main, (error) => {
     console.error('[canon-register] Fatal error:', error);
     process.exit(1);
+}, {
+    name: 'canon-register',
+    help: HELP,
 });

package/dist/server.js

@@ -13,6 +13,17 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { CanonClient, CanonStream, ApprovalManager, buildLocalRuntimeId, getActiveProfileLock, markLocalRuntimeStopped, loadProfiles, isProfileLocked, resolveCanonAgent, getActiveProfile, releaseLock, upsertLocalRuntimeEntry, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
 import { ApprovalHttpServer } from './approval-server.js';
 import { runCli } from './cli-entry.js';
+const HELP = `canon-channel-server — Claude Code MCP channel server for Canon
+
+USAGE
+  canon-channel-server
+
+FLAGS
+  --help, -h       Show this help
+  --version, -V    Show package version
+
+This command is normally launched by Claude Code as an MCP stdio server. For
+phone-controlled local sessions, use canon-claude instead.`;
 // ── MCP server ─────────────────────────────────────────────────────────
 const server = new Server({ name: 'canon-channel', version: '0.1.0' }, {
     capabilities: {
@@ -672,4 +683,7 @@ export async function main() {
 runCli(import.meta.url, main, (err) => {
     console.error('[canon] Fatal error:', err);
     process.exit(1);
+}, {
+    name: 'canon-channel-server',
+    help: HELP,
 });

package/dist/session-state.d.ts

@@ -0,0 +1,44 @@
+import type { SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { DeliveryIntent, ModelOption } from '@canonmsg/core';
+export type ClaudeInputKind = 'seed' | 'canon';
+export interface ClaudeInputEnvelope {
+    kind: ClaudeInputKind;
+    msg: SDKUserMessage;
+    intent: DeliveryIntent;
+    sourceMessageId: string | null;
+    markAccepted: boolean;
+    turnKey: string;
+}
+export interface ClaudeRuntimeControlError {
+    value: string;
+    message: string;
+    updatedAt: number;
+}
+export interface ClaudePendingFinalDelivery {
+    turnKey: string;
+    text: string;
+    messageId: string;
+}
+export declare function createClaudeInputEnvelope(input: {
+    kind: ClaudeInputKind;
+    msg: SDKUserMessage;
+    intent?: DeliveryIntent;
+    sourceMessageId?: string | null;
+    markAccepted?: boolean;
+}): ClaudeInputEnvelope;
+export declare function buildClaudeFinalMessageId(input: {
+    agentId: string;
+    conversationId: string;
+    turnKey: string;
+}): string;
+export declare function shouldDeliverClaudeFinal(input: {
+    turn: ClaudeInputEnvelope | null;
+    finalizedTurnKeys: ReadonlySet<string>;
+    interruptedTurnKeys: ReadonlySet<string>;
+}): boolean;
+export declare function mergeClaudeModelOptions(input: {
+    previous: ReadonlyArray<ModelOption>;
+    next: ReadonlyArray<ModelOption>;
+    selectedModel?: string | null;
+}): ModelOption[];
+export declare function formatClaudeControlError(error: unknown): string;

package/dist/session-state.js

@@ -0,0 +1,67 @@
+import { createHash, randomUUID } from 'node:crypto';
+export function createClaudeInputEnvelope(input) {
+    const sourceMessageId = input.sourceMessageId ?? null;
+    const fallbackId = randomUUID();
+    return {
+        kind: input.kind,
+        msg: input.msg,
+        intent: input.intent ?? 'queue',
+        sourceMessageId,
+        markAccepted: Boolean(input.markAccepted),
+        turnKey: input.kind === 'canon' && sourceMessageId
+            ? `canon:${sourceMessageId}`
+            : `${input.kind}:${fallbackId}`,
+    };
+}
+export function buildClaudeFinalMessageId(input) {
+    const digest = createHash('sha256')
+        .update(`${input.agentId}\n${input.conversationId}\n${input.turnKey}`)
+        .digest('hex')
+        .slice(0, 32);
+    return `claude-final-${digest}`;
+}
+export function shouldDeliverClaudeFinal(input) {
+    if (!input.turn || input.turn.kind !== 'canon')
+        return false;
+    if (input.finalizedTurnKeys.has(input.turn.turnKey))
+        return false;
+    if (input.interruptedTurnKeys.has(input.turn.turnKey))
+        return false;
+    return true;
+}
+export function mergeClaudeModelOptions(input) {
+    const byValue = new Map();
+    for (const option of input.previous) {
+        byValue.set(option.value, { ...option });
+    }
+    for (const option of input.next) {
+        byValue.set(option.value, { ...option });
+    }
+    if (input.selectedModel && !byValue.has(input.selectedModel)) {
+        byValue.set(input.selectedModel, {
+            value: input.selectedModel,
+            label: input.selectedModel,
+            description: 'Selected for this Canon session but not returned by the latest Claude model probe.',
+        });
+    }
+    const nextValues = new Set(input.next.map((option) => option.value));
+    return [...byValue.values()].map((option) => {
+        if (nextValues.has(option.value))
+            return option;
+        return {
+            ...option,
+            description: option.description
+                ? `${option.description} Previously advertised; not returned by the latest Claude model probe.`
+                : 'Previously advertised; not returned by the latest Claude model probe.',
+        };
+    });
+}
+export function formatClaudeControlError(error) {
+    if (error instanceof Error && error.message.trim()) {
+        return error.message.trim();
+    }
+    if (typeof error === 'string' && error.trim()) {
+        return error.trim();
+    }
+    return 'Claude Code did not apply that control.';
+}

package/dist/setup.js

@@ -10,6 +10,17 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runCli } from './cli-entry.js';
+const HELP = `canon-setup — install Claude Code Canon skills and print MCP setup
+
+USAGE
+  canon-setup
+
+FLAGS
+  --help, -h       Show this help
+  --version, -V    Show package version
+
+This command writes Canon Claude Code skill files under ~/.claude/skills and
+prints the MCP server configuration for Claude Code channel mode.`;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const home = process.env.HOME || process.env.USERPROFILE || '';
 const skillsDir = join(home, '.claude', 'skills');
@@ -70,4 +81,7 @@ export function main() {
 runCli(import.meta.url, main, (error) => {
     console.error('[canon-setup] Fatal error:', error);
     process.exit(1);
+}, {
+    name: 'canon-setup',
+    help: HELP,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.101",
     "@canonmsg/agent-sdk": "^1.1.0",
-    "@canonmsg/core": "^0.15.0",
+    "@canonmsg/core": "^0.15.1",
     "@modelcontextprotocol/sdk": "^1.12.0"
   },
   "engines": {