@canonmsg/claude-code-plugin 0.27.3 → 0.28.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.27.3",
+  "version": "0.28.0",
   "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, claudeModelInfoToOption, claudeOriginForCanonSender, composeClaudeFinalText, 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;
@@ -322,39 +323,57 @@ function resolveClaudeCliPath() {
         }
         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;
+    }
+    // A stale CLI on PATH would otherwise shadow the newer bundled one and quietly
+    // drop model families from discovery. Prefer the bundle over a silent downgrade.
+    let version = null;
+    try {
+        version = readExternalClaudeCliVersion(resolved);
+    }
+    catch (error) {
+        console.error(`[canon-host] Could not read the version of the claude CLI at ${resolved}:`, error);
+    }
+    if (!version || !isSupportedClaudeCliVersion(version)) {
+        cachedClaudeCliPath = null;
+        const found = version ? `is ${formatClaudeCliVersion(version)}` : 'has an unreadable version';
+        console.error(`[canon-host] claude CLI on PATH (${resolved}) ${found}; `
+            + `${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;
+    }
+    cachedClaudeCliPath = resolved;
+    console.error(`[canon-host] claude CLI on PATH: ${resolved} (${formatClaudeCliVersion(version)})`);
+    return resolved;
 }
-function assertExternalClaudeCliVersion(cliPath) {
+function readExternalClaudeCliVersion(cliPath) {
     const output = execFileSync(cliPath, ['--version'], { encoding: 'utf8' }).trim();
-    const match = output.match(/^(\d+)\.(\d+)\.(\d+)/);
-    if (!match) {
+    const version = parseClaudeCliVersion(output);
+    if (!version) {
         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]}.`);
+    return version;
+}
+function assertExternalClaudeCliVersion(cliPath) {
+    const version = readExternalClaudeCliVersion(cliPath);
+    if (!isSupportedClaudeCliVersion(version)) {
+        throw new Error(`Claude Code ${formatClaudeCliVersion(MINIMUM_CLAUDE_CLI_VERSION)} or newer is required; `
+            + `found ${formatClaudeCliVersion(version)}.`);
     }
 }
 function toModelOptions(models) {
@@ -398,16 +417,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);
@@ -1044,6 +1060,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.
@@ -1209,7 +1226,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 +1236,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             turnKey: turn.turnKey,
             text: finalText,
             retryCount,
+            ...(suppressAutoReply ? { suppressAutoReply: true } : {}),
             messageId: buildClaudeFinalMessageId({
                 agentId,
                 conversationId,
@@ -1233,7 +1251,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 +1273,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 +1292,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 +1352,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;
@@ -1651,7 +1667,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,
@@ -1660,7 +1691,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                             })
                             : false;
                         const finalDelivered = finalText && shouldDeliverFinal
-                            ? await deliverFinalReply(finalText, completedInput)
+                            ? await deliverFinalReply(finalText, completedInput, Boolean(failureNotice))
                             : true;
                         try {
                             const usage = await q.getContextUsage();
@@ -1757,9 +1788,10 @@ function createSession(conversationId, environment, agentId, client, typingSigna
         // 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 +2571,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 +2827,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,4 +1,4 @@
-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';
@@ -25,6 +25,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: {
@@ -67,6 +69,48 @@ export declare function shouldDeliverClaudeFinal(input: {
     interruptedTurnKeys: ReadonlySet<string>;
 }): boolean;
 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 +118,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 +134,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,4 +1,5 @@
 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();
@@ -60,6 +61,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 +192,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 +262,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.0",
   "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"