@canonmsg/claude-code-plugin 0.7.0 → 0.9.0

package/dist/host-runtime.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Host-runtime helpers, inlined from @canonmsg/core.
+ *
+ * These helpers glue Canon host wrappers (Codex, Claude Code) to the Canon
+ * RTDB session/runtime surface. They used to live in
+ * `@canonmsg/core/src/host-runtime/` but were moved into each plugin in
+ * media-parity PR C so core does not have to carry host-specific concerns.
+ *
+ * Keep this file in lockstep with the equivalent file in
+ * `packages/codex-plugin/src/host-runtime.ts`. If you change the
+ * behavior here, update that copy too and adjust the shared golden
+ * fixture test (`packages/claude-code-plugin/src/host-runtime.test.ts`).
+ */
+import { type AgentClientType, type AgentRuntime, type CanonClient, type CanonConversation, type CanonMessage, type CanonMessagesPage, type MessageCreatedPayload, type ResolvedAgentBehaviorPolicy, type SessionWorkspaceConfig } from '@canonmsg/core';
+export interface HostInboundParticipantContext {
+    conversationType: CanonConversation['type'] | 'unknown';
+    memberCount: number | null;
+    senderType: 'human' | 'ai_agent';
+    senderName: string;
+    isOwner: boolean;
+    mentionedAgent: boolean;
+    recentSenderTypes: Array<'human' | 'ai_agent'>;
+    recentHumanCount: number;
+    recentAgentCount: number;
+    consecutiveAgentTurns: number;
+    currentAgentStreakStartedByHuman: boolean;
+}
+type HostInboundMessage = {
+    text?: string | null;
+    contentType?: CanonMessage['contentType'] | null;
+    audioUrl?: string | null;
+    audioDurationMs?: number | null;
+    imageUrl?: string | null;
+    attachments?: CanonMessage['attachments'];
+    senderType?: CanonMessage['senderType'];
+    mentions?: string[] | null;
+};
+interface HostWorkspaceResolverOption {
+    id: string;
+    cwd: string;
+}
+export declare function buildCanonHostPrompt(input: {
+    hostLabel: string;
+    content: string;
+    conversationId: string;
+    participantContext: HostInboundParticipantContext;
+    behavior?: ResolvedAgentBehaviorPolicy | null;
+    workSession?: MessageCreatedPayload['message']['workSession'];
+    workSessions?: MessageCreatedPayload['workSessions'];
+    buildInboundContextLines: (context: HostInboundParticipantContext) => string[];
+}): string;
+/**
+ * Render the **text portion** of an inbound Canon message. Images and other
+ * binary attachments are referenced by short placeholders — their actual
+ * bytes are delivered to the host as native vision/media inputs (Anthropic
+ * image blocks, Codex `-i` file args). URLs are intentionally *not* inlined,
+ * since the harness never needs to refetch and earlier `[Image: <url>]`
+ * inlining caused vision models to see a string about an image instead of
+ * the image itself.
+ *
+ * `materialized` may be passed so non-image attachments can reference a
+ * local path the agent can Read. Without it we fall back to an unadorned
+ * placeholder; the vision path still works because image blocks carry the
+ * bytes directly.
+ */
+export declare function renderCanonHostInboundContent(message: HostInboundMessage, materialized?: ReadonlyArray<{
+    kind: 'image' | 'audio' | 'file';
+    path: string;
+    fileName?: string;
+    durationMs?: number;
+    index: number;
+}>): string;
+export declare function buildHydratedInboundContext(input: {
+    agentId: string;
+    conversation: CanonConversation | null;
+    page?: CanonMessagesPage | null;
+    message: HostInboundMessage;
+    senderName: string;
+    isOwner: boolean;
+}): {
+    participantContext: HostInboundParticipantContext;
+    behavior?: ResolvedAgentBehaviorPolicy | null;
+    workSessions: NonNullable<MessageCreatedPayload['workSessions']>;
+    hydratedFromPage: boolean;
+};
+export declare function publishHostAgentRuntime(agentId: string, clientType: AgentClientType, runtime: AgentRuntime): Promise<void>;
+export declare function readHostSessionConfig<TExtra extends string = never>(raw: unknown, extraStringFields?: readonly TExtra[]): (SessionWorkspaceConfig & Partial<Record<TExtra, string>>) | null;
+export declare function loadHostSessionConfig<TExtra extends string = never>(input: {
+    conversationId: string;
+    agentId: string;
+    extraStringFields?: readonly TExtra[];
+}): Promise<(SessionWorkspaceConfig & Partial<Record<TExtra, string>>) | null>;
+export declare function resolveHostWorkspaceCwd(input: {
+    workspaceOptions: HostWorkspaceResolverOption[];
+    config: {
+        workspaceId?: string;
+        retiredWorkspaceConfig?: boolean;
+    } | null;
+    defaultCwd: string;
+}): string;
+export declare function createConversationMetadataLoader(input: {
+    client: CanonClient;
+    conversationCache: Map<string, CanonConversation>;
+    cacheTtlMs?: number;
+}): {
+    refreshConversationCache(force?: boolean): Promise<void>;
+    getConversationMeta(conversationId: string): Promise<CanonConversation | null>;
+};
+export {};

package/dist/host-runtime.js

@@ -0,0 +1,171 @@
+/**
+ * Host-runtime helpers, inlined from @canonmsg/core.
+ *
+ * These helpers glue Canon host wrappers (Codex, Claude Code) to the Canon
+ * RTDB session/runtime surface. They used to live in
+ * `@canonmsg/core/src/host-runtime/` but were moved into each plugin in
+ * media-parity PR C so core does not have to carry host-specific concerns.
+ *
+ * Keep this file in lockstep with the equivalent file in
+ * `packages/codex-plugin/src/host-runtime.ts`. If you change the
+ * behavior here, update that copy too and adjust the shared golden
+ * fixture test (`packages/claude-code-plugin/src/host-runtime.test.ts`).
+ */
+import { buildBehaviorPolicyLines, buildParticipationHistorySnapshot, buildWorkSessionsPromptLines, mergeWorkSessionContexts, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, rtdbRead, rtdbWrite, } from '@canonmsg/core';
+export function buildCanonHostPrompt(input) {
+    const resolvedWorkSessions = mergeWorkSessionContexts(input.workSession, input.workSessions);
+    return [
+        `You are connected to Canon messaging through a ${input.hostLabel} host wrapper.`,
+        'Only the last assistant message from this turn will be delivered as the permanent Canon reply.',
+        'Short intermediate assistant messages may be shown as ephemeral status while you work.',
+        ...input.buildInboundContextLines(input.participantContext),
+        ...buildBehaviorPolicyLines(input.behavior),
+        ...buildWorkSessionsPromptLines(resolvedWorkSessions),
+        'Canon participants may be humans or AI agents.',
+        'Honor the Canon behavior policy above when deciding how proactively to participate.',
+        ...(resolvedWorkSessions.length > 0
+            ? ['Honor the Canon work-session context above within its stated disclosure limits.']
+            : []),
+        `Conversation ID: ${input.conversationId}`,
+        '',
+        'New Canon message:',
+        input.content,
+    ].join('\n');
+}
+/**
+ * Render the **text portion** of an inbound Canon message. Images and other
+ * binary attachments are referenced by short placeholders — their actual
+ * bytes are delivered to the host as native vision/media inputs (Anthropic
+ * image blocks, Codex `-i` file args). URLs are intentionally *not* inlined,
+ * since the harness never needs to refetch and earlier `[Image: <url>]`
+ * inlining caused vision models to see a string about an image instead of
+ * the image itself.
+ *
+ * `materialized` may be passed so non-image attachments can reference a
+ * local path the agent can Read. Without it we fall back to an unadorned
+ * placeholder; the vision path still works because image blocks carry the
+ * bytes directly.
+ */
+export function renderCanonHostInboundContent(message, materialized) {
+    const body = message.text || '';
+    const placeholders = [];
+    const attachments = message.attachments ?? [];
+    if (attachments.length > 0) {
+        for (let i = 0; i < attachments.length; i += 1) {
+            const att = attachments[i];
+            const mat = materialized?.find((m) => m.index === i) ?? null;
+            placeholders.push(describeAttachment(att, mat));
+        }
+    }
+    else if (message.contentType === 'audio' && message.audioUrl) {
+        const duration = message.audioDurationMs
+            ? ` (${Math.round(message.audioDurationMs / 1000)}s)`
+            : '';
+        placeholders.push(`[Voice message${duration}]`);
+    }
+    else if (message.contentType === 'image' && message.imageUrl) {
+        placeholders.push('[Image attached]');
+    }
+    const rendered = [...placeholders, body].filter(Boolean).join('\n');
+    return rendered || '[Empty message]';
+}
+function describeAttachment(attachment, materialized) {
+    if (attachment.kind === 'image') {
+        return '[Image attached]';
+    }
+    if (attachment.kind === 'audio') {
+        const durationMs = materialized?.durationMs ?? attachment.durationMs;
+        const duration = durationMs ? ` (${Math.round(durationMs / 1000)}s)` : '';
+        const ref = materialized?.path ? ` ${materialized.path}` : '';
+        return `[Voice message${duration}${ref}]`;
+    }
+    // file
+    const label = materialized?.fileName ?? attachment.fileName ?? 'File';
+    const ref = materialized?.path ? ` ${materialized.path}` : '';
+    return `[File: ${label}${ref}]`;
+}
+export function buildHydratedInboundContext(input) {
+    const history = buildParticipationHistorySnapshot(input.page?.messages ?? [], input.agentId);
+    return {
+        participantContext: {
+            conversationType: input.conversation?.type ?? 'unknown',
+            memberCount: input.conversation?.memberIds?.length ?? null,
+            senderType: input.message.senderType ?? 'human',
+            senderName: input.senderName,
+            isOwner: input.isOwner,
+            mentionedAgent: Array.isArray(input.message.mentions) && input.message.mentions.includes(input.agentId),
+            recentSenderTypes: history.recentSenderTypes,
+            recentHumanCount: history.recentHumanCount,
+            recentAgentCount: history.recentAgentCount,
+            consecutiveAgentTurns: history.consecutiveAgentTurns,
+            currentAgentStreakStartedByHuman: history.currentAgentStreakStartedByHuman,
+        },
+        behavior: input.page?.behavior ?? input.conversation?.behavior,
+        workSessions: input.page?.workSessions ?? [],
+        hydratedFromPage: input.page != null,
+    };
+}
+export async function publishHostAgentRuntime(agentId, clientType, runtime) {
+    await rtdbWrite(`/agent-runtime/${agentId}`, {
+        clientType,
+        hostMode: true,
+        ...runtime,
+        updatedAt: { '.sv': 'timestamp' },
+    });
+}
+export function readHostSessionConfig(raw, extraStringFields = []) {
+    const baseConfig = readSessionWorkspaceConfig(raw);
+    if (!raw || typeof raw !== 'object') {
+        return baseConfig;
+    }
+    const data = raw;
+    const extraConfig = Object.fromEntries(extraStringFields.flatMap((field) => {
+        const value = normalizeOptionalString(data[field]);
+        return value ? [[field, value]] : [];
+    }));
+    return {
+        ...(baseConfig ?? {}),
+        ...extraConfig,
+    };
+}
+export async function loadHostSessionConfig(input) {
+    const raw = await rtdbRead(`/session-config/${input.conversationId}/${input.agentId}`);
+    return readHostSessionConfig(raw, input.extraStringFields);
+}
+export function resolveHostWorkspaceCwd(input) {
+    return resolveConfiguredWorkspaceCwd(input);
+}
+export function createConversationMetadataLoader(input) {
+    const cacheTtlMs = input.cacheTtlMs ?? 10_000;
+    let conversationCacheLoadedAt = 0;
+    async function refreshConversationCache(force = false) {
+        if (!force
+            && input.conversationCache.size > 0
+            && Date.now() - conversationCacheLoadedAt < cacheTtlMs) {
+            return;
+        }
+        const conversations = await input.client.getConversations();
+        input.conversationCache.clear();
+        for (const conversation of conversations) {
+            input.conversationCache.set(conversation.id, conversation);
+        }
+        conversationCacheLoadedAt = Date.now();
+    }
+    async function getConversationMeta(conversationId) {
+        try {
+            await refreshConversationCache();
+            const cached = input.conversationCache.get(conversationId);
+            if (cached)
+                return cached;
+            await refreshConversationCache(true);
+            return input.conversationCache.get(conversationId) ?? null;
+        }
+        catch {
+            return input.conversationCache.get(conversationId) ?? null;
+        }
+    }
+    return {
+        refreshConversationCache,
+        getConversationMeta,
+    };
+}

package/dist/host.js

@@ -24,7 +24,9 @@ setDefaultResultOrder('ipv4first');
 import { parseArgs } from 'node:util';
 import { randomUUID } from 'node:crypto';
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { buildParticipationHistorySnapshot, buildBehaviorPolicyLines, buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildPublicWorkspaceOptions, isEnabledFlag, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, CanonClient, CanonStream, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, rtdbRead, rtdbWrite, writeSessionState, clearSessionState, writeTurnState, releaseConversationEnvironment, } from '@canonmsg/core';
+import { isAnthropicImageAttachment, materializeMessageMedia, toAnthropicImageBlock, } from '@canonmsg/agent-sdk';
+import { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, CanonClient, CanonStream, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, rtdbRead, rtdbWrite, writeSessionState, clearSessionState, writeTurnState, releaseConversationEnvironment, } from '@canonmsg/core';
+import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 let workingDir = process.cwd();
 let workspaceOptions = [];
@@ -36,27 +38,29 @@ function toModelOptions(models) {
     }));
 }
 async function publishAgentRuntime(agentId, runtime) {
-    await rtdbWrite(`/agent-runtime/${agentId}`, {
-        clientType: 'claude-code',
-        hostMode: true,
-        ...runtime,
-        updatedAt: { '.sv': 'timestamp' },
-    });
+    await publishHostAgentRuntime(agentId, 'claude-code', runtime);
 }
 async function loadSessionConfig(conversationId, agentId) {
-    const raw = await rtdbRead(`/session-config/${conversationId}/${agentId}`);
-    const baseConfig = readSessionWorkspaceConfig(raw);
-    if (!raw || typeof raw !== 'object')
-        return baseConfig;
-    const data = raw;
-    const permissionMode = normalizeOptionalString(data.permissionMode);
+    const config = await loadHostSessionConfig({
+        conversationId,
+        agentId,
+        extraStringFields: ['permissionMode'],
+    });
     return {
-        ...baseConfig,
-        permissionMode: permissionMode,
+        ...config,
+        permissionMode: config?.permissionMode,
     };
 }
+const SESSION_EXECUTION_MODE_REQUIRED = 'Session execution mode required; please select a mode before starting the session.';
+function requireSessionExecutionMode(config) {
+    const mode = config?.executionMode;
+    if (!mode) {
+        throw new ExecutionEnvironmentError(SESSION_EXECUTION_MODE_REQUIRED, SESSION_EXECUTION_MODE_REQUIRED);
+    }
+    return mode;
+}
 function resolveWorkspaceCwd(config) {
-    return resolveConfiguredWorkspaceCwd({
+    return resolveHostWorkspaceCwd({
         workspaceOptions,
         config,
         defaultCwd: workingDir,
@@ -104,52 +108,34 @@ const CLAUDE_RUNTIME_CAPABILITIES = {
     supportsNonFinalPermanentMessages: false,
 };
 function buildCanonPrompt(input) {
-    return [
-        'You are connected to Canon messaging through a Claude Code host wrapper.',
-        'Only the last assistant message from this turn will be delivered as the permanent Canon reply.',
-        'Short intermediate assistant messages may be shown as ephemeral status while you work.',
-        ...buildInboundContextLines(input.participantContext),
-        ...buildBehaviorPolicyLines(input.behavior),
-        'Canon participants may be humans or AI agents.',
-        'Honor the Canon behavior policy above when deciding how proactively to participate.',
-        `Conversation ID: ${input.conversationId}`,
-        '',
-        'New Canon message:',
-        input.content,
-    ].join('\n');
+    return buildCanonHostPrompt({
+        hostLabel: 'Claude Code',
+        buildInboundContextLines,
+        ...input,
+    });
 }
-function renderInboundContent(message) {
-    let content = message.text || '';
-    const attachment = message.attachments?.[0];
-    if (attachment?.kind === 'audio' && attachment.url) {
-        const duration = attachment.durationMs ? ` (${Math.round(attachment.durationMs / 1000)}s)` : '';
-        content = content
-            ? `[Voice message${duration}: ${attachment.url}]\n${content}`
-            : `[Voice message${duration}: ${attachment.url}]`;
-    }
-    else if (attachment?.kind === 'image' && attachment.url) {
-        content = content
-            ? `[Image: ${attachment.url}]\n${content}`
-            : `[Image: ${attachment.url}]`;
-    }
-    else if (attachment?.kind === 'file' && attachment.url) {
-        const label = attachment.fileName || 'File';
-        content = content
-            ? `[File: ${label} ${attachment.url}]\n${content}`
-            : `[File: ${label} ${attachment.url}]`;
-    }
-    else if (message.contentType === 'audio' && message.audioUrl) {
-        const duration = message.audioDurationMs ? ` (${Math.round(message.audioDurationMs / 1000)}s)` : '';
-        content = content
-            ? `[Voice message${duration}: ${message.audioUrl}]\n${content}`
-            : `[Voice message${duration}: ${message.audioUrl}]`;
-    }
-    else if (message.contentType === 'image' && message.imageUrl) {
-        content = content
-            ? `[Image: ${message.imageUrl}]\n${content}`
-            : `[Image: ${message.imageUrl}]`;
+function renderInboundContent(message, materialized) {
+    return renderCanonHostInboundContent(message, materialized);
+}
+/**
+ * Build the multimodal `content` payload handed to the Claude Code SDK.
+ *
+ * Images are delivered as native Anthropic `image` blocks (base64) so the
+ * vision model sees pixels, not a text reference to a URL. Non-image
+ * attachments (audio, files) are referenced by their local path inside the
+ * text prompt — see `renderCanonHostInboundContent` — so the agent can
+ * Read them on demand.
+ */
+async function buildCanonUserContent(input) {
+    const imageAttachments = input.materialized.filter(isAnthropicImageAttachment);
+    if (imageAttachments.length === 0) {
+        return input.promptText;
     }
-    return content || '[Empty message]';
+    const imageBlocks = await Promise.all(imageAttachments.map((attachment) => toAnthropicImageBlock(attachment)));
+    return [
+        { type: 'text', text: input.promptText },
+        ...imageBlocks,
+    ];
 }
 // ── Session factory ─────────────────────────────────────────────────
 function createSession(conversationId, environment, agentId, client, onSessionEnd, onRuntimeDescriptorUpdate, config, resumeSessionId) {
@@ -655,6 +641,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                 defaultPermissionMode: 'default',
                 availableModels: modelList,
                 availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                availableExecutionModes: config.availableExecutionModes,
             });
             writeSessionState(conversationId, agentId, {
                 ...session.state,
@@ -717,10 +704,14 @@ async function main() {
         console.error(`[canon-host] Authenticated as ${agentId}`);
     }
     let streamConnected = false;
+    const hostAvailableExecutionModes = allowWorktrees
+        ? [...EXECUTION_ENVIRONMENT_MODES]
+        : ['locked'];
     let runtimeDescriptor = {
         defaultWorkspaceId: workspaceOptions[0]?.id,
         defaultPermissionMode: 'default',
         availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+        availableExecutionModes: hostAvailableExecutionModes,
     };
     const publishRuntimeHeartbeat = async () => {
         if (!streamConnected)
@@ -738,6 +729,7 @@ async function main() {
             defaultPermissionMode: 'default',
             availableModels: runtimeModels,
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     catch {
@@ -745,6 +737,7 @@ async function main() {
             defaultWorkspaceId: workspaceOptions[0]?.id,
             defaultPermissionMode: 'default',
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     try {
@@ -760,50 +753,23 @@ async function main() {
     /** Saved SDK session IDs for resume after idle eviction, keyed by conversation + workspace */
     const savedSessionIds = new Map();
     const conversationCache = new Map();
-    let conversationCacheLoadedAt = 0;
-    async function refreshConversationCache(force = false) {
-        if (!force && conversationCache.size > 0 && Date.now() - conversationCacheLoadedAt < 10_000) {
-            return;
-        }
-        const conversations = await client.getConversations();
-        conversationCache.clear();
-        for (const conversation of conversations) {
-            conversationCache.set(conversation.id, conversation);
-        }
-        conversationCacheLoadedAt = Date.now();
-    }
-    async function getConversationMeta(conversationId) {
-        try {
-            await refreshConversationCache();
-            const cached = conversationCache.get(conversationId);
-            if (cached)
-                return cached;
-            await refreshConversationCache(true);
-            return conversationCache.get(conversationId) ?? null;
-        }
-        catch {
-            return conversationCache.get(conversationId) ?? null;
-        }
-    }
-    async function loadParticipantContext(input) {
-        const [conversation, recentMessages] = await Promise.all([
+    const { getConversationMeta } = createConversationMetadataLoader({
+        client,
+        conversationCache,
+    });
+    async function loadHydratedInboundContext(input) {
+        const [conversation, page] = await Promise.all([
             getConversationMeta(input.conversationId),
-            client.getMessages(input.conversationId, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT).catch(() => []),
+            client.getMessagesPage(input.conversationId, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT).catch(() => null),
         ]);
-        const history = buildParticipationHistorySnapshot(recentMessages, agentId);
-        return {
-            conversationType: conversation?.type ?? 'unknown',
-            memberCount: conversation?.memberIds?.length ?? null,
-            senderType: input.message.senderType ?? 'human',
+        return buildHydratedInboundContext({
+            agentId,
+            conversation,
+            page,
+            message: input.message,
             senderName: input.senderName,
             isOwner: input.isOwner,
-            mentionedAgent: Array.isArray(input.message.mentions) && input.message.mentions.includes(agentId),
-            recentSenderTypes: history.recentSenderTypes,
-            recentHumanCount: history.recentHumanCount,
-            recentAgentCount: history.recentAgentCount,
-            consecutiveAgentTurns: history.consecutiveAgentTurns,
-            currentAgentStreakStartedByHuman: history.currentAgentStreakStartedByHuman,
-        };
+        });
     }
     function closeSession(conversationId) {
         const session = sessions.get(conversationId);
@@ -864,12 +830,16 @@ async function main() {
         }
         const creation = (async () => {
             const config = await loadSessionConfig(conversationId, agentId);
+            const sessionExecutionMode = requireSessionExecutionMode(config);
+            if (sessionExecutionMode === 'worktree' && !allowWorktrees) {
+                throw new ExecutionEnvironmentError('This host does not allow worktree sessions (launched without --enable-worktrees).', 'This Canon host was started without worktree isolation enabled. Choose "Lock the workspace" or restart the host with --enable-worktrees.');
+            }
             const workspaceCwd = resolveWorkspaceCwd(config);
             const environment = prepareConversationEnvironment({
                 agentId,
                 conversationId,
                 workspaceCwd,
-                allowWorktrees,
+                allowWorktrees: sessionExecutionMode === 'worktree',
             });
             try {
                 const resumeKey = buildConversationEnvironmentKey(conversationId, environment.baseCwd);
@@ -893,6 +863,7 @@ async function main() {
                     model: config?.model ?? runtimeModels[0]?.value,
                     permissionMode: config?.permissionMode ?? 'default',
                     availableModels: runtimeModels,
+                    availableExecutionModes: hostAvailableExecutionModes,
                 }, resumeId);
                 sessions.set(conversationId, session);
                 return session;
@@ -933,17 +904,37 @@ async function main() {
                     }
                 }
                 const sender = m.senderName || m.senderId;
-                const content = renderInboundContent(m);
                 const isOwner = m.isOwner ?? (ownerId != null && m.senderId === ownerId);
                 void (async () => {
-                    const conversation = await getConversationMeta(convoId);
-                    const behavior = payload.behavior ?? conversation?.behavior;
-                    const participantContext = await loadParticipantContext({
+                    let materialized = [];
+                    if (m.id) {
+                        try {
+                            materialized = await materializeMessageMedia({
+                                id: m.id,
+                                attachments: m.attachments,
+                                imageUrl: m.imageUrl ?? null,
+                                audioUrl: m.audioUrl ?? null,
+                                audioDurationMs: m.audioDurationMs ?? null,
+                            }, { agentId, conversationId: convoId });
+                        }
+                        catch (error) {
+                            console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to materialize media:`, error instanceof Error ? error.message : error);
+                        }
+                    }
+                    const content = renderInboundContent(m, materialized);
+                    const hydrated = await loadHydratedInboundContext({
                         conversationId: convoId,
                         message: m,
                         senderName: sender,
                         isOwner,
                     });
+                    const behavior = payload.behavior ?? hydrated.behavior;
+                    const workSessions = hydrated.hydratedFromPage
+                        ? hydrated.workSessions
+                        : Array.isArray(payload.workSessions)
+                            ? payload.workSessions
+                            : hydrated.workSessions;
+                    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}`);
@@ -964,16 +955,20 @@ async function main() {
                     const turnMetadata = normalizeTurnMetadata(m.metadata);
                     const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
                     const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
+                    const promptText = buildCanonPrompt({
+                        content,
+                        conversationId: convoId,
+                        participantContext,
+                        behavior,
+                        workSession: m.workSession,
+                        workSessions,
+                    });
+                    const messageContent = await buildCanonUserContent({ promptText, materialized });
                     session.enqueueInbound({
                         type: 'user',
                         message: {
                             role: 'user',
-                            content: buildCanonPrompt({
-                                content,
-                                conversationId: convoId,
-                                participantContext,
-                                behavior,
-                            }),
+                            content: messageContent,
                         },
                         parent_tool_use_id: null,
                     }, deliveryIntent, m.id ?? null, shouldMarkAccepted);

package/dist/server.js

@@ -125,6 +125,48 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ['conversation_id'],
             },
         },
+        {
+            name: 'send_linked_message',
+            description: 'Send a message into another Canon conversation under an existing or lazily created shared work session',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    source_conversation_id: {
+                        type: 'string',
+                        description: 'The originating conversation for the shared task',
+                    },
+                    target_conversation_id: {
+                        type: 'string',
+                        description: 'The destination conversation to send into',
+                    },
+                    text: {
+                        type: 'string',
+                        description: 'Message text to send',
+                    },
+                    work_session_id: {
+                        type: 'string',
+                        description: 'Reuse an existing Canon work session when known',
+                    },
+                    create_work_session: {
+                        type: 'object',
+                        description: 'Optional initial work-session fields when creating a new shared task',
+                    },
+                    source_context: {
+                        type: 'object',
+                        description: 'Optional scoped context patch for the source conversation',
+                    },
+                    target_context: {
+                        type: 'object',
+                        description: 'Optional scoped context patch for the target conversation',
+                    },
+                    message_options: {
+                        type: 'object',
+                        description: 'Optional Canon send options for the linked outbound message',
+                    },
+                },
+                required: ['source_conversation_id', 'target_conversation_id', 'text'],
+            },
+        },
         {
             name: 'list_conversations',
             description: "List Canon conversations this agent participates in",
@@ -234,6 +276,58 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        case 'send_linked_message': {
+            const sourceConversationId = args.source_conversation_id;
+            const targetConversationId = args.target_conversation_id;
+            const text = args.text;
+            const workSessionId = typeof args.work_session_id === 'string' ? args.work_session_id : undefined;
+            const createWorkSession = typeof args.create_work_session === 'object' && args.create_work_session != null
+                ? args.create_work_session
+                : undefined;
+            const sourceContext = typeof args.source_context === 'object' && args.source_context != null
+                ? args.source_context
+                : undefined;
+            const targetContext = typeof args.target_context === 'object' && args.target_context != null
+                ? args.target_context
+                : undefined;
+            const messageOptions = typeof args.message_options === 'object' && args.message_options != null
+                ? args.message_options
+                : undefined;
+            const result = await client.sendLinkedMessage({
+                sourceConversationId,
+                targetConversationId,
+                text,
+                ...(workSessionId ? { workSessionId } : {}),
+                ...(createWorkSession
+                    ? {
+                        createWorkSession: createWorkSession,
+                    }
+                    : {}),
+                ...(sourceContext
+                    ? {
+                        sourceContext: sourceContext,
+                    }
+                    : {}),
+                ...(targetContext
+                    ? {
+                        targetContext: targetContext,
+                    }
+                    : {}),
+                ...(messageOptions
+                    ? {
+                        messageOptions: messageOptions,
+                    }
+                    : {}),
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Linked message sent (${result.messageId}) via work session ${result.workSessionId}${result.workSessionCreated ? ' [created]' : ''}`,
+                    },
+                ],
+            };
+        }
         case 'list_conversations': {
             const limit = args.limit || 20;
             const convos = await client.getConversations();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/server.js",
@@ -18,11 +18,13 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "tsc --watch",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "test": "vitest run"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.101",
-    "@canonmsg/core": "^0.6.0",
+    "@canonmsg/agent-sdk": "^0.8.0",
+    "@canonmsg/core": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.12.0"
   },
   "engines": {
@@ -47,7 +49,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "~5.7.0"
+    "typescript": "~5.7.0",
+    "vitest": "^3.0.0"
   },
   "license": "MIT"
 }