@canonmsg/claude-code-plugin 0.10.0 → 0.12.1

package/README.md

@@ -15,13 +15,21 @@ 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.).
+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.
+
+After a restart or closed terminal, use the shared local manager to list and revive all recorded local agents:
+
+```bash
+npm install -g @canonmsg/local-agents
+canon-necromance
+canon-necromance revive frontend
+```
 
 ## Features
 
 - **Two-way messaging** — Messages from Canon flow to Claude Code and back
-- **Session controls** — Switch model (Haiku/Sonnet/Opus) and permission mode from the app
-- **Live streaming** — See Claude's response as it types
+- **Session controls** — Canon renders setup and live controls from the runtime descriptor Claude publishes
+- **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
 - **Max plan auth** — Uses your Claude subscription, no API key billing
@@ -35,10 +43,19 @@ canon-claude --cwd /path/to/project
 Advertise multiple project choices to the Canon app:
 
 ```bash
-canon-claude --cwd ~/dev --workspace ~/dev/canon --workspace ~/dev/yumyumv2
+canon-claude --cwd ~/dev --workspace-root ~/dev
 ```
 
-`--cwd` is the default workspace. Each `--workspace` value appears as a selectable workspace during session creation. Worktree mode creates a per-conversation git worktree under `~/.canon/conversation-worktrees`; shared-workspace mode runs directly in the selected directory.
+`--cwd` is the default workspace. Each `--workspace-root` value is an approved local root; the host discovers immediate child projects with common markers such as `.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, or `go.mod` and publishes them as selectable projects during session creation. Use repeated `--workspace /path/to/project` entries to advertise specific projects outside those roots. Worktree mode creates a per-conversation git worktree under `~/.canon/conversation-worktrees`; shared-project mode runs directly in the selected directory.
+
+Current Canon truth for Claude host mode:
+
+- model is live-editable
+- thinking level / effort is live-editable when the host reports it
+- workspace selection is setup-only
+- execution mode selection is setup-only
+- permission modes are rendered exactly as the Claude runtime reports them; Canon does not flatten them to a smaller hardcoded set
+- if worktree creation is unavailable for the selected project, Canon may fall back to shared-project execution and surface the fallback reason in session details
 
 ## Multiple agents
 
@@ -51,6 +68,8 @@ CANON_AGENT=frontend canon-claude --cwd ~/projects/frontend
 
 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).
 
+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.
+
 ## Development
 
 ```bash

package/dist/host-runtime.js

@@ -69,8 +69,6 @@ export function renderCanonHostInboundContent(message, materialized) {
 }
 function describeContactCard(card) {
     const parts = [`${card.userType} · userId: ${card.userId}`];
-    if (card.accessLevel)
-        parts.push(`access: ${card.accessLevel}`);
     if (card.ownerName)
         parts.push(`owner: ${card.ownerName}`);
     if (card.about)

package/dist/host.js

@@ -26,18 +26,22 @@ 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, buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildPlanApprovalRequest, buildQuestionRequest, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, rtdbRead, rtdbWrite, writeRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, releaseConversationEnvironment, } from '@canonmsg/core';
+import { CLAUDE_PERMISSION_MODE_OPTIONS, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildPlanApprovalRequest, buildQuestionRequest, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, clearTurnState, 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, writeRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { createStreamingBuffer } from './streaming-buffer.js';
 import { runCli } from './cli-entry.js';
 let workingDir = process.cwd();
 let workspaceOptions = [];
+let workspaceRoots = [];
+let workspaceRootMetadata = [];
 let runtimeModels = [];
 const CLAUDE_METADATA_TTL_MS = 5 * 60 * 1000;
 let runtimeMetadata = {
     account: null,
     mcpServers: [],
+    commands: [],
+    agents: [],
     plugins: [],
     loadedAt: 0,
 };
@@ -56,25 +60,32 @@ function buildClaudeRuntimeDescriptor(input) {
             },
             {
                 id: 'workspace',
-                label: 'Workspace',
+                label: 'Project',
                 options: input.workspaces.map((workspace) => ({
                     value: workspace.id,
                     label: workspace.label,
+                    ...(workspace.description ? { description: workspace.description } : {}),
+                    ...(workspace.workspaceRootId ? { workspaceRootId: workspace.workspaceRootId } : {}),
+                    ...(workspace.workspaceRelativePath ? { workspaceRelativePath: workspace.workspaceRelativePath } : {}),
+                    ...(workspace.source ? { source: workspace.source } : {}),
                 })),
                 defaultValue: input.workspaces[0]?.id ?? null,
                 availability: 'setup',
                 liveBehavior: 'none',
                 selectionPolicy: 'inherit',
+                description: input.workspaceRoots?.length
+                    ? 'Choose one of the projects discovered inside the approved local roots for this host.'
+                    : 'Choose one of the local projects advertised by this host.',
             },
             {
                 id: 'executionMode',
                 label: 'Execution mode',
                 options: input.executionModes.map((mode) => ({
                     value: mode,
-                    label: mode === 'worktree' ? 'Isolated worktree' : 'Use shared workspace',
+                    label: mode === 'worktree' ? 'Isolated worktree' : 'Use shared project',
                     description: mode === 'worktree'
-                        ? 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected workspace is a git repo.'
-                        : 'Runs directly in the selected workspace. Canon records usage, but does not create a separate checkout.',
+                        ? 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected project is a git repo.'
+                        : 'Runs directly in the selected project folder. Changes happen there.',
                 })),
                 defaultValue: null,
                 availability: 'setup',
@@ -106,8 +117,97 @@ function buildClaudeRuntimeDescriptor(input) {
                 selectionPolicy: 'inherit',
             },
         ],
+        actions: [
+            {
+                id: 'plan',
+                label: 'Plan first',
+                description: 'Switch Claude into Plan mode. Text after /plan is kept as a ready prompt while the mode applies.',
+                aliases: ['plan'],
+                category: 'plan',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['always'],
+                trailingTextBehavior: 'send_as_prompt',
+                dispatch: {
+                    kind: 'control',
+                    controlId: 'permissionMode',
+                    value: 'plan',
+                },
+            },
+            {
+                id: 'runtime-status',
+                label: 'Runtime status',
+                description: 'Open Claude runtime details, including account, project, and policy status.',
+                aliases: ['status'],
+                category: 'details',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['always'],
+                dispatch: { kind: 'open_details', target: 'status' },
+            },
+            {
+                id: 'mcp-inventory',
+                label: 'MCP servers',
+                description: 'Open the Claude MCP inventory published by the host.',
+                aliases: ['mcp'],
+                category: 'details',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['always'],
+                dispatch: { kind: 'open_details', target: 'mcp' },
+            },
+            {
+                id: 'plugin-inventory',
+                label: 'Plugins',
+                description: 'Open the Claude plugin and command inventory published by the host.',
+                aliases: ['plugins'],
+                category: 'details',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['always'],
+                dispatch: { kind: 'open_details', target: 'plugins' },
+            },
+            {
+                id: 'model-details',
+                label: 'Model control',
+                description: 'Open runtime details and use the live Model control.',
+                aliases: ['model'],
+                category: 'details',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['always'],
+                dispatch: { kind: 'open_details', target: 'model' },
+            },
+            {
+                id: 'permission-details',
+                label: 'Permission mode',
+                description: 'Open runtime details and use the live Permission mode control.',
+                aliases: ['permission'],
+                category: 'details',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['always'],
+                dispatch: { kind: 'open_details', target: 'permissionMode' },
+            },
+            {
+                id: 'effort-details',
+                label: 'Thinking level',
+                description: 'Open runtime details and use the live Thinking level control.',
+                aliases: ['effort'],
+                category: 'details',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['always'],
+                dispatch: { kind: 'open_details', target: 'effort' },
+            },
+            {
+                id: 'stop',
+                label: 'Stop',
+                description: 'Interrupt the current Claude turn.',
+                aliases: ['stop'],
+                category: 'turn',
+                placements: ['composer_slash', 'command_palette'],
+                availability: ['busy'],
+                dispatch: { kind: 'signal', signal: 'interrupt' },
+            },
+        ],
+        workspaceRoots: input.workspaceRoots,
         supportsInterrupt: true,
         streamingTextMode: 'delta',
+        admissionActions: HOST_ADMISSION_ACTIONS_DISABLED,
     };
 }
 function normalizeClaudeEffortLevel(value) {
@@ -172,11 +272,10 @@ async function loadSessionConfig(conversationId, agentId) {
         effort: normalizeClaudeEffortLevel(config?.effort),
     };
 }
-// Default to 'locked' (shared workspace) when no mode has been picked. The
-// UI still lets owners flip to 'worktree'; this just stops sessions from
-// failing closed when the mode has never been written.
 function resolveSessionExecutionMode(config) {
-    return config?.executionMode ?? 'locked';
+    if (config?.executionMode)
+        return config.executionMode;
+    throw new ExecutionEnvironmentError('Session config is missing an execution mode.', 'Choose Isolated worktree or Use shared project before starting this coding session.');
 }
 function resolveWorkspaceCwd(config) {
     return resolveHostWorkspaceCwd({
@@ -245,6 +344,8 @@ async function inspectClaudeRuntimeMetadata(cwd, activeQuery) {
         return {
             account: init.account ?? null,
             mcpServers: pluginInfo?.mcpServers ?? mcpServers,
+            commands: pluginInfo?.commands ?? init.commands ?? [],
+            agents: pluginInfo?.agents ?? init.agents ?? [],
             plugins: pluginInfo?.plugins ?? [],
             loadedAt: Date.now(),
         };
@@ -369,10 +470,32 @@ function buildClaudeRuntimeInfo(input) {
                     description: plugin.source ?? plugin.path,
                 })),
             },
+            {
+                id: 'commands',
+                label: 'Commands',
+                entries: metadata.commands.map((command) => ({
+                    id: command.name,
+                    label: command.name.startsWith('/') ? command.name : `/${command.name}`,
+                    status: 'configured',
+                    description: command.description ?? command.argumentHint ?? undefined,
+                })),
+            },
+            {
+                id: 'agents',
+                label: 'Agents',
+                entries: metadata.agents.map((agent) => ({
+                    id: agent.name,
+                    label: agent.name,
+                    status: 'configured',
+                    description: agent.description ?? agent.model ?? undefined,
+                })),
+            },
         ],
         execution: {
             resolvedWorkspaceLabel: input.workspaceLabel,
             resolvedCwd: input.resolvedCwd,
+            workspaceRootId: input.workspaceRootId ?? null,
+            workspaceRelativePath: input.workspaceRelativePath ?? null,
             executionMode: input.executionMode,
             executionBranch: input.executionBranch,
             worktreePath: input.worktreePath,
@@ -495,6 +618,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         systemPrompt: { type: 'preset', preset: 'claude_code' },
         tools: { type: 'preset', preset: 'claude_code' },
         permissionMode: config.permissionMode,
+        allowDangerouslySkipPermissions: true,
         cwd,
         includePartialMessages: true,
         maxTurns: 200,
@@ -534,7 +658,30 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
             if (toolName === 'ExitPlanMode') {
                 try {
                     const planId = randomUUID();
-                    const planApproval = buildPlanApprovalRequest(planId);
+                    const allowedPrompts = Array.isArray(input.allowedPrompts)
+                        ? input.allowedPrompts
+                            .map((entry) => {
+                            if (!entry || typeof entry !== 'object') {
+                                return null;
+                            }
+                            const prompt = entry.prompt;
+                            const tool = entry.tool;
+                            if (typeof prompt !== 'string' || !prompt.trim()) {
+                                return null;
+                            }
+                            return {
+                                tool: typeof tool === 'string' && tool.trim() ? tool : 'Tool',
+                                prompt,
+                            };
+                        })
+                            .filter((entry) => Boolean(entry))
+                        : [];
+                    const planApproval = buildPlanApprovalRequest(planId, 'Plan ready for review.', allowedPrompts.length > 0 ? {
+                        summary: 'Claude has prepared a plan and is asking permission to continue.',
+                        allowedPrompts,
+                    } : {
+                        summary: 'Claude has prepared a plan and is asking permission to continue.',
+                    });
                     await client.sendMessage(conversationId, planApproval.text, {
                         metadata: {
                             ...planApproval.metadata,
@@ -594,6 +741,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         currentTurnOpenedAt: null,
         lastAcceptedIntent: null,
         lastActivity: Date.now(),
+        typingKeepaliveTimer: null,
         closed: false,
         sdkSessionId: resumeSessionId || null,
         pendingReply: null,
@@ -650,6 +798,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         session.pendingFinalDeliveryText = null;
         session.toolInProgress = false;
         session.turnState = 'idle';
+        stopVisibleWorkSignal();
         writeTurn();
         drainPendingInput();
     }
@@ -668,6 +817,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         session.pendingFinalDeliveryText = finalText;
         session.state.state = 'running';
         session.turnState = 'streaming';
+        stopVisibleWorkSignal();
         streamingBuffer.replace(finalText);
         writeState();
         writeTurn();
@@ -719,6 +869,9 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
             executionMode: session.environment.mode,
             ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
             ...(session.environment.worktreePath ? { worktreePath: session.environment.worktreePath } : {}),
+            ...(resolveExecutionFallbackReason(session.environment)
+                ? { executionFallbackReason: resolveExecutionFallbackReason(session.environment) ?? undefined }
+                : {}),
             hostMode: true,
             isActive: true,
         }).catch(() => { });
@@ -737,6 +890,25 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                 : {}),
         }).catch(() => { });
     }
+    function refreshVisibleWorkSignal() {
+        if (session.closed)
+            return;
+        if (session.turnState !== 'thinking' && session.turnState !== 'tool')
+            return;
+        client.setTyping(conversationId, true, 'thinking').catch(() => { });
+    }
+    function startVisibleWorkSignal() {
+        refreshVisibleWorkSignal();
+        if (session.typingKeepaliveTimer)
+            return;
+        session.typingKeepaliveTimer = setInterval(refreshVisibleWorkSignal, 3500);
+    }
+    function stopVisibleWorkSignal() {
+        if (session.typingKeepaliveTimer) {
+            clearInterval(session.typingKeepaliveTimer);
+            session.typingKeepaliveTimer = null;
+        }
+    }
     async function markQueuedMessageAccepted(sourceMessageId, markAccepted) {
         if (!markAccepted || !sourceMessageId)
             return;
@@ -768,6 +940,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         if (session.state.state === 'running' && intent === 'interrupt') {
             session.pendingInputs.unshift({ msg, intent, sourceMessageId, markAccepted });
             session.turnState = 'interrupted';
+            stopVisibleWorkSignal();
             writeTurn();
             void session.query.interrupt().catch(() => { });
             return;
@@ -808,18 +981,22 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                         if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
                             session.toolInProgress = true;
                             session.turnState = 'tool';
+                            startVisibleWorkSignal();
                             writeTurn();
                         }
                         else if (event?.type === 'content_block_stop' && session.toolInProgress) {
                             session.toolInProgress = false;
                             if (session.state.state === 'running') {
                                 session.turnState = 'thinking';
+                                startVisibleWorkSignal();
                                 writeTurn();
                             }
                         }
                         else if (event?.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
                             session.toolInProgress = false;
                             session.turnState = 'streaming';
+                            stopVisibleWorkSignal();
+                            client.setTyping(conversationId, false).catch(() => { });
                             writeTurn();
                             onStreamDelta(event.delta.text);
                         }
@@ -840,9 +1017,10 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                                 session.pendingFinalText = null;
                                 session.toolInProgress = false;
                                 session.turnState = 'thinking';
-                                client.setTyping(conversationId, true, 'thinking').catch(() => { });
+                                startVisibleWorkSignal();
                             }
                             else if (state === 'idle') {
+                                stopVisibleWorkSignal();
                                 client.setTyping(conversationId, false).catch(() => { });
                             }
                             else if (state === 'requires_action') {
@@ -853,6 +1031,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                                 }
                                 session.toolInProgress = false;
                                 session.turnState = 'waiting_input';
+                                stopVisibleWorkSignal();
                                 client.setTyping(conversationId, false).catch(() => { });
                             }
                             writeState();
@@ -952,6 +1131,12 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                 availableModels: modelList,
                 availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
                 availableExecutionModes: config.availableExecutionModes,
+                runtimeDescriptor: buildClaudeRuntimeDescriptor({
+                    models: modelList,
+                    workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                    workspaceRoots: workspaceRootMetadata,
+                    executionModes: config.availableExecutionModes,
+                }),
             });
             writeSessionState(conversationId, agentId, {
                 ...session.state,
@@ -960,6 +1145,9 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                 executionMode: session.environment.mode,
                 ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
                 ...(session.environment.worktreePath ? { worktreePath: session.environment.worktreePath } : {}),
+                ...(resolveExecutionFallbackReason(session.environment)
+                    ? { executionFallbackReason: resolveExecutionFallbackReason(session.environment) ?? undefined }
+                    : {}),
                 hostMode: true,
                 isActive: true,
             }).catch(() => { });
@@ -971,7 +1159,13 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         console.error(`[canon-host] [${conversationId.slice(0, 8)}] Session ${resumeSessionId ? 'resumed' : 'started'} `
             + `(mode: ${environment.mode}, cwd: ${cwd})`);
     };
-    init().catch((err) => console.error(`[canon-host] [${conversationId.slice(0, 8)}] Init failed:`, err));
+    init().catch((err) => {
+        console.error(`[canon-host] [${conversationId.slice(0, 8)}] Init failed:`, err);
+        if (resumeSessionId) {
+            session.sdkSessionId = null;
+            onSessionEnd(conversationId, null);
+        }
+    });
     return session;
 }
 // ── Main ────────────────────────────────────────────────────────────
@@ -981,16 +1175,28 @@ export async function main() {
         options: {
             cwd: { type: 'string' },
             workspace: { type: 'string', multiple: true },
+            'workspace-root': { type: 'string', multiple: true },
         },
         strict: false,
     });
     workingDir = (typeof args.cwd === 'string' ? args.cwd : null) || process.cwd();
     const configuredWorkspaces = (args.workspace ?? []).filter((value) => typeof value === 'string');
-    workspaceOptions = buildConfiguredWorkspaceOptions(workingDir, configuredWorkspaces);
-    const { apiKey, agentId: profileAgentId, profile } = resolveCanonAgent({ logPrefix: '[canon-host]' });
+    const configuredWorkspaceRoots = (args['workspace-root'] ?? []).filter((value) => typeof value === 'string');
+    const workspaceDiscovery = buildConfiguredWorkspaceOptionsWithRoots({
+        primaryCwd: workingDir,
+        configuredWorkspaces,
+        workspaceRoots: configuredWorkspaceRoots,
+    });
+    workspaceOptions = workspaceDiscovery.workspaceOptions;
+    workspaceRoots = workspaceDiscovery.workspaceRoots;
+    workspaceRootMetadata = buildPublicWorkspaceRoots(workspaceRoots);
+    for (const warning of workspaceDiscovery.warnings) {
+        console.error(`[canon-host] ${warning}`);
+    }
+    const { apiKey, agentId: profileAgentId, agentName: profileAgentName, profile, baseUrl, lockHandle, } = resolveCanonAgent({ logPrefix: '[canon-host]', expectedClientType: 'claude-code' });
     console.error(`[canon-host] Starting${profile ? ` (profile: ${profile})` : ''} in ${workingDir}`);
     // ── Canon API client + RTDB auth ──
-    const client = new CanonClient(apiKey);
+    const client = new CanonClient(apiKey, baseUrl);
     initRTDBAuth(client);
     let agentId;
     let ownerId = null;
@@ -1010,6 +1216,34 @@ export async function main() {
         }
         console.error(`[canon-host] Authenticated as ${agentId}`);
     }
+    const launchArgs = [...process.argv.slice(2)];
+    if (!launchArgs.some((arg) => arg === '--cwd' || arg.startsWith('--cwd='))) {
+        launchArgs.push('--cwd', workingDir);
+    }
+    const runtimeId = buildLocalRuntimeId({
+        runtime: 'claude-code',
+        profile,
+        cwd: workingDir,
+        launchCommand: ['canon-claude', ...launchArgs],
+    });
+    upsertLocalRuntimeEntry({
+        id: runtimeId,
+        runtime: 'claude-code',
+        profile,
+        agentId,
+        agentName: profileAgentName,
+        cwd: workingDir,
+        baseCwd: workingDir,
+        workspaceRoots: workspaceRoots.map((root) => root.cwd),
+        workspaces: workspaceOptions.map((workspace) => workspace.cwd),
+        launchCommand: ['canon-claude', ...launchArgs],
+        pid: process.pid,
+        status: profile ? 'running' : 'manual',
+        reviveCapability: profile ? 'revivable' : 'manual',
+        surfaceMode: 'host',
+        lastStartedAt: new Date().toISOString(),
+        lastHeartbeatAt: new Date().toISOString(),
+    });
     let streamConnected = false;
     const hostAvailableExecutionModes = [
         ...EXECUTION_ENVIRONMENT_MODES,
@@ -1023,6 +1257,7 @@ export async function main() {
         runtimeDescriptor: buildClaudeRuntimeDescriptor({
             models: runtimeModels,
             workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            workspaceRoots: workspaceRootMetadata,
             executionModes: hostAvailableExecutionModes,
         }),
     };
@@ -1030,6 +1265,12 @@ export async function main() {
     const knownConversationIds = new Set();
     let lastKnownConversationRefreshAt = 0;
     const publishRuntimeHeartbeat = async () => {
+        heartbeatLocalRuntimeEntry(runtimeId, {
+            agentId,
+            agentName: profileAgentName,
+            cwd: workingDir,
+            baseCwd: workingDir,
+        });
         if (!streamConnected)
             return;
         await refreshKnownConversationIds().catch((error) => {
@@ -1080,11 +1321,14 @@ export async function main() {
                 descriptor: runtimeDescriptor.runtimeDescriptor ?? buildClaudeRuntimeDescriptor({
                     models: runtimeModels,
                     workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                    workspaceRoots: workspaceRootMetadata,
                     executionModes: hostAvailableExecutionModes,
                 }),
                 metadata,
                 workspaceLabel: workspace?.label ?? workspaceId ?? null,
                 resolvedCwd: session?.cwd ?? workspace?.cwd ?? workingDir,
+                workspaceRootId: workspace?.workspaceRootId ?? null,
+                workspaceRelativePath: workspace?.workspaceRelativePath ?? null,
                 executionMode: session?.environment.mode ?? null,
                 executionBranch: session?.environment.branch ?? null,
                 worktreePath: session?.environment.worktreePath ?? null,
@@ -1109,6 +1353,7 @@ export async function main() {
             runtimeDescriptor: buildClaudeRuntimeDescriptor({
                 models: runtimeModels,
                 workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                workspaceRoots: workspaceRootMetadata,
                 executionModes: hostAvailableExecutionModes,
             }),
         };
@@ -1123,6 +1368,7 @@ export async function main() {
             runtimeDescriptor: buildClaudeRuntimeDescriptor({
                 models: runtimeModels,
                 workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                workspaceRoots: workspaceRootMetadata,
                 executionModes: hostAvailableExecutionModes,
             }),
         };
@@ -1182,10 +1428,20 @@ export async function main() {
         if (!session)
             return;
         session.closed = true;
+        if (session.typingKeepaliveTimer) {
+            clearInterval(session.typingKeepaliveTimer);
+            session.typingKeepaliveTimer = null;
+        }
         releaseConversationEnvironment(session.environment);
         // Save SDK session ID for future resume
         if (session.sdkSessionId) {
             savedSessionIds.set(buildConversationEnvironmentKey(conversationId, session.environment.baseCwd), session.sdkSessionId);
+            saveRuntimeSessionState(runtimeId, {
+                conversationId,
+                baseCwd: session.environment.baseCwd,
+                executionMode: session.environment.mode,
+                claudeSessionId: session.sdkSessionId,
+            });
         }
         if (session.streamingTimer)
             clearTimeout(session.streamingTimer);
@@ -1248,7 +1504,12 @@ export async function main() {
             });
             try {
                 const resumeKey = buildConversationEnvironmentKey(conversationId, environment.baseCwd);
-                const resumeId = savedSessionIds.get(resumeKey);
+                const persisted = loadRuntimeSessionState(runtimeId, {
+                    conversationId,
+                    baseCwd: environment.baseCwd,
+                    executionMode: environment.mode,
+                });
+                const resumeId = savedSessionIds.get(resumeKey) ?? persisted?.claudeSessionId;
                 const session = createSession(conversationId, environment, agentId, client, (convoId, sdkSessionId) => {
                     // Called when session processing loop ends — save session ID for resume
                     const existing = sessions.get(convoId);
@@ -1256,6 +1517,19 @@ export async function main() {
                         releaseConversationEnvironment(existing.environment);
                         if (sdkSessionId) {
                             savedSessionIds.set(buildConversationEnvironmentKey(convoId, existing.environment.baseCwd), sdkSessionId);
+                            saveRuntimeSessionState(runtimeId, {
+                                conversationId: convoId,
+                                baseCwd: existing.environment.baseCwd,
+                                executionMode: existing.environment.mode,
+                                claudeSessionId: sdkSessionId,
+                            });
+                        }
+                        else {
+                            clearRuntimeSessionState(runtimeId, {
+                                conversationId: convoId,
+                                baseCwd: existing.environment.baseCwd,
+                                executionMode: existing.environment.mode,
+                            });
                         }
                     }
                     sessions.delete(convoId);
@@ -1287,6 +1561,112 @@ export async function main() {
             pendingSessionCreations.delete(conversationId);
         }
     }
+    async function enqueueRecoveredInboundMessage(input) {
+        const m = input.message;
+        if (m.senderId === agentId)
+            return;
+        let materialized = [];
+        if (m.id) {
+            try {
+                materialized = await materializeMessageMedia({
+                    id: m.id,
+                    attachments: m.attachments ?? [],
+                }, { agentId, conversationId: input.conversationId });
+            }
+            catch (error) {
+                console.error(`[canon-host] [${input.conversationId.slice(0, 8)}] Failed to materialize recovered media:`, error instanceof Error ? error.message : error);
+            }
+        }
+        const sender = m.senderName || m.senderId;
+        const isOwner = m.isOwner ?? (ownerId != null && m.senderId === ownerId);
+        const content = renderInboundContent(m, materialized);
+        const hydrated = await loadHydratedInboundContext({
+            conversationId: input.conversationId,
+            message: m,
+            senderName: sender,
+            isOwner,
+        });
+        const behavior = input.hydratedPage?.behavior ?? hydrated.behavior;
+        const workSessions = input.hydratedPage?.workSessions ?? hydrated.workSessions;
+        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;
+        }
+        let session;
+        try {
+            session = await getOrCreateSession(input.conversationId);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            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}`, {
+                metadata: {
+                    turnSemantics: 'turn_complete',
+                    turnComplete: true,
+                },
+            }).catch(() => { });
+            return;
+        }
+        const turnMetadata = normalizeTurnMetadata(m.metadata);
+        const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
+        const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
+        const promptText = buildCanonPrompt({
+            content,
+            conversationId: input.conversationId,
+            participantContext,
+            behavior,
+            workSession: m.workSession,
+            workSessions,
+        });
+        const messageContent = await buildCanonUserContent({ promptText, materialized });
+        session.enqueueInbound({
+            type: 'user',
+            message: {
+                role: 'user',
+                content: messageContent,
+            },
+            parent_tool_use_id: null,
+        }, deliveryIntent, m.id ?? null, shouldMarkAccepted);
+        if (m.id) {
+            saveRuntimeSessionState(runtimeId, {
+                conversationId: input.conversationId,
+                baseCwd: workingDir,
+                lastInboundMessageId: m.id,
+            });
+        }
+    }
+    try {
+        for (const conversation of conversationCache.values()) {
+            const cursor = loadRuntimeSessionState(runtimeId, {
+                conversationId: conversation.id,
+                baseCwd: workingDir,
+            })?.lastInboundMessageId;
+            const page = await client.getMessagesPage(conversation.id, 25);
+            const inboundMessages = page.messages
+                .filter((message) => message.senderId !== agentId)
+                .sort((a, b) => String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? '')));
+            const cursorIndex = cursor
+                ? inboundMessages.findIndex((message) => message.id === cursor)
+                : -1;
+            const messagesToRecover = cursorIndex >= 0
+                ? inboundMessages.slice(cursorIndex + 1)
+                : inboundMessages.slice(-1);
+            for (const message of messagesToRecover) {
+                console.error(`[canon-host] [${conversation.id.slice(0, 8)}] Recovering inbound message on startup`);
+                await enqueueRecoveredInboundMessage({
+                    conversationId: conversation.id,
+                    message: message,
+                    hydratedPage: page,
+                });
+            }
+        }
+    }
+    catch (error) {
+        console.error('[canon-host] Failed startup recovery:', error instanceof Error ? error.message : error);
+    }
     // ── Connect SSE stream for inbound Canon messages ──
     const stream = new CanonStream({
         apiKey,
@@ -1370,7 +1750,12 @@ export async function main() {
                         const message = error instanceof Error ? error.message : String(error);
                         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}`).catch(() => { });
+                        await client.sendMessage(convoId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
+                            metadata: {
+                                turnSemantics: 'turn_complete',
+                                turnComplete: true,
+                            },
+                        }).catch(() => { });
                         return;
                     }
                     const turnMetadata = normalizeTurnMetadata(m.metadata);
@@ -1393,6 +1778,13 @@ export async function main() {
                         },
                         parent_tool_use_id: null,
                     }, deliveryIntent, m.id ?? null, shouldMarkAccepted);
+                    if (m.id) {
+                        saveRuntimeSessionState(runtimeId, {
+                            conversationId: convoId,
+                            baseCwd: workingDir,
+                            lastInboundMessageId: m.id,
+                        });
+                    }
                 })();
             },
             onConnected: () => {
@@ -1467,6 +1859,9 @@ export async function main() {
                                     executionMode: session.environment.mode,
                                     ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
                                     ...(session.environment.worktreePath ? { worktreePath: session.environment.worktreePath } : {}),
+                                    ...(resolveExecutionFallbackReason(session.environment)
+                                        ? { executionFallbackReason: resolveExecutionFallbackReason(session.environment) ?? undefined }
+                                        : {}),
                                     hostMode: true,
                                     isActive: true,
                                 }).catch(() => { });
@@ -1571,13 +1966,13 @@ export async function main() {
         for (const convoId of [...sessions.keys()]) {
             closeSession(convoId);
         }
-        const ap = getActiveProfile();
-        if (ap)
-            releaseLock(ap);
+        markLocalRuntimeStopped(runtimeId);
+        (lockHandle ?? getActiveProfileLock())?.release();
         process.exit(0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    process.on('SIGHUP', shutdown);
     console.error('[canon-host] Ready — sessions created on demand');
     // Keep alive
     await new Promise(() => { });
@@ -1585,8 +1980,6 @@ export async function main() {
 // ── Entry ───────────────────────────────────────────────────────────
 runCli(import.meta.url, main, (err) => {
     console.error('[canon-host] Fatal error:', err);
-    const ap = getActiveProfile();
-    if (ap)
-        releaseLock(ap);
+    getActiveProfileLock()?.release();
     process.exit(1);
 });

package/dist/register.js

@@ -9,14 +9,10 @@ import { setDefaultResultOrder } from 'node:dns';
  *
  * On approval, saves the agent to ~/.canon/agents.json under the profile name.
  */
-import { registerAndWaitForApproval } from '@canonmsg/core';
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
+import { ackRegistrationApproval, clearPendingRegistration, getOrCreatePendingRegistration, registerAndWaitForApproval, updatePendingRegistration, upsertAgentProfile, AGENTS_PATH, } from '@canonmsg/core';
+import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { runCli } from './cli-entry.js';
-const CANON_DIR = join(homedir(), '.canon');
-const AGENTS_PATH = join(CANON_DIR, 'agents.json');
 export async function main() {
     setDefaultResultOrder('ipv4first');
     const { values } = parseArgs({
@@ -44,6 +40,7 @@ export async function main() {
         // File doesn't exist yet
     }
     console.log(`Registering agent "${values.name}" (profile: ${profileName})...`);
+    const pending = getOrCreatePendingRegistration(profileName, 'claude-code');
     const result = await registerAndWaitForApproval({
         name: values.name,
         description: values.description,
@@ -52,8 +49,14 @@ export async function main() {
         clientType: 'claude-code',
         baseUrl: values['base-url'],
         requestedAgentId: existingAgentId,
+        localRegistrationId: pending.localRegistrationId,
     }, {
-        onSubmitted: (requestId) => {
+        onSubmitted: (requestId, pollToken) => {
+            updatePendingRegistration(profileName, {
+                requestId,
+                pollToken,
+                clientType: 'claude-code',
+            });
             console.log(`Registration submitted (request ID: ${requestId}).`);
             console.log('Waiting for approval in Canon app...');
         },
@@ -64,25 +67,26 @@ export async function main() {
     console.log(''); // newline after dots
     switch (result.status) {
         case 'approved': {
-            // Save to ~/.canon/agents.json
-            mkdirSync(CANON_DIR, { recursive: true });
-            let profiles = {};
-            try {
-                profiles = JSON.parse(readFileSync(AGENTS_PATH, 'utf-8'));
+            if (!result.apiKey || !result.agentId || !result.agentName) {
+                console.error('Approval completed but Canon did not return a usable API key. Run this command again to resume key pickup.');
+                process.exit(1);
             }
-            catch {
-                // File doesn't exist yet
-            }
-            profiles[profileName] = {
+            upsertAgentProfile(profileName, {
                 apiKey: result.apiKey,
                 agentId: result.agentId,
                 agentName: result.agentName,
                 registeredAt: new Date().toISOString(),
-            };
-            writeFileSync(AGENTS_PATH, JSON.stringify(profiles, null, 2));
+                clientType: 'claude-code',
+                ...(typeof values['base-url'] === 'string' ? { baseUrl: values['base-url'] } : {}),
+            });
+            if (result.requestId) {
+                await ackRegistrationApproval(values['base-url'], result.requestId, result.pollToken);
+            }
+            clearPendingRegistration(profileName);
             console.log(`Approved! Agent: ${result.agentName} (${result.agentId})`);
             console.log(`Saved as profile "${profileName}" in ~/.canon/agents.json`);
-            console.log('Restart Claude Code to connect.');
+            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.');
             break;
         }
         case 'rejected':

package/dist/server.js

@@ -10,7 +10,7 @@ import { setDefaultResultOrder } from 'node:dns';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { CanonClient, CanonStream, ApprovalManager, loadProfiles, isProfileLocked, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
+import { CanonClient, CanonStream, ApprovalManager, buildLocalRuntimeId, getActiveProfileLock, markLocalRuntimeStopped, loadProfiles, isProfileLocked, resolveCanonAgent, getActiveProfile, releaseLock, upsertLocalRuntimeEntry, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
 import { ApprovalHttpServer } from './approval-server.js';
 import { runCli } from './cli-entry.js';
 // ── MCP server ─────────────────────────────────────────────────────────
@@ -26,6 +26,10 @@ let agentContext = null;
 let approvalManager = null;
 let approvalServer = null;
 const conversationCache = new Map();
+const TURN_COMPLETE_METADATA = {
+    turnSemantics: 'turn_complete',
+    turnComplete: true,
+};
 /** The conversation that most recently triggered work (for approval routing) */
 let triggerConversationId = null;
 function getPrimaryAttachment(message) {
@@ -221,7 +225,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         case 'reply': {
             const conversationId = args.conversation_id;
             const text = args.text;
-            const result = await client.sendMessage(conversationId, text);
+            const result = await client.sendMessage(conversationId, text, {
+                metadata: TURN_COMPLETE_METADATA,
+            });
             return {
                 content: [
                     {
@@ -261,6 +267,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             else {
                 opts.contentType = contentType;
             }
+            opts.metadata = {
+                ...(opts.metadata ?? {}),
+                ...TURN_COMPLETE_METADATA,
+            };
             const result = await client.sendMessage(conversationId, text, opts);
             return {
                 content: [
@@ -288,6 +298,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const messageOptions = typeof args.message_options === 'object' && args.message_options != null
                 ? args.message_options
                 : undefined;
+            const linkedMessageOptions = messageOptions;
             const result = await client.sendLinkedMessage({
                 sourceConversationId,
                 targetConversationId,
@@ -308,11 +319,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         targetContext: targetContext,
                     }
                     : {}),
-                ...(messageOptions
+                ...(linkedMessageOptions
                     ? {
-                        messageOptions: messageOptions,
+                        messageOptions: {
+                            ...linkedMessageOptions,
+                            metadata: {
+                                ...(linkedMessageOptions.metadata ?? {}),
+                                ...TURN_COMPLETE_METADATA,
+                            },
+                        },
                     }
-                    : {}),
+                    : { messageOptions: { metadata: TURN_COMPLETE_METADATA } }),
             });
             return {
                 content: [
@@ -508,10 +525,14 @@ async function handleInboundMessage(payload) {
 async function startChannel() {
     let apiKey;
     let profile;
+    let baseUrl;
+    let profileAgentName;
     try {
-        const resolved = resolveCanonAgent({ logPrefix: '[canon]' });
+        const resolved = resolveCanonAgent({ logPrefix: '[canon]', expectedClientType: 'claude-code' });
         apiKey = resolved.apiKey;
         profile = resolved.profile;
+        baseUrl = resolved.baseUrl;
+        profileAgentName = resolved.agentName;
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : err);
@@ -520,7 +541,7 @@ async function startChannel() {
     if (profile) {
         console.error(`[canon] Using agent profile: ${profile}`);
     }
-    client = new CanonClient(apiKey);
+    client = new CanonClient(apiKey, baseUrl);
     // Get agent identity — try /agents/me first, fall back to /agents/auth-token
     let agentId;
     try {
@@ -543,6 +564,27 @@ async function startChannel() {
     }
     // Initialize RTDB auth for session state reporting
     initRTDBAuth(client);
+    const runtimeId = buildLocalRuntimeId({
+        runtime: 'claude-code',
+        profile,
+        cwd: process.cwd(),
+        launchCommand: ['canon-channel-server'],
+    });
+    upsertLocalRuntimeEntry({
+        id: runtimeId,
+        runtime: 'claude-code',
+        profile,
+        agentId,
+        agentName: agentContext?.displayName ?? profileAgentName,
+        cwd: process.cwd(),
+        launchCommand: ['canon-channel-server'],
+        pid: process.pid,
+        status: 'embedded',
+        reviveCapability: 'embedded',
+        surfaceMode: 'channel',
+        lastStartedAt: new Date().toISOString(),
+        lastHeartbeatAt: new Date().toISOString(),
+    });
     // Populate conversation cache
     try {
         const convos = await client.getConversations();
@@ -610,13 +652,22 @@ export async function main() {
         approvalManager?.dispose();
         approvalServer?.stop().catch(() => { });
         stream?.stop();
+        const runtimeId = buildLocalRuntimeId({
+            runtime: 'claude-code',
+            profile: getActiveProfile(),
+            cwd: process.cwd(),
+            launchCommand: ['canon-channel-server'],
+        });
+        markLocalRuntimeStopped(runtimeId);
         const ap = getActiveProfile();
         if (ap)
             releaseLock(ap);
+        getActiveProfileLock()?.release();
         process.exit(0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    process.on('SIGHUP', shutdown);
 }
 runCli(import.meta.url, main, (err) => {
     console.error('[canon] Fatal error:', err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.10.0",
+  "version": "0.12.1",
   "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": "^0.9.0",
-    "@canonmsg/core": "^0.8.0",
+    "@canonmsg/agent-sdk": "^0.10.1",
+    "@canonmsg/core": "^0.13.0",
     "@modelcontextprotocol/sdk": "^1.12.0"
   },
   "engines": {