@canonmsg/codex-plugin 0.4.0 → 0.6.0

package/dist/adapter.d.ts

@@ -36,7 +36,7 @@ export declare class CodexConversationAdapter {
     private readonly codexBin;
     private model;
     private readonly sandbox;
-    private readonly approvalPolicy;
+    private readonly legacyApprovalPolicy;
     private readonly codexProfile;
     private readonly addDirs;
     private readonly configOverrides;
@@ -63,7 +63,7 @@ export declare class CodexConversationAdapter {
     setModel(model: string | null): void;
     isRunning(): boolean;
     interrupt(): Promise<void>;
-    runTurn(prompt: string, onEvent: (event: CodexEvent) => void, onLog?: (line: string) => void): Promise<CodexTurnResult>;
+    runTurn(prompt: string, onEvent: (event: CodexEvent) => void, onLog?: (line: string) => void, imagePaths?: readonly string[]): Promise<CodexTurnResult>;
     private buildArgs;
     private clearActiveProcess;
 }

package/dist/adapter.js

@@ -5,7 +5,7 @@ export class CodexConversationAdapter {
     codexBin;
     model;
     sandbox;
-    approvalPolicy;
+    legacyApprovalPolicy;
     codexProfile;
     addDirs;
     configOverrides;
@@ -21,7 +21,7 @@ export class CodexConversationAdapter {
         this.codexBin = opts.codexBin ?? 'codex';
         this.model = opts.model ?? null;
         this.sandbox = opts.sandbox ?? null;
-        this.approvalPolicy = opts.approvalPolicy ?? null;
+        this.legacyApprovalPolicy = opts.approvalPolicy ?? null;
         this.codexProfile = opts.codexProfile ?? null;
         this.addDirs = opts.addDirs ?? [];
         this.configOverrides = opts.configOverrides ?? [];
@@ -47,11 +47,11 @@ export class CodexConversationAdapter {
                 this.child.kill('SIGKILL');
         }, 5_000);
     }
-    async runTurn(prompt, onEvent, onLog) {
+    async runTurn(prompt, onEvent, onLog, imagePaths = []) {
         if (this.child) {
             throw new Error('A Codex turn is already in progress for this conversation');
         }
-        const args = this.buildArgs(prompt);
+        const args = this.buildArgs(prompt, imagePaths);
         const child = spawn(this.codexBin, args, {
             cwd: this.cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -141,7 +141,7 @@ export class CodexConversationAdapter {
             });
         });
     }
-    buildArgs(prompt) {
+    buildArgs(prompt, imagePaths = []) {
         if (this.threadId) {
             const args = ['exec', 'resume', '--json', '--skip-git-repo-check'];
             if (this.model) {
@@ -159,13 +159,16 @@ export class CodexConversationAdapter {
             if (this.bypassApprovalsAndSandbox) {
                 args.push('--dangerously-bypass-approvals-and-sandbox');
             }
+            for (const imagePath of imagePaths) {
+                args.push('-i', imagePath);
+            }
             args.push(this.threadId, prompt);
             return args;
         }
         const args = ['exec', '--json', '--color', 'never', '-C', this.cwd, '--skip-git-repo-check'];
         const execMode = resolveExecMode({
             sandbox: this.sandbox,
-            approvalPolicy: this.approvalPolicy,
+            approvalPolicy: this.legacyApprovalPolicy,
             fullAuto: this.fullAuto,
             bypassApprovalsAndSandbox: this.bypassApprovalsAndSandbox,
         });
@@ -190,6 +193,9 @@ export class CodexConversationAdapter {
         if (execMode.bypassApprovalsAndSandbox) {
             args.push('--dangerously-bypass-approvals-and-sandbox');
         }
+        for (const imagePath of imagePaths) {
+            args.push('-i', imagePath);
+        }
         args.push(prompt);
         return args;
     }
@@ -231,15 +237,18 @@ function resolveExecMode(input) {
     if (input.fullAuto) {
         return { fullAuto: true, bypassApprovalsAndSandbox: false };
     }
-    // Newer Codex CLI releases no longer accept --ask-for-approval for `exec`.
-    // Preserve the old Canon example (`--sandbox workspace-write --ask-for-approval never`)
-    // by translating it to the supported `--full-auto` mode.
-    if (input.approvalPolicy === 'never' &&
-        (input.sandbox === 'workspace-write' || input.sandbox == null)) {
+    if (shouldTranslateLegacyApprovalMode(input)) {
         return { fullAuto: true, bypassApprovalsAndSandbox: false };
     }
     return { fullAuto: false, bypassApprovalsAndSandbox: false };
 }
+function shouldTranslateLegacyApprovalMode(input) {
+    // Newer Codex CLI releases no longer accept --ask-for-approval for `exec`.
+    // Keep the compatibility shim isolated here so the rest of the adapter only
+    // deals with the supported execution switches.
+    return input.approvalPolicy === 'never'
+        && (input.sandbox === 'workspace-write' || input.sandbox == null);
+}
 function isIgnorableCodexLog(line) {
     return [
         'Reading additional input from stdin...',

package/dist/host-runtime.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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/claude-code-plugin/src/host-runtime.ts`. If you change the
+ * behavior here, update that copy too and adjust the shared golden
+ * fixture test (`packages/codex-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 are
+ * referenced by short placeholders — their actual bytes are delivered to the
+ * host as native vision/media inputs (Codex `-i <file>`, Anthropic image
+ * blocks). 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 args carry the
+ * file path 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,170 @@
+/**
+ * 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/claude-code-plugin/src/host-runtime.ts`. If you change the
+ * behavior here, update that copy too and adjust the shared golden
+ * fixture test (`packages/codex-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 are
+ * referenced by short placeholders — their actual bytes are delivered to the
+ * host as native vision/media inputs (Codex `-i <file>`, Anthropic image
+ * blocks). 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 args carry the
+ * file path 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

@@ -3,7 +3,9 @@ import { setDefaultResultOrder } from 'node:dns';
 setDefaultResultOrder('ipv4first');
 import { randomUUID } from 'node:crypto';
 import { parseArgs } from 'node:util';
-import { buildParticipationHistorySnapshot, buildBehaviorPolicyLines, buildConfiguredWorkspaceOptions, buildPublicWorkspaceOptions, ExecutionEnvironmentError, isEnabledFlag, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfile, initRTDBAuth, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseLock, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, writeSessionState, writeTurnState, } from '@canonmsg/core';
+import { getCodexImagePath, materializeMessageMedia, } from '@canonmsg/agent-sdk';
+import { buildConfiguredWorkspaceOptions, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, isEnabledFlag, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfile, initRTDBAuth, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseLock, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, writeSessionState, writeTurnState, } from '@canonmsg/core';
+import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
 import { clearStoredThreadId, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
@@ -37,71 +39,35 @@ function normalizeRuntimeTurnState(value) {
     return null;
 }
 async function publishAgentRuntime(agentId, runtime) {
-    await rtdbWrite(`/agent-runtime/${agentId}`, {
-        clientType: 'codex',
-        hostMode: true,
-        ...runtime,
-        updatedAt: { '.sv': 'timestamp' },
-    });
+    await publishHostAgentRuntime(agentId, 'codex', runtime);
 }
 async function loadSessionConfig(conversationId, agentId) {
-    const raw = await rtdbRead(`/session-config/${conversationId}/${agentId}`);
-    return readSessionWorkspaceConfig(raw);
+    return loadHostSessionConfig({ conversationId, agentId });
+}
+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,
     });
 }
 function buildCanonPrompt(input) {
-    return [
-        'You are connected to Canon messaging through a Codex 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: 'Codex',
+        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}]`;
-    }
-    return content || '[Empty message]';
+function renderInboundContent(message, materialized) {
+    return renderCanonHostInboundContent(message, materialized);
 }
 function summarizeCommand(command) {
     const trimmed = command.trim();
@@ -173,31 +139,10 @@ async function main() {
     const sessions = new Map();
     const pendingSessionCreations = 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;
-        }
-    }
+    const { getConversationMeta } = createConversationMetadataLoader({
+        client,
+        conversationCache,
+    });
     async function loadSenderRuntimeState(conversationId, senderId) {
         try {
             const [turnState, sessionState] = await Promise.all([
@@ -210,25 +155,21 @@ async function main() {
             return null;
         }
     }
-    async function loadParticipantContext(input) {
-        const [conversation, recentMessages] = await Promise.all([
+    async function loadHydratedInboundContext(input) {
+        const [conversation, page] = await Promise.all([
             getConversationMeta(input.conversationId),
-            client.getMessages(input.conversationId, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT).catch(() => []),
+            input.hydratedPage
+                ? Promise.resolve(input.hydratedPage)
+                : 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 writeState(session) {
         writeSessionState(session.conversationId, agentId, {
@@ -309,12 +250,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 sessionCwd = environment.cwd;
@@ -371,8 +316,8 @@ async function main() {
             pendingSessionCreations.delete(conversationId);
         }
     }
-    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false) {
-        const nextPrompt = { prompt, intent, sourceMessageId, markAccepted };
+    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false, imagePaths = []) {
+        const nextPrompt = { prompt, intent, sourceMessageId, markAccepted, imagePaths };
         if (toFront) {
             session.queue.unshift(nextPrompt);
         }
@@ -384,15 +329,39 @@ async function main() {
         void runNextTurn(session);
     }
     async function enqueueInboundMessage(input) {
-        const content = renderInboundContent(input.message);
-        const conversation = await getConversationMeta(input.conversationId);
-        const behavior = input.behavior ?? conversation?.behavior;
-        const participantContext = await loadParticipantContext({
+        let materialized = [];
+        if (input.message.id) {
+            try {
+                materialized = await materializeMessageMedia({
+                    id: input.message.id,
+                    attachments: input.message.attachments,
+                    imageUrl: input.message.imageUrl ?? null,
+                    audioUrl: input.message.audioUrl ?? null,
+                    audioDurationMs: input.message.audioDurationMs ?? null,
+                }, { agentId, conversationId: input.conversationId });
+            }
+            catch (error) {
+                console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to materialize media:`, error instanceof Error ? error.message : error);
+            }
+        }
+        const imagePaths = materialized
+            .map((attachment) => getCodexImagePath(attachment))
+            .filter((path) => path !== null);
+        const content = renderInboundContent(input.message, materialized);
+        const hydrated = await loadHydratedInboundContext({
             conversationId: input.conversationId,
             message: input.message,
             senderName: input.senderName,
             isOwner: input.isOwner,
+            hydratedPage: input.hydratedPage,
         });
+        const behavior = input.behavior ?? hydrated.behavior;
+        const workSessions = hydrated.hydratedFromPage
+            ? hydrated.workSessions
+            : Array.isArray(input.workSessions)
+                ? input.workSessions
+                : hydrated.workSessions;
+        const participantContext = hydrated.participantContext;
         const autoReply = decideAutoReply(participantContext, behavior);
         if (!autoReply.allow) {
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Suppressed auto-reply: ${autoReply.reason}`);
@@ -418,16 +387,18 @@ async function main() {
             conversationId: input.conversationId,
             participantContext,
             behavior,
+            workSession: input.message.workSession,
+            workSessions,
         });
         if (session.running && deliveryIntent === 'interrupt') {
-            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted);
+            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths);
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Interrupting current turn for explicit human send-now`);
             await session.adapter.interrupt().catch(() => { });
             clearStreaming(input.conversationId);
             client.setTyping(input.conversationId, false).catch(() => { });
             return;
         }
-        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted);
+        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths);
     }
     async function runNextTurn(session) {
         if (session.running || session.closed)
@@ -453,6 +424,7 @@ async function main() {
             updatedAt: { '.sv': 'timestamp' },
         }).catch(() => { });
         try {
+            const turnImagePaths = nextTurn.imagePaths ?? [];
             const result = await session.adapter.runTurn(nextTurn.prompt, (event) => {
                 session.lastActivity = Date.now();
                 if (event.type === 'thread.started') {
@@ -486,7 +458,7 @@ async function main() {
                 }
             }, (line) => {
                 console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] ${line}`);
-            });
+            }, turnImagePaths);
             if (result.threadId) {
                 saveStoredThreadId(agentId, session.conversationId, session.cwd, result.threadId);
             }
@@ -563,10 +535,14 @@ async function main() {
     }
     let controlStopped = false;
     let streamConnected = false;
+    const hostAvailableExecutionModes = allowWorktrees
+        ? [...EXECUTION_ENVIRONMENT_MODES]
+        : ['locked'];
     let runtimeDescriptor = {
         defaultWorkspaceId: workspaceOptions[0]?.id,
         ...(typeof args.model === 'string' ? { defaultModel: args.model } : {}),
         availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+        availableExecutionModes: hostAvailableExecutionModes,
     };
     const publishRuntimeHeartbeat = async () => {
         if (!streamConnected)
@@ -589,6 +565,7 @@ async function main() {
                     senderName: message.senderName || message.senderId,
                     isOwner: message.isOwner ?? (ownerId != null && message.senderId === ownerId),
                     behavior: payload.behavior,
+                    workSessions: payload.workSessions,
                 });
             },
             onConnected: () => {
@@ -609,12 +586,14 @@ async function main() {
             defaultWorkspaceId: workspaceOptions[0]?.id,
             ...(typeof args.model === 'string' ? { defaultModel: args.model } : {}),
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     catch {
         runtimeDescriptor = {
             defaultWorkspaceId: workspaceOptions[0]?.id,
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     try {
@@ -650,6 +629,8 @@ async function main() {
                 senderName: latestMessage.senderId,
                 isOwner: ownerId != null && latestMessage.senderId === ownerId,
                 behavior: latestPage.behavior,
+                workSessions: latestPage.workSessions,
+                hydratedPage: latestPage,
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/host.js",
@@ -22,7 +22,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/core": "^0.5.0"
+    "@canonmsg/agent-sdk": "^0.8.0",
+    "@canonmsg/core": "^0.7.0"
   },
   "engines": {
     "node": ">=18.0.0"