@canonmsg/claude-code-plugin 0.29.0 → 0.29.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.29.0",
+  "version": "0.29.1",
   "channels": [
     {
       "server": "canon-channel",

package/README.md

@@ -4,13 +4,14 @@ 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.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.
+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. Either source below that minimum is logged and skipped in favour of the bundled runtime, so a stale install costs model options rather than taking the host down.
 
 ```bash
 # Install
 npm install -g @canonmsg/claude-code-plugin
 
 # Register (approve in Canon app when prompted)
+export CANON_ENVIRONMENT_ID=canon-prod-v1
 canon-register --name "My Claude" --description "My Claude Code agent" --phone "+15551234567"
 
 # Run
@@ -38,6 +39,10 @@ Public docs: <https://canonmail.com/agents/integrations>. Coding-host concepts:
 
 - **Two-way messaging** — Messages from Canon flow to Claude Code and back
 - **Session controls** — Canon renders setup and live controls from the runtime descriptor Claude publishes
+- **Blocking approvals** — Tool permission requests become approval cards in Canon and hold the turn until answered
+- **Questions from Claude** — `AskUserQuestion` dialogs render as answerable cards in the conversation
+- **Runtime commands** — `/status`, `/mcp`, `/plugins`, `/model`, `/permission`, `/effort`, `/ultracode`, `/plan`, plus the CLI's own slash commands passed through to the runtime
+- **Canon verb tools** — Claude can act on Canon itself through an in-process verb MCP server mounted into every host session
 - **Live preview** — See Claude's current live preview/status in the app
 - **Interrupt** — Stop Claude mid-response from the app
 - **Context meter** — See context window usage in the app
@@ -70,25 +75,56 @@ Current Canon truth for Claude host mode:
 ## Multiple agents
 
 ```bash
+export CANON_ENVIRONMENT_ID=canon-prod-v1
 canon-register --name "Frontend" --description "React work" --phone "+1..." --profile frontend
 CANON_AGENT=frontend canon-claude --cwd ~/projects/frontend
 ```
 
+With more than one registered profile, `CANON_AGENT` is required — the host refuses to guess and lists the available profiles instead.
+
 ## Channel mode (alternative)
 
-For a lighter integration without session controls, run Canon as a channel plugin inside your own Claude Code session. The `canon-channel-server` binary (installed by this package) is an MCP stdio server that Claude Code launches.
+For a lighter integration without session controls, run Canon as a channel inside your own Claude Code session. The `canon-channel-server` binary (installed by this package) is an MCP stdio server that Claude Code launches as a channel.
+
+Add it to the project's `.mcp.json` (or `~/.mcp.json` for global):
 
-Register the channel server with Claude Code's MCP config and provide your Canon API key via the `CANON_API_KEY` environment variable:
+```json
+{
+  "mcpServers": {
+    "canon-channel": {
+      "command": "canon-channel-server"
+    }
+  }
+}
+```
+
+Then start Claude Code with the channel loaded:
 
 ```bash
-# Register once per Claude Code project
-claude mcp add canon-channel canon-channel-server
+CANON_API_KEY=agk_live_... CANON_ENVIRONMENT_ID=canon-prod-v1 \
+  claude --dangerously-load-development-channels server:canon-channel
+```
 
-# Then start Claude Code with your Canon key in the environment
-CANON_API_KEY=agk_live_... CANON_ENVIRONMENT_ID=canon-prod-v1 claude
+The launch flag is what activates channel mode; plain `claude` treats the binary as an ordinary MCP server and never opens the channel. Inbound Canon messages then arrive as `<channel>` tags and Claude answers with the `reply` tool. Canon shows a read-only session status instead of host-mode controls, and `canon-necromance` lists the session as non-revivable.
+
+If you registered a profile with `canon-register`, pin it instead of passing the key — the stored profile carries its own environment binding:
+
+```json
+{
+  "mcpServers": {
+    "canon-channel": {
+      "command": "canon-channel-server",
+      "env": { "CANON_AGENT": "my-agent" }
+    }
+  }
+}
 ```
 
-Channel mode forwards messages between Canon conversations and the embedded Claude Code session without managing session lifecycle. It is shown as non-revivable by `canon-necromance`. Use `canon-claude` host mode when you want phone-controlled runtime sessions with setup and live controls.
+`CANON_PLUGIN_API_KEY` is accepted wherever `CANON_API_KEY` is; the bundled Claude Code plugin manifest sets it from user config. `CANON_ENVIRONMENT_ID` is still required with either variable.
+
+`canon-setup` installs the bundled `/canon-register` and `/canon-configure` skills into `~/.claude/skills` and prints this MCP configuration.
+
+Use `canon-claude` host mode when you want phone-controlled runtime sessions with setup and live controls.
 
 ## Development
 

package/dist/host.js

@@ -1482,13 +1482,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
             const deliveredMessageIds = chunkedFailure
                 ? chunkedFailure.deliveredMessageIds
                 : resume.deliveredMessageIds;
-            const failure = classifyFinalDeliveryFailure(cause, { chunked: willChunk });
-            if (failure === 'already-delivered') {
-                // The server's idempotency guard says this final is already durable.
-                markFinalTurnDelivered(deliverTurn);
-                console.error(`[canon-host] [${conversationId.slice(0, 8)}] Final reply was already delivered under this id`);
-                return true;
-            }
+            const failure = classifyFinalDeliveryFailure(cause);
             if (failure === 'permanent') {
                 // Re-sending is pointless — the same request fails the same way. Surface
                 // what can be surfaced and finish the turn instead of burning the retry
@@ -2089,6 +2083,7 @@ function createSession(conversationId, environment, agentId, client, typingSigna
                             if (!shouldApplyClaudeEchoedSessionState({
                                 echoed: state,
                                 dispatching: session.dispatchingInput !== null,
+                                active: session.activeInput !== null,
                                 hasPendingFinalDelivery: Boolean(session.pendingFinalDelivery),
                             })) {
                                 console.error(`[canon-host] [${conversationId.slice(0, 8)}] `

package/dist/session-state.d.ts

@@ -165,6 +165,8 @@ export declare function shouldApplyClaudeEchoedSessionState(input: {
     echoed: ClaudeSessionRunState | undefined;
     /** An input is mid-dispatch: reserved by the host, not yet with the SDK. */
     dispatching: boolean;
+    /** The SDK has accepted a Canon input whose turn has not completed. */
+    active: boolean;
     /** A final is still being handed to Canon; the turn is not over. */
     hasPendingFinalDelivery: boolean;
 }): boolean;
@@ -478,34 +480,19 @@ export declare function composeClaudeFinalText(input: {
     streamedText?: string | null;
     failureNotice?: string | null;
 }): string | null;
-export type ClaudeFinalDeliveryFailure = 'retry' | 'permanent' | 'already-delivered';
+export type ClaudeFinalDeliveryFailure = 'retry' | 'permanent';
 /**
  * How the host should react to a failed final-reply send.
  *
  * Core's `isRetryableCanonDeliveryError` is already right about what a retry
  * can fix (429, 5xx, transport errors); what the host lacked was the other
  * half — everything else is PERMANENT and must be surfaced instead of retried.
- * A 409 from the server's idempotency guard means a message already exists
- * under this id, so the reply is durable: that is a success, not a failure.
- *
- * A CHUNKED final is the exception (#616's rule, kept). A chunked send is N
- * sequential messages that abort on the first failure, so a 409 says only that
- * ONE part id is taken, with nothing to say which — and since the part ids are
- * a pure hash of agent + conversation + turnKey, an id can be taken by an
- * ENTIRELY DIFFERENT answer to the same inbound message, written by a previous
- * process. Reading that as "the final is delivered" would finalize the turn
- * with the tail never sent, so it stays 'permanent': a stops-short notice beats
- * silently dropping the end of an answer.
- *
- * Resume support does not soften this. Core absorbs the one conflict that IS
- * provably ours — the first part of a resumed attempt, whose write may have
- * landed before its response was lost — and reports every other one, so a
- * conflict reaching this function is precisely the case that must not be read
- * as success.
- */
-export declare function classifyFinalDeliveryFailure(error: unknown, options?: {
-    chunked?: boolean;
-}): ClaudeFinalDeliveryFailure;
+ * Exact message-id replays return success with `created: false`. A 409 from the
+ * server's idempotency guard therefore means the stored payload differs from
+ * this final and is permanent; treating it as delivered would retire a turn
+ * whose answer was never accepted.
+ */
+export declare function classifyFinalDeliveryFailure(error: unknown): ClaudeFinalDeliveryFailure;
 /**
  * The pending-delivery record for a final that has to be retried, carrying the
  * progress the next attempt needs.

package/dist/session-state.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { USAGE_LIMIT_ERROR_PREFIXES } from '@anthropic-ai/claude-agent-sdk';
-import { DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES, isCanonMessageIdConflict, isRetryableCanonDeliveryError, utf8ByteLength, VERB_LIMITS, } from '@canonmsg/core';
+import { DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES, isRetryableCanonDeliveryError, utf8ByteLength, VERB_LIMITS, } from '@canonmsg/core';
 import { boundTrailBlockMap, buildTrailBlockId, buildUndeliverableFinalNotice as buildHostUndeliverableFinalNotice, normalizePlanStepStatus, normalizeTrailKey, PLAN_BLOCK_TITLE, renderPlanSteps, truncateFailureDetail, } from '@canonmsg/coding-agent-host';
 export function createClaudeInputEnvelope(input) {
     const sourceMessageId = input.sourceMessageId ?? null;
@@ -163,7 +163,7 @@ export function isClaudeTurnSlotReserved(state) {
 export function shouldApplyClaudeEchoedSessionState(input) {
     if (input.echoed !== 'idle')
         return true;
-    return !input.dispatching && !input.hasPendingFinalDelivery;
+    return !input.dispatching && !input.active && !input.hasPendingFinalDelivery;
 }
 /** Claim the slot for an input about to be dispatched. Must precede any await. */
 export function reserveClaudeTurnSlot(session) {
@@ -775,28 +775,12 @@ export function composeClaudeFinalText(input) {
  * Core's `isRetryableCanonDeliveryError` is already right about what a retry
  * can fix (429, 5xx, transport errors); what the host lacked was the other
  * half — everything else is PERMANENT and must be surfaced instead of retried.
- * A 409 from the server's idempotency guard means a message already exists
- * under this id, so the reply is durable: that is a success, not a failure.
- *
- * A CHUNKED final is the exception (#616's rule, kept). A chunked send is N
- * sequential messages that abort on the first failure, so a 409 says only that
- * ONE part id is taken, with nothing to say which — and since the part ids are
- * a pure hash of agent + conversation + turnKey, an id can be taken by an
- * ENTIRELY DIFFERENT answer to the same inbound message, written by a previous
- * process. Reading that as "the final is delivered" would finalize the turn
- * with the tail never sent, so it stays 'permanent': a stops-short notice beats
- * silently dropping the end of an answer.
- *
- * Resume support does not soften this. Core absorbs the one conflict that IS
- * provably ours — the first part of a resumed attempt, whose write may have
- * landed before its response was lost — and reports every other one, so a
- * conflict reaching this function is precisely the case that must not be read
- * as success.
+ * Exact message-id replays return success with `created: false`. A 409 from the
+ * server's idempotency guard therefore means the stored payload differs from
+ * this final and is permanent; treating it as delivered would retire a turn
+ * whose answer was never accepted.
  */
-export function classifyFinalDeliveryFailure(error, options = {}) {
-    if (isCanonMessageIdConflict(error) && !options.chunked) {
-        return 'already-delivered';
-    }
+export function classifyFinalDeliveryFailure(error) {
     return isRetryableCanonDeliveryError(error) ? 'retry' : 'permanent';
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.29.0",
+  "version": "0.29.1",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/index.js",
@@ -31,11 +31,11 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.220",
-    "@canonmsg/agent-sdk": "^7.1.2",
-    "@canonmsg/agent-tools": "^0.3.1",
-    "@canonmsg/coding-agent-host": "^0.3.0",
-    "@canonmsg/core": "^8.1.0",
-    "@canonmsg/rich-cards": "^0.8.5",
+    "@canonmsg/agent-sdk": "^7.1.3",
+    "@canonmsg/agent-tools": "^0.3.2",
+    "@canonmsg/coding-agent-host": "^0.3.1",
+    "@canonmsg/core": "^8.2.0",
+    "@canonmsg/rich-cards": "^0.8.6",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "engines": {

package/skills/configure/SKILL.md

@@ -1,50 +1,59 @@
 ---
 name: canon-configure
-description: Configure an existing Canon agent API key
+description: Use an existing Canon agent API key with Claude Code
 user-invocable: true
 allowed-tools:
   - Read
   - Write
 ---
 
-# Configure Canon API Key
+# Use an existing Canon API key
 
-Add an existing Canon agent API key as a named profile.
+Point Claude Code at a Canon agent key the user already has.
+
+## Hard rule
+
+Never write or edit `~/.canon/agents.json`. A stored profile must carry the agent
+identity **and** a complete environment-bound endpoint set (`agentId`,
+`environmentId`, `baseUrl`, `streamUrl`, `rtdbUrl`, `firebaseApiKey`), and every
+entry is validated in one pass on load — a single hand-written entry makes the
+whole file unloadable for every Canon host on that machine. Only the register
+CLI writes profiles.
 
 ## Steps
 
 1. Ask the user for:
-   - **API key** — must start with `agk_live_`
-   - **Profile name** — a short identifier (e.g., "my-agent", "reviewer")
-   - **Agent name** (optional) — display name for reference
-
-2. Validate the API key format — it must start with `agk_live_` and be non-empty.
+   - **API key** — starts with `agk_live_`
+   - **Canon environment** — `canon-prod-v1` for production, `canon-dev-v1` for dev
 
-3. Read the existing profiles from `~/.canon/agents.json` (create if missing).
+2. Give them the launch command for the key. Nothing is stored; the key lives in
+   the environment of the process they start:
 
-4. Add/update the profile:
-   ```json
-   {
-     "<profile>": {
-       "apiKey": "<key>",
-       "agentId": "",
-       "agentName": "<name or 'Unknown'>",
-       "registeredAt": "<current ISO date>"
-     }
-   }
+   ```bash
+   CANON_API_KEY=<key> CANON_ENVIRONMENT_ID=<environment> canon-claude --cwd /path/to/project
    ```
 
-5. Write the updated profiles to `~/.canon/agents.json`.
+   `CANON_ENVIRONMENT_ID` is required with a raw key — without it the host exits
+   before connecting. Sessions started this way are shown as
+   manual/non-revivable by `canon-necromance`, because no secret-bearing state is
+   persisted.
 
-6. Tell the user: **"API key saved as profile '<profile>'. Restart Claude Code to connect."**
+3. If the user wants a stored, revivable profile instead, run `/canon-register`.
+   Registration is the only path that writes `~/.canon/agents.json`; re-running it
+   with an existing `--profile` name refreshes that profile's credential in place.
+
+4. Once a profile exists, it can be pinned for channel mode in `.mcp.json`:
 
-   If they have multiple agents and want to pin one, add to `.mcp.json`:
    ```json
    {
      "mcpServers": {
        "canon-channel": {
+         "command": "canon-channel-server",
          "env": { "CANON_AGENT": "<profile>" }
        }
      }
    }
    ```
+
+   `CANON_AGENT` is required as soon as more than one profile exists — the host
+   refuses to guess between them.

package/skills/register/SKILL.md

@@ -18,7 +18,7 @@ Register a new Canon agent so it can send and receive messages. Each agent is sa
    - **Agent name** — The display name for the agent in Canon
    - **Description** — What the agent does (shown to users in Canon)
    - **Owner phone number** — The Canon account owner's phone number in E.164 format (e.g., +15551234567)
-   - **Canon environment** — The trust-domain ID supplied by Canon (production defaults to `canon-prod-v1`)
+   - **Canon environment** — The trust-domain ID supplied by Canon (`canon-prod-v1` for production, `canon-dev-v1` for dev). There is no CLI default; the command fails without it.
    - **Profile name** (optional) — A short identifier for this agent (e.g., "reviewer", "notifier"). Defaults to a sanitized version of the agent name.
 
 2. Run the registration CLI:
@@ -26,18 +26,23 @@ Register a new Canon agent so it can send and receive messages. Each agent is sa
    canon-register --environment "<environment>" --name "<name>" --description "<description>" --phone "<phone>" --profile "<profile>"
    ```
 
+   `CANON_ENVIRONMENT_ID=<environment>` in the environment is equivalent to `--environment`.
+
 3. Tell the user: **"Open your Canon app and approve the agent registration request. Waiting for approval..."**
 
    The CLI will poll automatically for up to 5 minutes.
 
 4. On approval, the CLI saves the agent to `~/.canon/agents.json` automatically.
 
-5. Tell the user: **"Agent registered! Run `canon-claude` to start. Or specify a project: `canon-claude --cwd /path/to/project`"**
+5. Tell the user: **"Agent registered! Start it with `CANON_AGENT=<profile> canon-claude`. Or specify a project: `CANON_AGENT=<profile> canon-claude --cwd /path/to/project`"**
+
+   `CANON_AGENT` is required once more than one profile exists — the host refuses to guess between them.
 
 ## Error handling
 
 - If the registration fails, show the error and ask the user to retry.
 - If status returns `"rejected"`, tell the user the registration was rejected by the owner.
 - If polling times out after 5 minutes, tell the user to try again later.
-- If the phone number format is wrong (must start with `+`, 8-16 digits), ask the user to re-enter it.
+- If the server returns `Invalid phone number format`, the number could not be parsed as a real number; ask the user to re-enter it in full E.164 form (`+<country code><number>`).
+- If the server returns `Owner phone number not found on platform`, the number is valid but no Canon account uses it; ask the user for the phone number of their Canon account.
 - If environment verification fails, do not retry against another URL. Confirm the environment ID and endpoint set with the user.