@canonmsg/claude-code-plugin 0.13.0 → 0.14.0

package/README.md

@@ -15,7 +15,7 @@ canon-register --name "My Claude" --description "My Claude Code agent" --phone "
 canon-claude
 ```
 
-Send a message to your agent in the Canon app. Claude Code responds with full capabilities (file read/write, bash, etc.). Keep the `canon-claude` terminal open; closing it takes this local agent offline.
+Send a message to your agent in the Canon app. Claude Code responds with full capabilities (file read/write, bash, etc.). `canon-claude` is the local agent process. Keep that terminal open while you want Canon to reach the agent. Closing it, logging out, rebooting, or sleeping long enough to stop the process takes this local agent offline until you revive it.
 
 After a restart or closed terminal, use the shared local manager to list and revive all recorded local agents:
 
@@ -25,6 +25,8 @@ canon-necromance
 canon-necromance revive frontend
 ```
 
+Public docs: <https://canonmail.com/agents/integrations>. Coding-host concepts: <https://canonmail.com/agents/coding-agents>.
+
 ## Features
 
 - **Two-way messaging** — Messages from Canon flow to Claude Code and back
@@ -66,9 +68,19 @@ CANON_AGENT=frontend canon-claude --cwd ~/projects/frontend
 
 ## Channel mode (alternative)
 
-For a lighter integration without session controls, run Canon as a channel plugin inside your own Claude Code session. See [full setup guide](../../docs/claude-code-setup.md#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.
+
+Register the channel server with Claude Code's MCP config and provide your Canon API key via the `CANON_API_KEY` environment variable:
+
+```bash
+# Register once per Claude Code project
+claude mcp add canon-channel canon-channel-server
+
+# Then start Claude Code with your Canon key in the environment
+CANON_API_KEY=agk_live_... claude
+```
 
-Channel mode is embedded inside Claude Code and is shown as non-revivable by `canon-necromance`. Use `canon-claude` host mode when you want phone-controlled runtime sessions.
+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.
 
 ## Development
 

package/dist/host.js

@@ -26,7 +26,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { query, } from '@anthropic-ai/claude-agent-sdk';
 import { isAnthropicImageAttachment, materializeMessageMedia, toAnthropicImageBlock, } from '@canonmsg/agent-sdk';
-import { CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, buildPlanApprovalRequest, buildQuestionRequest, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, createConversationMetadataLoader, createRuntimeStatePublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, initRTDBAuth, rtdbRead, rtdbWrite, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { CLAUDE_PERMISSION_MODE_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPlanApprovalRequest, buildQuestionRequest, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, createConversationMetadataLoader, createRuntimeStatePublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, initRTDBAuth, rtdbRead, rtdbWrite, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { createStreamingBuffer } from './streaming-buffer.js';
 import { runCli } from './cli-entry.js';
@@ -51,7 +51,10 @@ EXAMPLES
   canon-claude --cwd ~/dev/canon
   canon-claude --cwd ~/dev/canon --workspace-root ~/dev
 
-Keep this terminal open while you want Canon to reach the agent.`;
+Keep this terminal open while you want Canon to reach the agent. Closing it,
+logging out, rebooting, or sleeping long enough to stop the process takes the
+local agent offline until you revive it. Docs:
+https://canonmail.com/agents/integrations`;
 let workingDir = process.cwd();
 let workspaceOptions = [];
 let workspaceRoots = [];
@@ -785,6 +788,10 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
     function onStreamDelta(text) {
         streamingBuffer.append(text);
     }
+    function isActiveTurnInterrupted() {
+        const turnKey = session.activeInput?.turnKey;
+        return Boolean(turnKey && session.interruptedTurnKeys.has(turnKey));
+    }
     function clearStreaming() {
         streamingBuffer.clear();
         runtimeState.clearStreaming(conversationId).catch(() => { });
@@ -1077,6 +1084,11 @@ function createSession(conversationId, environment, agentId, client, runtimeStat
                     }
                     case 'stream_event': {
                         const event = msg.event;
+                        if (isActiveTurnInterrupted()) {
+                            stopVisibleWorkSignal();
+                            client.setTyping(conversationId, false).catch(() => { });
+                            break;
+                        }
                         if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
                             session.toolInProgress = true;
                             session.turnState = 'tool';
@@ -1313,10 +1325,12 @@ export async function main() {
     initRTDBAuth(client);
     let agentId;
     let ownerId = null;
+    let ownerName = null;
     try {
         const ctx = await client.getAgentMe();
         agentId = ctx.agentId;
         ownerId = ctx.ownerId;
+        ownerName = ctx.ownerName;
         console.error(`[canon-host] Connected as ${ctx.displayName || agentId}`);
     }
     catch {
@@ -1381,6 +1395,8 @@ export async function main() {
     };
     const conversationCache = new Map();
     const knownConversationIds = new Set();
+    const promptedGroupContextConversationIds = new Set();
+    const pendingMembershipChanges = new Map();
     let lastKnownConversationRefreshAt = 0;
     const publishRuntimeHeartbeat = async () => {
         heartbeatLocalRuntimeEntry(runtimeId, {
@@ -1533,18 +1549,65 @@ export async function main() {
         }
         lastKnownConversationRefreshAt = Date.now();
     }
+    function handleConversationUpdated(payload) {
+        const rawMemberIds = payload.changes.memberIds;
+        if (!Array.isArray(rawMemberIds))
+            return;
+        const memberIds = rawMemberIds.filter((id) => typeof id === 'string');
+        const cached = conversationCache.get(payload.conversationId);
+        const membershipChange = payload.membershipChange
+            ?? (cached ? diffCanonMemberIds(cached.memberIds, memberIds) : null);
+        if (cached) {
+            conversationCache.set(payload.conversationId, {
+                ...cached,
+                memberIds,
+            });
+        }
+        if (membershipChange) {
+            pendingMembershipChanges.set(payload.conversationId, membershipChange);
+        }
+        if (!memberIds.includes(agentId)) {
+            knownConversationIds.delete(payload.conversationId);
+            conversationCache.delete(payload.conversationId);
+        }
+    }
+    function getGroupContextMode(conversationId, conversation) {
+        if (conversation?.type !== 'group')
+            return undefined;
+        if (pendingMembershipChanges.has(conversationId))
+            return 'membership_change';
+        if (!promptedGroupContextConversationIds.has(conversationId))
+            return 'initial';
+        return undefined;
+    }
+    function markGroupContextModeUsed(conversationId, mode) {
+        if (!mode)
+            return;
+        promptedGroupContextConversationIds.add(conversationId);
+        if (mode === 'membership_change') {
+            pendingMembershipChanges.delete(conversationId);
+        }
+    }
     async function loadHydratedInboundContext(input) {
         const [conversation, page] = await Promise.all([
             getConversationMeta(input.conversationId),
-            client.getMessagesPage(input.conversationId, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT).catch(() => null),
+            input.hydratedPage
+                ? Promise.resolve(input.hydratedPage)
+                : client.getMessagesPage(input.conversationId, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT).catch(() => null),
         ]);
         return buildHydratedInboundContext({
             agentId,
             conversation,
             page,
+            activeSelfContextId: input.activeSelfContextId,
+            selfContexts: input.selfContexts,
             message: input.message,
             senderName: input.senderName,
             isOwner: input.isOwner,
+            ownerId,
+            ownerName,
+            membershipChange: pendingMembershipChanges.get(input.conversationId) ?? null,
+            groupContextMode: getGroupContextMode(input.conversationId, conversation),
         });
     }
     function closeSession(conversationId, options = {}) {
@@ -1779,15 +1842,18 @@ export async function main() {
             message: m,
             senderName: sender,
             isOwner,
+            hydratedPage: input.hydratedPage,
         });
         const behavior = input.hydratedPage?.behavior ?? hydrated.behavior;
-        const selfContexts = input.hydratedPage?.selfContexts ?? hydrated.selfContexts;
+        const activeSelfContextId = hydrated.activeSelfContextId;
+        const selfContexts = hydrated.selfContexts;
         const participantContext = hydrated.participantContext;
         const autoReply = decideAutoReply(participantContext, behavior);
         if (!autoReply.allow) {
             console.error(`[canon-host] [${input.conversationId.slice(0, 8)}] Suppressed recovered auto-reply: ${autoReply.reason}`);
             return;
         }
+        markGroupContextModeUsed(input.conversationId, participantContext.groupContextMode);
         let session;
         try {
             session = await getOrCreateSession(input.conversationId);
@@ -1797,7 +1863,7 @@ export async function main() {
             const userMessage = error instanceof ExecutionEnvironmentError ? error.userMessage : message;
             console.error(`[canon-host] [${input.conversationId.slice(0, 8)}] Failed to create recovered session: ${message}`);
             await client.sendMessage(input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
-                ...(selfContexts[0]?.id ? { selfContextId: selfContexts[0].id } : {}),
+                ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                 metadata: {
                     turnSemantics: 'turn_complete',
                     turnComplete: true,
@@ -1807,7 +1873,7 @@ export async function main() {
             return;
         }
         const turnMetadata = normalizeTurnMetadata(m.metadata);
-        session.activeSelfContextId = selfContexts[0]?.id ?? null;
+        session.activeSelfContextId = activeSelfContextId;
         const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
         const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
         const promptText = buildCanonPrompt({
@@ -1925,19 +1991,19 @@ export async function main() {
                         message: m,
                         senderName: sender,
                         isOwner,
+                        activeSelfContextId: payload.activeSelfContextId,
+                        selfContexts: payload.selfContexts,
                     });
                     const behavior = payload.behavior ?? hydrated.behavior;
-                    const selfContexts = hydrated.hydratedFromPage
-                        ? hydrated.selfContexts
-                        : Array.isArray(payload.selfContexts)
-                            ? payload.selfContexts
-                            : hydrated.selfContexts;
+                    const activeSelfContextId = hydrated.activeSelfContextId;
+                    const selfContexts = hydrated.selfContexts;
                     const participantContext = hydrated.participantContext;
                     const autoReply = decideAutoReply(participantContext, behavior);
                     if (!autoReply.allow) {
                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Suppressed auto-reply: ${autoReply.reason}`);
                         return;
                     }
+                    markGroupContextModeUsed(convoId, participantContext.groupContextMode);
                     console.error(`[canon-host] [${convoId.slice(0, 8)}] Message from ${sender}: "${content.slice(0, 80)}" (${autoReply.reason})`);
                     let session;
                     try {
@@ -1948,7 +2014,7 @@ export async function main() {
                         const userMessage = error instanceof ExecutionEnvironmentError ? error.userMessage : message;
                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to create session: ${message}`);
                         await client.sendMessage(convoId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
-                            ...(selfContexts[0]?.id ? { selfContextId: selfContexts[0].id } : {}),
+                            ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                             metadata: {
                                 turnSemantics: 'turn_complete',
                                 turnComplete: true,
@@ -1958,7 +2024,7 @@ export async function main() {
                         return;
                     }
                     const turnMetadata = normalizeTurnMetadata(m.metadata);
-                    session.activeSelfContextId = selfContexts[0]?.id ?? null;
+                    session.activeSelfContextId = activeSelfContextId;
                     const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
                     const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
                     const promptText = buildCanonPrompt({
@@ -1987,6 +2053,9 @@ export async function main() {
                     }
                 })();
             },
+            onConversationUpdated: (payload) => {
+                handleConversationUpdated(payload);
+            },
             onConnected: () => {
                 streamConnected = true;
                 void publishRuntimeHeartbeat();

package/dist/inbound-policy.d.ts

@@ -1,4 +1,4 @@
-import { type CanonConversation, type ResolvedAgentBehaviorPolicy } from '@canonmsg/core';
+import { type CanonGroupContext, type CanonGroupContextMode, type CanonConversation, type ResolvedAgentBehaviorPolicy } from '@canonmsg/core';
 export interface InboundParticipantContext {
     conversationType: CanonConversation['type'] | 'unknown';
     memberCount: number | null;
@@ -6,6 +6,8 @@ export interface InboundParticipantContext {
     senderName: string;
     isOwner: boolean;
     mentionedAgent: boolean;
+    groupContext?: CanonGroupContext;
+    groupContextMode?: CanonGroupContextMode;
     recentSenderTypes: Array<'human' | 'ai_agent'>;
     recentHumanCount: number;
     recentAgentCount: number;

package/dist/inbound-policy.js

@@ -1,4 +1,4 @@
-import { evaluateParticipationPolicy, resolveAgentBehaviorPolicy, } from '@canonmsg/core';
+import { buildCompactGroupContextLines, evaluateParticipationPolicy, resolveAgentBehaviorPolicy, } from '@canonmsg/core';
 function formatRecentSenders(senderTypes) {
     if (senderTypes.length === 0)
         return 'none';
@@ -18,6 +18,9 @@ export function buildInboundContextLines(context) {
         `Latest sender name: ${context.senderName}`,
         `Latest sender type: ${context.senderType}`,
         `Conversation type: ${conversationTypeLabel}`,
+        ...(context.groupContext && context.groupContextMode
+            ? buildCompactGroupContextLines(context.groupContext, context.groupContextMode)
+            : []),
         `Directly addressed to this agent: ${context.mentionedAgent ? 'yes' : 'no'}`,
         `Recent sender pattern: ${formatRecentSenders(context.recentSenderTypes)}`,
         `Recent human messages: ${context.recentHumanCount}`,

package/dist/register.js

@@ -107,7 +107,9 @@ export async function main() {
             console.log(`Approved! Agent: ${result.agentName} (${result.agentId})`);
             console.log(`Saved as profile "${profileName}" in ~/.canon/agents.json`);
             console.log('Start it with: CANON_AGENT=' + profileName + ' canon-claude --cwd /path/to/project');
-            console.log('Keep that terminal open. Closing it takes this local agent offline.');
+            console.log('Keep that terminal open while you want Canon to reach the agent.');
+            console.log('Closing it, logging out, rebooting, or sleeping long enough to stop the process takes this local agent offline until you revive it.');
+            console.log('Docs: https://canonmail.com/agents/integrations');
             break;
         }
         case 'rejected':

package/dist/server.js

@@ -447,6 +447,9 @@ async function handleInboundMessage(payload) {
         }
     }
     if (Array.isArray(payload.selfContexts) && payload.selfContexts.length > 0) {
+        if (payload.activeSelfContextId) {
+            meta.active_self_context_id = payload.activeSelfContextId;
+        }
         meta.self_context_ids = payload.selfContexts
             .map((selfContext) => selfContext.id)
             .join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/index.js",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.101",
-    "@canonmsg/agent-sdk": "^1.2.0",
-    "@canonmsg/core": "^0.16.0",
+    "@canonmsg/agent-sdk": "^1.3.0",
+    "@canonmsg/core": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.12.0"
   },
   "engines": {