@canonmsg/claude-code-plugin 0.28.1 → 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.28.1",
+  "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