@canonmsg/claude-code-plugin 0.27.3 → 0.28.1

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.27.3",
+  "version": "0.28.1",
   "channels": [
     {
       "server": "canon-channel",

package/README.md

@@ -4,7 +4,7 @@ Connect Claude Code to [Canon](https://github.com/HeyBobChan/canon) — a messag
 
 ## Quick start
 
-The package includes a compatible Claude Code runtime. If `claude` is installed on `PATH`, or selected with `CANON_CLAUDE_CLI_PATH`, use Claude Code 2.1.201 or newer.
+The package includes a compatible Claude Code runtime. If `claude` is installed on `PATH`, or selected with `CANON_CLAUDE_CLI_PATH`, use Claude Code 2.1.220 or newer — the model picker lists whatever the CLI reports, so an older binary hides newer model families. A `PATH` install below that minimum is skipped in favour of the bundled runtime; a `CANON_CLAUDE_CLI_PATH` below it is a hard error.
 
 ```bash
 # Install

package/dist/host.js

@@ -34,7 +34,7 @@ import { runCli } from './cli-entry.js';
 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, buildClaudeFinalMessageId, claudeModelInfoToOption, confirmClaudeInterrupt, createClaudeInputEnvelope, formatClaudeControlError, isClaudeCustomModelOption, mergeClaudeDiscoveredModelOptions, resolveClaudeTurnResponseRouting, resolveClaudeModelOptions, resetClaudeCompletedTurnState, shouldDeliverClaudeFinal, } from './session-state.js';
+import { applyClaudeSessionControl, buildClaudeFinalMessageId, buildClaudeFinalTurnMetadata, buildClaudeTurnFailureNotice, claudeInputOwnsTurnSlot, rememberDispatchedClaudeInput, takeClaudeResultOwner, claudeModelInfoToOption, claudeOriginForCanonSender, composeClaudeFinalText, describeUndeliveredClaudeFinal, confirmClaudeInterrupt, createClaudeInputEnvelope, deriveClaudeSupplementalModelProbes, formatClaudeCliVersion, formatClaudeControlError, isClaudeCustomModelOption, isSupportedClaudeCliVersion, mergeClaudeDiscoveredModelOptions, parseClaudeCliVersion, resolveClaudeTurnResponseRouting, resolveClaudeModelOptions, resetClaudeCompletedTurnState, shouldDeliverClaudeFinal, MINIMUM_CLAUDE_CLI_VERSION, } from './session-state.js';
 import { CLAUDE_SUPPORTED_DIALOG_KINDS, buildClaudeAskUserPermissionDenied, buildClaudeAskUserPermissionResult, createClaudeUserDialogCoordinator, parseClaudeAskUserDialog, parseClaudeAskUserToolInput, resolveClaudeUserDialogRequestId, } from './user-dialog.js';
 import { collectMissedInboundMessages, createReconnectRecoveryGate, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from './startup-recovery.js';
 function parseRuntimeVisibilityPreset(value) {
@@ -307,7 +307,8 @@ let cachedClaudeCliPath;
 // claude-agent-sdk-darwin-arm64. On some macOS setups that exact binary gets
 // SIGKILL'd at launch (path-based code-sign enforcement) even though a
 // byte-identical copy at ~/.local/bin/claude runs fine. Prefer whatever is on
-// PATH; fall back to the bundled one.
+// PATH; fall back to the bundled one — including when the PATH copy is older
+// than MINIMUM_CLAUDE_CLI_VERSION, since the bundle is always new enough.
 function resolveClaudeCliPath() {
     if (cachedClaudeCliPath !== undefined) {
         return cachedClaudeCliPath ?? undefined;
@@ -315,47 +316,62 @@ function resolveClaudeCliPath() {
     const override = process.env.CANON_CLAUDE_CLI_PATH?.trim();
     if (override) {
         if (existsSync(override)) {
-            assertExternalClaudeCliVersion(override);
-            cachedClaudeCliPath = override;
-            console.error(`[canon-host] claude CLI override: ${override}`);
-            return override;
+            return acceptClaudeCli('override', override);
         }
         console.error(`[canon-host] CANON_CLAUDE_CLI_PATH=${override} not found; ignoring`);
     }
+    let resolved;
     try {
-        const resolved = execFileSync('/bin/sh', ['-c', 'command -v claude'], {
+        const found = execFileSync('/bin/sh', ['-c', 'command -v claude'], {
             encoding: 'utf8',
         }).trim();
-        if (resolved && existsSync(resolved)) {
-            assertExternalClaudeCliVersion(resolved);
-            cachedClaudeCliPath = resolved;
-            console.error(`[canon-host] claude CLI on PATH: ${resolved}`);
-            return resolved;
+        if (found && existsSync(found)) {
+            resolved = found;
         }
     }
     catch {
         // `command -v` exits non-zero when claude isn't on PATH; fall through.
     }
-    cachedClaudeCliPath = null;
-    console.error('[canon-host] claude CLI not on PATH; using SDK-bundled binary');
-    return undefined;
+    if (!resolved) {
+        cachedClaudeCliPath = null;
+        console.error('[canon-host] claude CLI not on PATH; using SDK-bundled binary');
+        return undefined;
+    }
+    return acceptClaudeCli('on PATH', resolved);
 }
-function assertExternalClaudeCliVersion(cliPath) {
-    const output = execFileSync(cliPath, ['--version'], { encoding: 'utf8' }).trim();
-    const match = output.match(/^(\d+)\.(\d+)\.(\d+)/);
-    if (!match) {
-        throw new Error(`Could not determine Claude Code version from: ${output}`);
-    }
-    const installed = match.slice(1, 4).map(Number);
-    const minimum = [2, 1, 201];
-    const supported = installed.some((value, index) => {
-        if (value === minimum[index])
-            return false;
-        return value > minimum[index] && installed.slice(0, index).every((part, partIndex) => part === minimum[partIndex]);
-    }) || installed.every((value, index) => value === minimum[index]);
-    if (!supported) {
-        throw new Error(`Claude Code ${minimum.join('.')} or newer is required; found ${match[0]}.`);
+function readClaudeCliVersionSafely(cliPath) {
+    try {
+        const output = execFileSync(cliPath, ['--version'], { encoding: 'utf8' }).trim();
+        const version = parseClaudeCliVersion(output);
+        if (!version) {
+            console.error(`[canon-host] Could not determine Claude Code version from: ${output}`);
+        }
+        return version;
+    }
+    catch (error) {
+        console.error(`[canon-host] Could not run ${cliPath} --version:`, error);
+        return null;
+    }
+}
+/**
+ * Take a candidate CLI, or fall back to the SDK-bundled binary. Deliberately
+ * total: this is reached from the runtime heartbeat, so an unusable CLI must
+ * cost a few model options, never take the host down. A stale binary would
+ * otherwise shadow the newer bundled one and quietly shorten model discovery.
+ */
+function acceptClaudeCli(source, cliPath) {
+    const version = readClaudeCliVersionSafely(cliPath);
+    if (version && isSupportedClaudeCliVersion(version)) {
+        cachedClaudeCliPath = cliPath;
+        console.error(`[canon-host] claude CLI ${source}: ${cliPath} (${formatClaudeCliVersion(version)})`);
+        return cliPath;
     }
+    cachedClaudeCliPath = null;
+    console.error(`[canon-host] claude CLI ${source} (${cliPath}) `
+        + `${version ? `is ${formatClaudeCliVersion(version)}` : 'has an unreadable version'}; `
+        + `${formatClaudeCliVersion(MINIMUM_CLAUDE_CLI_VERSION)} or newer is required — `
+        + 'using the SDK-bundled binary instead. Run `claude update` to use your own install.');
+    return undefined;
 }
 function toModelOptions(models) {
     return models.map(claudeModelInfoToOption);
@@ -398,16 +414,13 @@ function resolveExecutionFallbackReason(environment) {
         ? null
         : environment.reason;
 }
-const CLAUDE_SUPPLEMENTAL_MODEL_PROBES = ['opus', 'fable'];
 async function detectRuntimeModels(cwd) {
-    const [discovered, supplemental] = await Promise.all([
-        detectRuntimeModelsForSelection(cwd, 'default'),
-        detectSupplementalRuntimeModels(cwd),
-    ]);
+    const discovered = await detectRuntimeModelsForSelection(cwd, 'default');
+    const supplemental = await detectSupplementalRuntimeModels(cwd, deriveClaudeSupplementalModelProbes(discovered));
     return mergeClaudeDiscoveredModelOptions(discovered, ...supplemental);
 }
-async function detectSupplementalRuntimeModels(cwd) {
-    return Promise.all(CLAUDE_SUPPLEMENTAL_MODEL_PROBES.map(async (model) => {
+async function detectSupplementalRuntimeModels(cwd, aliases) {
+    return Promise.all(aliases.map(async (model) => {
         try {
             const options = await detectRuntimeModelsForSelection(cwd, model);
             const option = options.find((entry) => entry.value === model);
@@ -769,6 +782,22 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             artifactRoutingMode,
         }));
     };
+    // Envelopes pulled by the SDK, keyed by the uuid stamped on each message, so a
+    // turn result can be matched to its own input. The SDK drains this iterable
+    // eagerly and may coalesce queued messages, so neither arrival order nor a
+    // single mutable slot can attribute results correctly on their own.
+    const dispatchedInputs = new Map();
+    // Only Canon turns may own the active-input slot. Result ownership comes from
+    // UUID correlation, while this slot drives live tool/dialog state.
+    function bindActiveInput(input) {
+        rememberDispatchedClaudeInput(dispatchedInputs, input);
+        // The slot drives in-turn concerns (tool routing, dialogs, interrupts), so
+        // it tracks the newest Canon turn. Result ownership is resolved by uuid, not
+        // from here.
+        if (!claudeInputOwnsTurnSlot(input))
+            return;
+        session.activeInput = input;
+    }
     const inputStream = {
         [Symbol.asyncIterator]() {
             return {
@@ -778,12 +807,12 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                     // Drain queued messages first (sent before iterator was ready)
                     if (messageQueue.length > 0) {
                         const next = messageQueue.shift();
-                        session.activeInput = next;
+                        bindActiveInput(next);
                         return Promise.resolve({ done: false, value: next.msg });
                     }
                     return new Promise((resolve) => {
                         resolveInput = (input) => {
-                            session.activeInput = input;
+                            bindActiveInput(input);
                             resolve({ done: false, value: input.msg });
                         };
                     });
@@ -1044,6 +1073,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                 approvalManager: config.approvalManager,
                 canRequestApproval: config.canRequestApproval,
                 allowedNonOwnerTools: allowedNonOwnerClaudeTools,
+                ruleForcedAsk: Boolean(options.matchedAskRule),
                 // File-change preview for Edit/Write-class approvals: canUseTool fires
                 // before the mutation lands, so read the pre-image from disk and splice
                 // the edit in memory. Best-effort — failure logs and omits the diff.
@@ -1088,7 +1118,6 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         streamingTimer: null,
         idleResetTimer: null,
         finalDeliveryTimer: null,
-        seedResponseHandled: !!resumeSessionId, // Resumed sessions don't need seed handling
         pendingInputs: [],
         activeInput: null,
         finalizedTurnKeys: new Set(),
@@ -1209,7 +1238,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             resetTurnToIdle();
         }, FINAL_MESSAGE_HANDOFF_MS);
     }
-    function markPendingFinalDelivery(finalText, turn) {
+    function markPendingFinalDelivery(finalText, turn, suppressAutoReply = false) {
         clearIdleResetTimer();
         const retryCount = session.pendingFinalDelivery?.turnKey === turn.turnKey
             ? session.pendingFinalDelivery.retryCount
@@ -1219,6 +1248,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             turnKey: turn.turnKey,
             text: finalText,
             retryCount,
+            ...(suppressAutoReply ? { suppressAutoReply: true } : {}),
             messageId: buildClaudeFinalMessageId({
                 agentId,
                 conversationId,
@@ -1233,7 +1263,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         writeTurn();
         typingSignals.start(conversationId, 'typing').catch(() => { });
     }
-    async function deliverFinalReply(finalText, turn = session.activeInput) {
+    async function deliverFinalReply(finalText, turn = session.activeInput, suppressAutoReply = false) {
         if (!shouldDeliverClaudeFinal({
             turn,
             finalizedTurnKeys: session.finalizedTurnKeys,
@@ -1255,16 +1285,14 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                 ...(session.activeSelfContextId
                     ? { selfContextId: session.activeSelfContextId }
                     : {}),
-                metadata: {
+                metadata: buildClaudeFinalTurnMetadata({
                     turnId: session.currentTurnId,
                     turnKey: deliverTurn.turnKey,
-                    sourceMessageId: deliverTurn.sourceMessageId ?? undefined,
-                    turnSemantics: 'turn_complete',
-                    deliveryIntent: session.lastAcceptedIntent ?? undefined,
-                    ...(getFinalTurnTrail().length > 0
-                        ? { turnTrail: getFinalTurnTrail() }
-                        : {}),
-                },
+                    sourceMessageId: deliverTurn.sourceMessageId,
+                    deliveryIntent: session.lastAcceptedIntent,
+                    turnTrail: getFinalTurnTrail(),
+                    suppressAutoReply,
+                }),
             });
             session.finalizedTurnKeys.add(deliverTurn.turnKey);
             markInputCompleted(deliverTurn);
@@ -1276,7 +1304,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             return true;
         }
         catch (err) {
-            markPendingFinalDelivery(finalText, deliverTurn);
+            markPendingFinalDelivery(finalText, deliverTurn, suppressAutoReply);
             console.error(`[canon-host] [${conversationId.slice(0, 8)}] Failed to send final reply:`, err);
             return false;
         }
@@ -1336,7 +1364,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             const retryTurn = session.activeInput?.turnKey === pending.turnKey
                 ? session.activeInput
                 : null;
-            void deliverFinalReply(pending.text, retryTurn).then((sent) => {
+            void deliverFinalReply(pending.text, retryTurn, pending.suppressAutoReply ?? false).then((sent) => {
                 if (sent) {
                     scheduleFinalHandoffReset();
                     return;
@@ -1549,10 +1577,13 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                         const assistantSessionId = msg.session_id;
                         if (assistantSessionId)
                             session.sdkSessionId = assistantSessionId;
-                        if (!session.seedResponseHandled) {
-                            session.seedResponseHandled = true;
+                        // Only a Canon turn's text is user-facing. This used to skip the
+                        // FIRST assistant message on the assumption it answered the seed,
+                        // but the seed is pulled after the first real message, so the guard
+                        // swallowed the actual reply — no streamed text and no fallback for
+                        // the final. Gate on the owning turn instead of on arrival order.
+                        if (!claudeInputOwnsTurnSlot(session.activeInput))
                             break;
-                        }
                         const textBlocks = (msg.message?.content ?? [])
                             .filter((b) => b.type === 'text')
                             .map((b) => b.text);
@@ -1641,7 +1672,10 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                         const resultSessionId = msg.session_id;
                         if (resultSessionId)
                             session.sdkSessionId = resultSessionId;
-                        const completedInput = session.activeInput;
+                        // Match the result to the envelope that produced it. Falling back to
+                        // the slot only when the SDK reports no uuid keeps older runtimes
+                        // working, at their existing accuracy.
+                        const completedInput = takeClaudeResultOwner(dispatchedInputs, msg.user_message_uuid) ?? session.activeInput;
                         console.error(`[canon-host] [${conversationId.slice(0, 8)}] Turn complete (${msg.subtype})`);
                         // Turn artifacts land before the final text reply.
                         if (completedInput?.kind === 'canon'
@@ -1651,7 +1685,22 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                         const resultText = typeof msg.result === 'string'
                             ? msg.result.trim()
                             : '';
-                        const finalText = resultText || session.pendingFinalText?.trim() || null;
+                        // Error results carry no `result` text — without a notice the
+                        // turn would end silently and the agent just goes idle in chat.
+                        const failureNotice = buildClaudeTurnFailureNotice({
+                            subtype: msg.subtype,
+                            errors: msg.errors,
+                        });
+                        if (failureNotice) {
+                            const errorList = Array.isArray(msg.errors) ? msg.errors : [];
+                            console.error(`[canon-host] [${conversationId.slice(0, 8)}] Turn failed (${msg.subtype}): `
+                                + (errorList.join(' | ') || 'no error detail'));
+                        }
+                        const finalText = composeClaudeFinalText({
+                            resultText,
+                            streamedText: session.pendingFinalText,
+                            failureNotice,
+                        });
                         const shouldDeliverFinal = finalText
                             ? shouldDeliverClaudeFinal({
                                 turn: completedInput,
@@ -1659,8 +1708,21 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                                 interruptedTurnKeys: session.interruptedTurnKeys,
                             })
                             : false;
+                        // Gated finals are dropped without sending. That is correct for the
+                        // seed's own turn, but it is also how a misattributed Canon reply
+                        // disappears — silently, which is why this class of bug went unseen.
+                        // Always say why.
+                        if (finalText && !shouldDeliverFinal) {
+                            console.error(`[canon-host] [${conversationId.slice(0, 8)}] `
+                                + `Final not delivered (${finalText.length} chars): `
+                                + describeUndeliveredClaudeFinal({
+                                    turn: completedInput,
+                                    finalizedTurnKeys: session.finalizedTurnKeys,
+                                    interruptedTurnKeys: session.interruptedTurnKeys,
+                                }));
+                        }
                         const finalDelivered = finalText && shouldDeliverFinal
-                            ? await deliverFinalReply(finalText, completedInput)
+                            ? await deliverFinalReply(finalText, completedInput, Boolean(failureNotice))
                             : true;
                         try {
                             const usage = await q.getContextUsage();
@@ -1687,6 +1749,10 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                                 scheduleFinalHandoffReset();
                             }
                             else {
+                                // Nothing durable is coming, so retire the live bubble here.
+                                // The delivering path does this after a handoff delay; without
+                                // it a gated turn leaves an orphaned /streaming node behind.
+                                clearStreaming().catch(() => { });
                                 resetTurnToIdle();
                             }
                         }
@@ -1740,26 +1806,13 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                 console.error(`[canon-host] [${conversationId.slice(0, 8)}] Failed to set initial ultracode:`, err);
             }
         }
-        if (!resumeSessionId) {
-            // New session — send seed message to activate streaming input mode
-            sendInput(createClaudeInputEnvelope({
-                kind: 'seed',
-                msg: {
-                    type: 'user',
-                    message: {
-                        role: 'user',
-                        content: 'You are assisting in an ongoing chat. Reply naturally to the latest participant.',
-                    },
-                    parent_tool_use_id: null,
-                },
-            }));
-        }
         // Refresh the canonical runtime descriptor after Claude reports supported models.
         try {
             const models = await q.supportedModels();
-            const supplemental = await detectSupplementalRuntimeModels(cwd);
+            const discoveredOptions = toModelOptions(models);
+            const supplemental = await detectSupplementalRuntimeModels(cwd, deriveClaudeSupplementalModelProbes(discoveredOptions));
             const modelList = resolveClaudeModelOptions({
-                discovered: mergeClaudeDiscoveredModelOptions(toModelOptions(models), ...supplemental),
+                discovered: mergeClaudeDiscoveredModelOptions(discoveredOptions, ...supplemental),
                 selectedModel: session.state.model,
             });
             session.availableModels = modelList;
@@ -2539,6 +2592,11 @@ export async function main() {
                 content: messageContent,
             },
             parent_tool_use_id: null,
+            origin: claudeOriginForCanonSender({
+                senderType: m.senderType,
+                senderId: m.senderId,
+                senderName: m.senderName,
+            }),
         }, deliveryIntent, m.id ?? null, shouldMarkAccepted, isOwner, m.senderType === 'human' ? m.senderId : null, artifactRoutingMode);
         return 'queued';
     }
@@ -2790,6 +2848,11 @@ export async function main() {
                             content: messageContent,
                         },
                         parent_tool_use_id: null,
+                        origin: claudeOriginForCanonSender({
+                            senderType: m.senderType,
+                            senderId: m.senderId,
+                            senderName: m.senderName,
+                        }),
                     }, deliveryIntent, m.id ?? null, shouldMarkAccepted, isOwner, m.senderType === 'human' ? m.senderId : null, artifactRoutingMode);
                     return true;
                 })().then((queued) => {

package/dist/session-state.d.ts

@@ -1,10 +1,12 @@
-import type { PermissionMode, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { PermissionMode, SDKMessageOrigin, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
 import type { DeliveryIntent, ModelOption, TurnLifecycleState } from '@canonmsg/core';
 import type { TurnArtifactSnapshot } from '@canonmsg/coding-agent-host';
 export type ClaudeInputKind = 'seed' | 'canon';
 export type ClaudeArtifactRoutingMode = 'workspace-generated' | 'disabled';
 export interface ClaudeInputEnvelope {
     kind: ClaudeInputKind;
+    /** Correlates this envelope with its turn result's `user_message_uuid`. */
+    messageUuid: string;
     msg: SDKUserMessage;
     intent: DeliveryIntent;
     sourceMessageId: string | null;
@@ -25,6 +27,8 @@ export interface ClaudePendingFinalDelivery {
     text: string;
     messageId: string;
     retryCount: number;
+    /** Carried so a retried failure notice keeps suppressing agent auto-replies. */
+    suppressAutoReply?: boolean;
 }
 export interface ClaudeCompletedTurnState {
     state: {
@@ -66,7 +70,71 @@ export declare function shouldDeliverClaudeFinal(input: {
     finalizedTurnKeys: ReadonlySet<string>;
     interruptedTurnKeys: ReadonlySet<string>;
 }): boolean;
+export declare function rememberDispatchedClaudeInput(dispatched: Map<string, ClaudeInputEnvelope>, input: ClaudeInputEnvelope): void;
+/**
+ * The envelope a turn result belongs to, matched by `user_message_uuid`.
+ *
+ * The SDK coalesces queued inputs — three rapid messages can produce two turns —
+ * and reports the LAST message of a coalesced batch, which is the correct owner
+ * of the reply. Entries up to and including the match are consumed, so messages
+ * folded into that batch do not linger. Returns null when the result carries no
+ * usable uuid, leaving the caller to fall back.
+ */
+export declare function takeClaudeResultOwner(dispatched: Map<string, ClaudeInputEnvelope>, userMessageUuid: unknown): ClaudeInputEnvelope | null;
+/**
+ * Whether an envelope owns the session's active-turn slot. Only Canon turns do;
+ * any future internal envelope must remain invisible to user-facing turn state.
+ */
+export declare function claudeInputOwnsTurnSlot(input: Pick<ClaudeInputEnvelope, 'kind'> | null | undefined): boolean;
+/** Why a non-empty final was gated instead of sent. Diagnostics only. */
+export declare function describeUndeliveredClaudeFinal(input: {
+    turn: ClaudeInputEnvelope | null;
+    finalizedTurnKeys: ReadonlySet<string>;
+    interruptedTurnKeys: ReadonlySet<string>;
+}): string;
 export declare function resetClaudeCompletedTurnState(session: ClaudeCompletedTurnState): void;
+export declare function claudeOriginForCanonSender(input: {
+    senderType?: string | null;
+    senderId: string;
+    senderName?: string | null;
+}): SDKMessageOrigin;
+/**
+ * Metadata for a completed-turn message. `suppressAutoReply` is set for turns
+ * that ended in failure: a failure notice is not a handoff, so it must not
+ * trigger a peer agent's auto-reply and start an error-response exchange.
+ */
+export declare function buildClaudeFinalTurnMetadata(input: {
+    turnId?: string | null;
+    turnKey: string;
+    sourceMessageId?: string | null;
+    deliveryIntent?: DeliveryIntent | null;
+    turnTrail?: ReadonlyArray<unknown>;
+    suppressAutoReply?: boolean;
+}): Record<string, unknown>;
+/**
+ * A chat-deliverable notice for a turn that ended on an SDK error result.
+ * Without it the agent goes from working to idle with no message at all —
+ * the error subtypes carry no `result` text, and `errors` was never read.
+ * Returns null for success results.
+ */
+export declare function buildClaudeTurnFailureNotice(input: {
+    subtype: unknown;
+    errors?: unknown;
+}): string | null;
+/**
+ * Final chat text for a completed turn. Success keeps today's behaviour
+ * (result text, else the streamed text). A failure notice is appended to any
+ * partial output — partial text alone would read as a successful reply.
+ */
+export declare function composeClaudeFinalText(input: {
+    resultText?: string | null;
+    streamedText?: string | null;
+    failureNotice?: string | null;
+}): string | null;
+export declare const MINIMUM_CLAUDE_CLI_VERSION: readonly number[];
+export declare function parseClaudeCliVersion(output: string): number[] | null;
+export declare function formatClaudeCliVersion(version: readonly number[]): string;
+export declare function isSupportedClaudeCliVersion(installed: readonly number[], minimum?: readonly number[]): boolean;
 export interface ClaudeModelInfoLike {
     value: string;
     displayName: string;
@@ -74,6 +142,14 @@ export interface ClaudeModelInfoLike {
 }
 export declare function claudeModelInfoToOption(model: ClaudeModelInfoLike): ModelOption;
 export declare function isClaudeCustomModelOption(option: ModelOption | null | undefined): boolean;
+/**
+ * Bare model aliases worth probing beyond what default discovery lists.
+ * Discovery decorates values (`opus[1m]`, `claude-fable-5[1m]`) while the
+ * plain alias (`opus`, `fable`) is selectable but unlisted; deriving the
+ * aliases from the discovered set keeps the picker discovery-driven instead
+ * of needing a code change every time a model family ships.
+ */
+export declare function deriveClaudeSupplementalModelProbes(discovered: ReadonlyArray<ModelOption>): string[];
 export declare function mergeClaudeDiscoveredModelOptions(...groups: ReadonlyArray<ReadonlyArray<ModelOption>>): ModelOption[];
 export declare function resolveClaudeModelOptions(input: {
     discovered: ReadonlyArray<ModelOption>;
@@ -82,7 +158,7 @@ export declare function resolveClaudeModelOptions(input: {
 export declare function formatClaudeControlError(error: unknown): string;
 export declare function confirmClaudeInterrupt(input: {
     active: boolean;
-    interrupt: () => Promise<void>;
+    interrupt: () => Promise<unknown>;
 }): Promise<'confirmed' | 'defer'>;
 /** Requested session-control values from the control plane (raw, pre-validation). */
 export interface ClaudeSessionControlInput {

package/dist/session-state.js

@@ -1,10 +1,16 @@
 import { createHash, randomUUID } from 'node:crypto';
+import { USAGE_LIMIT_ERROR_PREFIXES } from '@anthropic-ai/claude-agent-sdk';
 export function createClaudeInputEnvelope(input) {
     const sourceMessageId = input.sourceMessageId ?? null;
     const fallbackId = randomUUID();
+    // Stamped so each turn result can be matched back to the envelope that caused
+    // it via SDKResultMessage.user_message_uuid, instead of inferring ownership
+    // from a mutable slot and arrival order.
+    const messageUuid = randomUUID();
     return {
         kind: input.kind,
-        msg: input.msg,
+        messageUuid,
+        msg: { ...input.msg, uuid: messageUuid },
         intent: input.intent ?? 'queue',
         sourceMessageId,
         markAccepted: Boolean(input.markAccepted),
@@ -48,6 +54,59 @@ export function shouldDeliverClaudeFinal(input) {
         return false;
     return true;
 }
+/** Bounds the correlation map if the SDK ever stops reporting a uuid we sent. */
+const MAX_TRACKED_DISPATCHED_INPUTS = 64;
+export function rememberDispatchedClaudeInput(dispatched, input) {
+    dispatched.set(input.messageUuid, input);
+    while (dispatched.size > MAX_TRACKED_DISPATCHED_INPUTS) {
+        const oldest = dispatched.keys().next();
+        if (oldest.done)
+            break;
+        dispatched.delete(oldest.value);
+    }
+}
+/**
+ * The envelope a turn result belongs to, matched by `user_message_uuid`.
+ *
+ * The SDK coalesces queued inputs — three rapid messages can produce two turns —
+ * and reports the LAST message of a coalesced batch, which is the correct owner
+ * of the reply. Entries up to and including the match are consumed, so messages
+ * folded into that batch do not linger. Returns null when the result carries no
+ * usable uuid, leaving the caller to fall back.
+ */
+export function takeClaudeResultOwner(dispatched, userMessageUuid) {
+    if (typeof userMessageUuid !== 'string' || !dispatched.has(userMessageUuid)) {
+        return null;
+    }
+    let owner = null;
+    for (const [key, envelope] of dispatched) {
+        dispatched.delete(key);
+        if (key === userMessageUuid) {
+            owner = envelope;
+            break;
+        }
+    }
+    return owner;
+}
+/**
+ * Whether an envelope owns the session's active-turn slot. Only Canon turns do;
+ * any future internal envelope must remain invisible to user-facing turn state.
+ */
+export function claudeInputOwnsTurnSlot(input) {
+    return input?.kind === 'canon';
+}
+/** Why a non-empty final was gated instead of sent. Diagnostics only. */
+export function describeUndeliveredClaudeFinal(input) {
+    if (!input.turn)
+        return 'no Canon turn owns this result';
+    if (input.turn.kind !== 'canon')
+        return `owning turn is '${input.turn.kind}'`;
+    if (input.interruptedTurnKeys.has(input.turn.turnKey))
+        return 'turn was interrupted';
+    if (input.finalizedTurnKeys.has(input.turn.turnKey))
+        return 'turn was already finalized';
+    return 'turn did not qualify for delivery';
+}
 export function resetClaudeCompletedTurnState(session) {
     session.state.state = 'idle';
     session.currentTurnId = null;
@@ -60,6 +119,110 @@ export function resetClaudeCompletedTurnState(session) {
     session.toolInProgress = false;
     session.turnState = 'idle';
 }
+// Provenance for a Canon message entering the SDK. From 0.3.220 an absent
+// `origin` is "unattributed" and fails closed at strict isHuman() gates, so a
+// human sender must be stamped explicitly rather than left to default. Agent
+// senders keep their identity as peers instead of being laundered into humans.
+export function claudeOriginForCanonSender(input) {
+    if (input.senderType === 'human')
+        return { kind: 'human' };
+    const name = input.senderName?.trim();
+    return { kind: 'peer', from: input.senderId, ...(name ? { name } : {}) };
+}
+/**
+ * Metadata for a completed-turn message. `suppressAutoReply` is set for turns
+ * that ended in failure: a failure notice is not a handoff, so it must not
+ * trigger a peer agent's auto-reply and start an error-response exchange.
+ */
+export function buildClaudeFinalTurnMetadata(input) {
+    return {
+        turnId: input.turnId ?? null,
+        turnKey: input.turnKey,
+        sourceMessageId: input.sourceMessageId ?? undefined,
+        turnSemantics: 'turn_complete',
+        ...(input.suppressAutoReply ? { replyBehavior: 'suppress_auto_reply' } : {}),
+        deliveryIntent: input.deliveryIntent ?? undefined,
+        ...(input.turnTrail && input.turnTrail.length > 0 ? { turnTrail: input.turnTrail } : {}),
+    };
+}
+const CLAUDE_FAILURE_DETAIL_MAX_CHARS = 280;
+function claudeFailureDetail(errors) {
+    if (!Array.isArray(errors))
+        return null;
+    const first = errors.find((entry) => typeof entry === 'string' && entry.trim());
+    if (typeof first !== 'string')
+        return null;
+    const trimmed = first.trim();
+    return trimmed.length > CLAUDE_FAILURE_DETAIL_MAX_CHARS
+        ? `${trimmed.slice(0, CLAUDE_FAILURE_DETAIL_MAX_CHARS - 1)}…`
+        : trimmed;
+}
+function claudeUsageLimitDetail(errors) {
+    if (!Array.isArray(errors))
+        return null;
+    const match = errors.find((entry) => typeof entry === 'string'
+        && USAGE_LIMIT_ERROR_PREFIXES.some((prefix) => entry.startsWith(prefix)));
+    return typeof match === 'string' ? claudeFailureDetail([match]) : null;
+}
+/**
+ * A chat-deliverable notice for a turn that ended on an SDK error result.
+ * Without it the agent goes from working to idle with no message at all —
+ * the error subtypes carry no `result` text, and `errors` was never read.
+ * Returns null for success results.
+ */
+export function buildClaudeTurnFailureNotice(input) {
+    if (typeof input.subtype !== 'string' || !input.subtype.startsWith('error')) {
+        return null;
+    }
+    const usageLimit = claudeUsageLimitDetail(input.errors);
+    if (usageLimit) {
+        return `I've hit a usage limit, so this turn didn't finish: ${usageLimit}`;
+    }
+    switch (input.subtype) {
+        case 'error_max_turns':
+            return 'I stopped this turn after reaching its maximum number of turns. Send a follow-up message to continue.';
+        case 'error_max_budget_usd':
+            return 'I stopped this turn after reaching its spending budget.';
+        default: {
+            const detail = claudeFailureDetail(input.errors);
+            return detail
+                ? `This turn failed before I could reply: ${detail}`
+                : 'This turn failed before I could reply.';
+        }
+    }
+}
+/**
+ * Final chat text for a completed turn. Success keeps today's behaviour
+ * (result text, else the streamed text). A failure notice is appended to any
+ * partial output — partial text alone would read as a successful reply.
+ */
+export function composeClaudeFinalText(input) {
+    const primary = input.resultText?.trim() || input.streamedText?.trim() || null;
+    if (!input.failureNotice)
+        return primary;
+    return primary ? `${primary}\n\n${input.failureNotice}` : input.failureNotice;
+}
+// Model options are discovery-driven: the host publishes whatever the Claude
+// Code CLI it spawns reports. A CLI older than this predates whole model
+// families (2.1.220 is the first to know Opus 5), so an old binary silently
+// shortens the picker instead of failing. Keep this at or above the CLI the
+// pinned SDK bundles, so the bundled fallback always satisfies it.
+export const MINIMUM_CLAUDE_CLI_VERSION = [2, 1, 220];
+export function parseClaudeCliVersion(output) {
+    const match = output.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+    return match ? match.slice(1, 4).map(Number) : null;
+}
+export function formatClaudeCliVersion(version) {
+    return version.join('.');
+}
+export function isSupportedClaudeCliVersion(installed, minimum = MINIMUM_CLAUDE_CLI_VERSION) {
+    for (let index = 0; index < minimum.length; index += 1) {
+        const part = installed[index] ?? 0;
+        if (part !== minimum[index])
+            return part > minimum[index];
+    }
+    return true;
+}
 function normalizeModelDescription(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
@@ -87,6 +250,31 @@ export function claudeModelInfoToOption(model) {
 export function isClaudeCustomModelOption(option) {
     return option?.description?.trim().toLowerCase() === 'custom model';
 }
+const CLAUDE_LONG_CONTEXT_SUFFIX = /\[1m\]$/;
+const CLAUDE_FULL_MODEL_ID_FAMILY = /^claude-([a-z]+)-\d/;
+/**
+ * Bare model aliases worth probing beyond what default discovery lists.
+ * Discovery decorates values (`opus[1m]`, `claude-fable-5[1m]`) while the
+ * plain alias (`opus`, `fable`) is selectable but unlisted; deriving the
+ * aliases from the discovered set keeps the picker discovery-driven instead
+ * of needing a code change every time a model family ships.
+ */
+export function deriveClaudeSupplementalModelProbes(discovered) {
+    const values = new Set(discovered.map((option) => option.value));
+    const aliases = new Set();
+    for (const option of discovered) {
+        if (option.value === 'default')
+            continue;
+        const base = option.value.replace(CLAUDE_LONG_CONTEXT_SUFFIX, '');
+        const alias = CLAUDE_FULL_MODEL_ID_FAMILY.exec(base)?.[1] ?? base;
+        if (!/^[a-z]+$/.test(alias))
+            continue;
+        if (alias === option.value || values.has(alias))
+            continue;
+        aliases.add(alias);
+    }
+    return [...aliases];
+}
 export function mergeClaudeDiscoveredModelOptions(...groups) {
     const byValue = new Map();
     const valueByLabel = new Map();
@@ -132,6 +320,8 @@ export function formatClaudeControlError(error) {
     }
     return 'Claude Code did not apply that control.';
 }
+// `Query.interrupt()` resolves to a receipt of what survived the interrupt
+// (SDK 0.3.220+). Only settlement matters here, so accept any resolved value.
 export async function confirmClaudeInterrupt(input) {
     if (!input.active)
         return 'confirmed';

package/dist/tool-policy.d.ts

@@ -32,6 +32,12 @@ export declare function decideClaudeToolPermissionForMode(input: {
     approvalManager?: ApprovalManager | null;
     canRequestApproval?: () => Promise<boolean>;
     allowedNonOwnerTools?: Iterable<string>;
+    /**
+     * A user-configured `permissions.ask` rule forced this prompt (the SDK's
+     * `matchedAskRule`). The user asked to be consulted about this tool, which
+     * outranks the mode's host-side auto-approval.
+     */
+    ruleForcedAsk?: boolean;
     /**
      * Lazy file-change preview for the approval card (Edit/Write-class tools).
      * Invoked only once the call is headed for a responder approval; best-effort —

package/dist/tool-policy.js

@@ -2,6 +2,7 @@ const NON_OWNER_DENY_MESSAGE = 'Only the agent owner can authorize runtime tool
 const NON_OWNER_CROSS_CONVERSATION_DENY_MESSAGE = 'Non-owner turns may only target the conversation they came from.';
 const NATIVE_APPROVAL_UNAVAILABLE_MESSAGE = 'Runtime action approval is not available for this conversation.';
 const NATIVE_APPROVAL_DENIED_MESSAGE = 'The user denied this action.';
+const RULE_FORCED_INTERACTION_DENY_MESSAGE = 'A Claude permissions.ask rule cannot gate Canon interaction tools because they are already the human interaction surface. Remove or narrow the matching ask rule.';
 export const CLAUDE_NATIVE_APPROVAL_PERMISSION_MODE = 'default';
 const SENSITIVE_CLAUDE_TOOLS = new Set([
     'agent',
@@ -63,6 +64,14 @@ const CANON_HITL_OR_READ_VERBS = new Set([
     'list_contact_requests',
     'list_conversations',
 ]);
+// Asking permission to create or poll an interaction would put the interaction
+// behind another interaction and can recurse indefinitely. Fail closed instead.
+const CANON_INTERACTION_LIFECYCLE_VERBS = new Set([
+    'request_input',
+    'request_approval',
+    'check_approval',
+    'request_card',
+]);
 /**
  * Verbs a NON-owner conversation member may trigger: same-conversation HITL
  * and display surfaces, whose responder routing and owner-only escalation
@@ -205,8 +214,13 @@ export function buildClaudeApprovalDetails(toolName, toolInput) {
     return details;
 }
 export async function decideClaudeToolPermissionForMode(input) {
+    let effectiveToolInput = input.toolInput;
+    let canonFastLaneAllowed = false;
     const canonVerb = canonVerbFromToolName(input.toolName);
     if (canonVerb) {
+        if (input.ruleForcedAsk && CANON_INTERACTION_LIFECYCLE_VERBS.has(canonVerb)) {
+            return { behavior: 'deny', message: RULE_FORCED_INTERACTION_DENY_MESSAGE };
+        }
         // Non-owner turns: same-conversation HITL/display verbs are allowed
         // (members may instruct the agent; the server enforces responder
         // membership and owner-only escalation); everything cross-conversation
@@ -222,28 +236,42 @@ export async function decideClaudeToolPermissionForMode(input) {
                 if (typeof target === 'string' && target !== input.conversationId) {
                     return { behavior: 'deny', message: NON_OWNER_CROSS_CONVERSATION_DENY_MESSAGE };
                 }
-                return {
-                    behavior: 'allow',
-                    updatedInput: { ...input.toolInput, conversationId: input.conversationId },
-                };
+                effectiveToolInput = { ...input.toolInput, conversationId: input.conversationId };
+                canonFastLaneAllowed = true;
+                if (!input.ruleForcedAsk) {
+                    return {
+                        behavior: 'allow',
+                        updatedInput: effectiveToolInput,
+                    };
+                }
+            }
+            else {
+                return { behavior: 'deny', message: NON_OWNER_DENY_MESSAGE };
             }
-            return { behavior: 'deny', message: NON_OWNER_DENY_MESSAGE };
         }
         // HITL + read verbs are allowed without an approval card: the HITL verbs
         // themselves render the human-facing card (recursion otherwise), and the
         // reads are side-effect free. Outbound verbs (send_to, share_contact)
         // fall through to the mode policy — in native-approval mode they gate
         // like any other side effect; in default mode owner turns allow.
-        if (CANON_HITL_OR_READ_VERBS.has(canonVerb)) {
+        if (CANON_HITL_OR_READ_VERBS.has(canonVerb) && !input.ruleForcedAsk) {
             return { behavior: 'allow' };
         }
+        canonFastLaneAllowed = CANON_HITL_OR_READ_VERBS.has(canonVerb);
     }
     if (input.permissionMode !== CLAUDE_NATIVE_APPROVAL_PERMISSION_MODE) {
-        return decideClaudeToolPermission({
-            toolName: input.toolName,
-            isOwnerTurn: input.isOwnerTurn,
-            allowedNonOwnerTools: input.allowedNonOwnerTools,
-        });
+        const modeDecision = canonFastLaneAllowed
+            ? { behavior: 'allow' }
+            : decideClaudeToolPermission({
+                toolName: input.toolName,
+                isOwnerTurn: input.isOwnerTurn,
+                allowedNonOwnerTools: input.allowedNonOwnerTools,
+            });
+        // A rule-forced ask only ever tightens: an auto-allow becomes a Canon
+        // approval card, while a non-owner deny still stands.
+        if (!input.ruleForcedAsk || modeDecision.behavior === 'deny') {
+            return modeDecision;
+        }
     }
     if (!input.approvalManager || !(await input.canRequestApproval?.())) {
         return {
@@ -268,9 +296,9 @@ export async function decideClaudeToolPermissionForMode(input) {
     }
     let result;
     try {
-        const risk = classifyClaudeApprovalRisk(input.toolName, input.toolInput);
+        const risk = classifyClaudeApprovalRisk(input.toolName, effectiveToolInput);
         const allowSessionRule = input.allowSessionRule ?? input.isOwnerTurn;
-        result = await input.approvalManager.requestApproval(input.conversationId, input.toolName, input.toolInput, {
+        result = await input.approvalManager.requestApproval(input.conversationId, input.toolName, effectiveToolInput, {
             category: classifyClaudeApprovalCategory(input.toolName),
             risk,
             riskLevel: risk === 'destructive' ? 'destructive' : 'normal',
@@ -280,7 +308,7 @@ export async function decideClaudeToolPermissionForMode(input) {
                 runtime: 'claude-code',
                 method: 'canUseTool',
             },
-            details: buildClaudeApprovalDetails(input.toolName, input.toolInput),
+            details: buildClaudeApprovalDetails(input.toolName, effectiveToolInput),
             ...(diff ? { diff } : {}),
             ...(input.responseUserId ? { responseUserId: input.responseUserId } : {}),
             ignoreSessionRules: !allowSessionRule,
@@ -294,7 +322,10 @@ export async function decideClaudeToolPermissionForMode(input) {
         };
     }
     if (result.decision === 'allow') {
-        return { behavior: 'allow' };
+        return {
+            behavior: 'allow',
+            ...(effectiveToolInput !== input.toolInput ? { updatedInput: effectiveToolInput } : {}),
+        };
     }
     return {
         behavior: 'deny',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.27.3",
+  "version": "0.28.1",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/index.js",
@@ -30,10 +30,10 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.204",
+    "@anthropic-ai/claude-agent-sdk": "0.3.220",
     "@canonmsg/agent-sdk": "^7.1.1",
-    "@canonmsg/coding-agent-host": "^0.2.2",
     "@canonmsg/agent-tools": "^0.3.1",
+    "@canonmsg/coding-agent-host": "^0.2.2",
     "@canonmsg/core": "^8.0.0",
     "@canonmsg/rich-cards": "^0.8.5",
     "@modelcontextprotocol/sdk": "^1.29.0"