@canonmsg/claude-code-plugin 0.32.0 → 0.34.0

package/dist/server.js

@@ -16,8 +16,10 @@ import { ApprovalHttpServer } from './approval-server.js';
 import { renderClaudeInboundContent } from './canon-user-content.js';
 import { runCli } from '@canonmsg/core';
 import { parseReplyArgs, parseSendMessageArgs, parseSetTypingArgs, } from './mcp-args.js';
-import { OWNER_BOUND_CANON_COMMUNICATION_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, stampSendToTurnComplete, } from '@canonmsg/agent-tools';
-const OWNER_BOUND_COMMUNICATION_VERBS = new Set(OWNER_BOUND_CANON_COMMUNICATION_VERBS);
+import { canonVerbToolDefinitions, createCanonCommunicationBinding, executeCanonVerbTool, isCanonToolVerb, isCommunicateReplacedVerb, } from '@canonmsg/agent-tools';
+import { isProactiveCommunicationEnabled } from './communication-policy.js';
+import { InboundReplyAuthority, InboundReplyAuthorityError, } from './inbound-reply-authority.js';
+import { AgentContextState } from './agent-context-state.js';
 const HELP = `canon-channel-server — Claude Code MCP channel server for Canon
 
 USAGE
@@ -32,13 +34,12 @@ phone-controlled local sessions, use canon-claude instead.`;
 // ── MCP server ─────────────────────────────────────────────────────────
 const server = new Server({ name: 'canon-channel', version: '0.1.0' }, {
     capabilities: {
-        tools: {},
+        tools: { listChanged: true },
         experimental: { 'claude/channel': {} },
     },
 });
 let client = null;
 let stream = null;
-let agentContext = null;
 let approvalManager = null;
 let approvalServer = null;
 let rtdb = null;
@@ -46,10 +47,33 @@ const conversationCache = new Map();
 const TURN_COMPLETE_METADATA = {
     turnSemantics: 'turn_complete',
 };
+const communicationBinding = createCanonCommunicationBinding();
+const inboundReplyAuthority = new InboundReplyAuthority();
+const agentContextState = new AgentContextState(() => {
+    void server.sendToolListChanged().catch((error) => {
+        console.error(`[canon] Failed to refresh communication tools: ${error instanceof Error ? error.message : error}`);
+    });
+});
 /** Last owner-visible conversation to route approval cards into. */
 let approvalConversationId = null;
 /** Whether the message that most recently triggered work came from the owner. */
 let triggerIsOwner = true;
+const INBOUND_SOURCE_PROPERTY = {
+    type: 'string',
+    description: 'The source_message_id from the inbound Canon channel metadata',
+};
+function requireInboundSource(conversationId, sourceMessageId) {
+    if (typeof conversationId !== 'string'
+        || !conversationId
+        || typeof sourceMessageId !== 'string'
+        || !sourceMessageId) {
+        return null;
+    }
+    return { conversationId, sourceMessageId };
+}
+function replyAuthorityError() {
+    return toolArgumentError('This action must target the exact current inbound Canon message and may only reply once.');
+}
 function getPrimaryAttachment(message) {
     const attachment = message.attachments?.[0];
     if (attachment?.url)
@@ -66,118 +90,144 @@ function toolArgumentError(error) {
     };
 }
 // ── Tool definitions ───────────────────────────────────────────────────
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-        {
-            name: 'reply',
-            description: 'Reply to a Canon conversation',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    conversation_id: {
-                        type: 'string',
-                        description: 'The conversation ID to reply to',
-                    },
-                    text: {
-                        type: 'string',
-                        description: 'Message text to send',
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    await agentContextState.ready;
+    return {
+        tools: [
+            {
+                name: 'reply',
+                description: 'Reply to the current inbound Canon conversation',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        conversation_id: {
+                            type: 'string',
+                            description: 'The conversation ID to reply to',
+                        },
+                        source_message_id: INBOUND_SOURCE_PROPERTY,
+                        text: {
+                            type: 'string',
+                            description: 'Message text to send',
+                        },
                     },
+                    required: ['conversation_id', 'source_message_id', 'text'],
                 },
-                required: ['conversation_id', 'text'],
             },
-        },
-        {
-            name: 'send_message',
-            description: 'Send a message to a Canon conversation (supports text, images, audio, video, files)',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    conversation_id: {
-                        type: 'string',
-                        description: 'The conversation ID',
-                    },
-                    text: {
-                        type: 'string',
-                        description: 'Message text',
-                    },
-                    content_type: {
-                        type: 'string',
-                        enum: ['text', 'image', 'audio', 'video', 'file'],
-                        description: 'Content type (default: text)',
-                    },
-                    image_url: {
-                        type: 'string',
-                        description: 'Image URL (when content_type is image)',
-                    },
-                    audio_url: {
-                        type: 'string',
-                        description: 'Audio URL (when content_type is audio)',
-                    },
-                    video_url: {
-                        type: 'string',
-                        description: 'Video URL (when content_type is video)',
-                    },
-                    file_url: {
-                        type: 'string',
-                        description: 'File URL (when content_type is file)',
-                    },
-                    media_path: {
-                        type: 'string',
-                        description: 'Local image/audio/video/file path to upload and send',
-                    },
-                    file_name: {
-                        type: 'string',
-                        description: 'Optional display filename for file attachments',
-                    },
-                    mime_type: {
-                        type: 'string',
-                        description: 'Optional MIME type for media_path uploads',
-                    },
-                    duration_ms: {
-                        type: 'number',
-                        description: 'Optional audio duration in milliseconds for media_path uploads',
+            {
+                name: 'send_message',
+                description: 'Reply with text or media in the current inbound Canon conversation',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        conversation_id: {
+                            type: 'string',
+                            description: 'The conversation ID',
+                        },
+                        source_message_id: INBOUND_SOURCE_PROPERTY,
+                        text: {
+                            type: 'string',
+                            description: 'Message text',
+                        },
+                        content_type: {
+                            type: 'string',
+                            enum: ['text', 'image', 'audio', 'video', 'file'],
+                            description: 'Content type (default: text)',
+                        },
+                        image_url: {
+                            type: 'string',
+                            description: 'Image URL (when content_type is image)',
+                        },
+                        audio_url: {
+                            type: 'string',
+                            description: 'Audio URL (when content_type is audio)',
+                        },
+                        video_url: {
+                            type: 'string',
+                            description: 'Video URL (when content_type is video)',
+                        },
+                        file_url: {
+                            type: 'string',
+                            description: 'File URL (when content_type is file)',
+                        },
+                        media_path: {
+                            type: 'string',
+                            description: 'Local image/audio/video/file path to upload and send',
+                        },
+                        file_name: {
+                            type: 'string',
+                            description: 'Optional display filename for file attachments',
+                        },
+                        mime_type: {
+                            type: 'string',
+                            description: 'Optional MIME type for media_path uploads',
+                        },
+                        duration_ms: {
+                            type: 'number',
+                            description: 'Optional audio duration in milliseconds for media_path uploads',
+                        },
                     },
+                    required: ['conversation_id', 'source_message_id'],
                 },
-                required: ['conversation_id'],
             },
-        },
-        {
-            name: 'list_agents',
-            description: 'List registered Canon agent profiles and their lock status',
-            inputSchema: {
-                type: 'object',
-                properties: {},
+            {
+                name: 'list_agents',
+                description: 'List registered Canon agent profiles and their lock status',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
             },
-        },
-        {
-            name: 'set_typing',
-            description: 'Show or hide typing indicator in a Canon conversation',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    conversation_id: {
-                        type: 'string',
-                        description: 'The conversation ID',
-                    },
-                    typing: {
-                        type: 'boolean',
-                        description: 'Whether to show typing indicator',
-                    },
-                    status: {
-                        type: 'string',
-                        enum: ['typing', 'thinking'],
-                        description: 'Typing status (default: typing). Use "thinking" when processing/reasoning.',
+            {
+                name: 'set_typing',
+                description: 'Show or hide typing indicator in a Canon conversation',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        conversation_id: {
+                            type: 'string',
+                            description: 'The conversation ID',
+                        },
+                        source_message_id: INBOUND_SOURCE_PROPERTY,
+                        typing: {
+                            type: 'boolean',
+                            description: 'Whether to show typing indicator',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['typing', 'thinking'],
+                            description: 'Typing status (default: typing). Use "thinking" when processing/reasoning.',
+                        },
                     },
+                    required: ['conversation_id', 'source_message_id', 'typing'],
                 },
-                required: ['conversation_id', 'typing'],
             },
-        },
-        // Canonical verbs — projections of canon.verbs.v1 (@canonmsg/agent-tools).
-        // Channel mode owns no turn, so `no_reply` is an ack-only no-op here: the
-        // standalone session has no final delivery for it to suppress.
-        ...canonVerbToolDefinitions().filter((definition) => !OWNER_BOUND_COMMUNICATION_VERBS.has(definition.name)),
-    ],
-}));
+            // Canonical verbs — projections of canon.verbs.v1 (@canonmsg/agent-tools).
+            // Channel mode owns no turn, so `no_reply` is an ack-only no-op here: the
+            // standalone session has no final delivery for it to suppress.
+            ...canonVerbToolDefinitions({ compactCommunication: true }).map((tool) => ({
+                ...tool,
+                description: `${tool.description} Use source_message_id from the inbound Canon channel metadata.`,
+                inputSchema: {
+                    ...tool.inputSchema,
+                    properties: {
+                        ...(tool.inputSchema.properties ?? {}),
+                        source_message_id: INBOUND_SOURCE_PROPERTY,
+                    },
+                    required: [
+                        ...new Set([
+                            ...(tool.inputSchema.required ?? []),
+                            'conversationId',
+                            'source_message_id',
+                        ]),
+                    ],
+                },
+            })),
+            ...(isProactiveCommunicationEnabled(agentContextState.current?.outboundPolicy)
+                ? communicationBinding.tools
+                : []),
+        ],
+    };
+});
 // ── Tool handlers ──────────────────────────────────────────────────────
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!client) {
@@ -192,10 +242,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const parsed = parseReplyArgs(args);
             if (!parsed.ok)
                 return toolArgumentError(parsed.error);
-            const { conversationId, text } = parsed.value;
-            const result = await client.sendMessage(conversationId, text, {
-                metadata: TURN_COMPLETE_METADATA,
-            });
+            const { conversationId, sourceMessageId, text } = parsed.value;
+            let result;
+            try {
+                result = await inboundReplyAuthority.sendVisibleReply({ conversationId, sourceMessageId }, (replyAuthority) => client.sendMessage(conversationId, text, {
+                    metadata: {
+                        ...TURN_COMPLETE_METADATA,
+                        turnId: `claude-channel:${sourceMessageId}`,
+                    },
+                    ...(replyAuthority ? { replyAuthority } : {}),
+                }));
+            }
+            catch (error) {
+                if (error instanceof InboundReplyAuthorityError)
+                    return replyAuthorityError();
+                throw error;
+            }
             return {
                 content: [
                     {
@@ -209,25 +271,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const parsed = parseSendMessageArgs(args);
             if (!parsed.ok)
                 return toolArgumentError(parsed.error);
-            const { conversationId, text, contentType, imageUrl, audioUrl, videoUrl, fileUrl, mediaPath, fileName, mimeType, durationMs, } = parsed.value;
+            const { conversationId, sourceMessageId, text, contentType, imageUrl, audioUrl, videoUrl, fileUrl, mediaPath, fileName, mimeType, durationMs, } = parsed.value;
             const opts = {};
             const metadata = TURN_COMPLETE_METADATA;
-            if (mediaPath) {
-                const result = await sendMediaFileMessage(client, conversationId, mediaPath, text, {
-                    ...(fileName ? { fileName } : {}),
-                    ...(mimeType ? { mimeType } : {}),
-                    ...(durationMs != null ? { durationMs } : {}),
-                    metadata,
-                });
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Message sent (${result.messageId})`,
-                        },
-                    ],
-                };
-            }
             if (contentType === 'image' && imageUrl) {
                 opts.contentType = 'image';
                 opts.attachments = [{ kind: 'image', url: imageUrl }];
@@ -268,7 +314,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ...(opts.metadata ?? {}),
                 ...metadata,
             };
-            const result = await client.sendMessage(conversationId, text, opts);
+            let result;
+            try {
+                result = await inboundReplyAuthority.sendVisibleReply({ conversationId, sourceMessageId }, (replyAuthority) => mediaPath
+                    ? sendMediaFileMessage(client, conversationId, mediaPath, text, {
+                        ...(fileName ? { fileName } : {}),
+                        ...(mimeType ? { mimeType } : {}),
+                        ...(durationMs != null ? { durationMs } : {}),
+                        metadata: {
+                            ...metadata,
+                            turnId: `claude-channel:${sourceMessageId}`,
+                        },
+                        ...(replyAuthority ? { replyAuthority } : {}),
+                    })
+                    : client.sendMessage(conversationId, text, {
+                        ...opts,
+                        metadata: {
+                            ...metadata,
+                            turnId: `claude-channel:${sourceMessageId}`,
+                        },
+                        ...(replyAuthority ? { replyAuthority } : {}),
+                    }));
+            }
+            catch (error) {
+                if (error instanceof InboundReplyAuthorityError)
+                    return replyAuthorityError();
+                throw error;
+            }
             return {
                 content: [
                     {
@@ -302,7 +374,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const parsed = parseSetTypingArgs(args);
             if (!parsed.ok)
                 return toolArgumentError(parsed.error);
-            const { conversationId, typing, status } = parsed.value;
+            const { conversationId, sourceMessageId, typing, status } = parsed.value;
+            if (!inboundReplyAuthority.validate({ conversationId, sourceMessageId })) {
+                return replyAuthorityError();
+            }
             await client.setTyping(conversationId, typing, status);
             return {
                 content: [
@@ -315,13 +390,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         default: {
             const name = request.params.name;
-            if (OWNER_BOUND_COMMUNICATION_VERBS.has(name)) {
-                return toolArgumentError(`${name} requires an owner-authored Canon turn and is unavailable in standalone channel mode.`);
+            if (communicationBinding.isToolName(name)) {
+                if (!isProactiveCommunicationEnabled(agentContextState.current?.outboundPolicy)) {
+                    return toolArgumentError('Outbound communication is not enabled by the agent operator.');
+                }
+                const result = await communicationBinding.execute(client, name, args);
+                return {
+                    content: result.content.map((item) => ({ type: 'text', text: item.text })),
+                    ...(result.isError ? { isError: true } : {}),
+                };
             }
-            if (isCanonToolVerb(name)) {
+            if (isCanonToolVerb(name) && !isCommunicateReplacedVerb(name)) {
                 const rawArgs = args && typeof args === 'object' ? { ...args } : {};
-                const verbArgs = name === 'send_to' ? stampSendToTurnComplete(rawArgs) : rawArgs;
-                const verbResult = await executeCanonVerbTool(client, name, verbArgs);
+                const source = requireInboundSource(rawArgs.conversationId, rawArgs.source_message_id);
+                delete rawArgs.source_message_id;
+                if (!source)
+                    return replyAuthorityError();
+                if (name === 'no_reply') {
+                    if (!inboundReplyAuthority.consumeNoReply(source))
+                        return replyAuthorityError();
+                }
+                else if (!inboundReplyAuthority.validate(source)) {
+                    return replyAuthorityError();
+                }
+                const verbResult = await executeCanonVerbTool(client, name, rawArgs, {
+                    context: {
+                        conversationId: source.conversationId,
+                        sourceMessageId: source.sourceMessageId,
+                    },
+                });
                 return {
                     content: verbResult.content.map((item) => ({ type: 'text', text: item.text })),
                     ...(verbResult.isError ? { isError: true } : {}),
@@ -340,6 +437,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function handleInboundMessage(payload) {
     const m = payload.message;
     const convo = conversationCache.get(payload.conversationId);
+    const pendingReplySource = inboundReplyAuthority.beginInbound({
+        conversationId: payload.conversationId,
+        sourceMessageId: m.id,
+        ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
+    });
     // Track turn provenance separately from the owner-visible approval route.
     // Non-owner direct chats do not include the owner, so approval cards still go
     // to the last owner conversation while the hook bypasses cached session rules.
@@ -358,9 +460,11 @@ async function handleInboundMessage(payload) {
             return;
         }
     }
+    inboundReplyAuthority.authorize(pendingReplySource);
     // meta must be Record<string, string> — non-string values cause silent drops
     const meta = {
         conversation_id: payload.conversationId,
+        source_message_id: m.id,
         sender_id: m.senderId,
         sender_name: m.senderName || m.senderId,
         sender_type: m.senderType || 'human',
@@ -402,7 +506,7 @@ async function handleInboundMessage(payload) {
                 id: m.id,
                 attachments: m.attachments ?? [],
             }, {
-                agentId: agentContext?.agentId ?? 'claude-code',
+                agentId: agentContextState.current?.agentId ?? 'claude-code',
                 conversationId: payload.conversationId,
             });
         }
@@ -445,6 +549,7 @@ async function handleInboundMessage(payload) {
         console.error('[canon] Notification sent to Claude Code');
     }
     catch (err) {
+        inboundReplyAuthority.revoke(pendingReplySource);
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`[canon] Failed to send notification: ${msg}`);
     }
@@ -465,6 +570,7 @@ async function startChannel() {
         await verifyResolvedAgentEnvironment(resolvedRuntime);
     }
     catch (err) {
+        agentContextState.settleUnavailable();
         resolvedRuntime?.lockHandle?.release();
         console.error(err instanceof Error ? err.message : err);
         return;
@@ -476,18 +582,21 @@ async function startChannel() {
     // Get agent identity — try /agents/me first, fall back to /agents/auth-token
     let agentId;
     try {
-        agentContext = await client.getAgentMe();
-        agentId = agentContext.agentId;
-        console.error(`[canon] Connected as ${agentContext.displayName || agentId}`);
+        const context = await client.getAgentMe();
+        agentContextState.set(context);
+        agentId = context.agentId;
+        console.error(`[canon] Connected as ${context.displayName || agentId}`);
     }
     catch {
         // /agents/me may not be deployed — fall back to auth-token exchange
         try {
             const auth = await client.getAuthToken();
             agentId = auth.agentId;
+            agentContextState.settleUnavailable();
             console.error(`[canon] Authenticated as ${agentId}`);
         }
         catch (err) {
+            agentContextState.settleUnavailable();
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`[canon] Failed to authenticate: ${msg}`);
             return;
@@ -509,7 +618,7 @@ async function startChannel() {
         runtime: 'claude-code',
         profile,
         agentId,
-        agentName: agentContext?.displayName ?? profileAgentName,
+        agentName: agentContextState.current?.displayName ?? profileAgentName,
         cwd: process.cwd(),
         launchCommand: ['canon-channel-server'],
         pid: process.pid,
@@ -542,7 +651,7 @@ async function startChannel() {
         handler: {
             onMessage: handleInboundMessage,
             onAgentContext: (ctx) => {
-                agentContext = ctx;
+                agentContextState.set(ctx);
             },
             onConnected: () => {
                 console.error('[canon] SSE stream connected');
@@ -560,8 +669,8 @@ async function startChannel() {
         console.error(`[canon] SSE start error: ${msg}`);
     });
     // Start approval system
-    if (agentContext?.ownerId) {
-        approvalManager = new ApprovalManager(client, agentId, agentContext.ownerId);
+    if (agentContextState.current?.ownerId) {
+        approvalManager = new ApprovalManager(client, agentId, agentContextState.current.ownerId);
         approvalServer = new ApprovalHttpServer(approvalManager, () => approvalConversationId, {
             token: process.env.CANON_CLAUDE_APPROVAL_TOKEN,
             getIsOwnerTurn: () => triggerIsOwner,
@@ -586,9 +695,9 @@ export async function main() {
     // Graceful shutdown — release agent lock and clear session state
     const shutdown = () => {
         // Mark all conversations as inactive
-        if (agentContext) {
+        if (agentContextState.current) {
             for (const convoId of conversationCache.keys()) {
-                rtdb?.clearSessionState(convoId, agentContext.agentId).catch(() => { });
+                rtdb?.clearSessionState(convoId, agentContextState.current.agentId).catch(() => { });
             }
         }
         approvalManager?.dispose();

package/dist/session-state.d.ts

@@ -1,6 +1,6 @@
-import type { PermissionMode, SDKMessageOrigin, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { SDKMessageOrigin, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
 import type { DeliveryIntent, ModelOption, RuntimeStreamingPayload, TurnLifecycleState, TurnOutputBlock, TurnOutputSnapshot, TurnVerbosity } from '@canonmsg/core';
-import type { OwnerBoundCanonContactTarget } from '@canonmsg/agent-tools';
+import type { AgentReplyAuthorityV1 } from '@canonmsg/backend-contracts';
 import type { TurnArtifactRoutingDecision, TurnArtifactSnapshot } from '@canonmsg/coding-agent-host';
 export type ClaudeInputKind = 'seed' | 'canon';
 export type ClaudeArtifactRoutingMode = 'workspace-generated' | 'disabled';
@@ -24,8 +24,8 @@ export interface ClaudeInputEnvelope {
     turnKey: string;
     isOwnerTurn: boolean;
     requestingUserId: string | null;
-    /** Trusted contact-card target resolved from the owner message's reply. */
-    replyContactTarget?: OwnerBoundCanonContactTarget;
+    /** Opaque server capability; never rendered into the Claude prompt. */
+    replyAuthority: AgentReplyAuthorityV1 | null;
 }
 /**
  * The per-turn modes an inbound message resolves from its participant context,
@@ -34,6 +34,7 @@ export interface ClaudeInputEnvelope {
 export interface ClaudeTurnModes {
     artifactRoutingMode?: ClaudeArtifactRoutingMode;
     turnVerbosity?: TurnVerbosity;
+    replyAuthority?: AgentReplyAuthorityV1 | null;
 }
 export interface ClaudeRuntimeControlError {
     value: string;
@@ -105,7 +106,7 @@ export declare function createClaudeInputEnvelope(input: {
     artifactBaseline?: TurnArtifactSnapshot | null;
     isOwnerTurn?: boolean;
     requestingUserId?: string | null;
-    replyContactTarget?: OwnerBoundCanonContactTarget;
+    replyAuthority?: AgentReplyAuthorityV1 | null;
 }): ClaudeInputEnvelope;
 export declare function resolveClaudeTurnResponseRouting(turn: Pick<ClaudeInputEnvelope, 'kind' | 'isOwnerTurn' | 'requestingUserId'> | null | undefined, ownerId: string | null | undefined, ownerOnly?: boolean): {
     isOwnerTurn: boolean;
@@ -819,44 +820,3 @@ export declare function confirmClaudeInterrupt(input: {
     active: boolean;
     interrupt: () => Promise<unknown>;
 }): Promise<'confirmed' | 'defer'>;
-/** Requested session-control values from the control plane (raw, pre-validation). */
-export interface ClaudeSessionControlInput {
-    model?: string;
-    permissionMode?: string;
-    effort?: string;
-    ultracode?: string;
-}
-/** Mutable mirror of the live session's control state — mutated in place on success. */
-export interface ClaudeSessionControlState {
-    model?: string;
-    permissionMode?: string;
-    effort?: string;
-    ultracode?: string;
-}
-/**
- * Injected validators + side effects so the apply logic stays host-agnostic and
- * unit-testable. The host wires these to the live SDK query and its runtime
- * control-error bookkeeping; tests inject fakes.
- */
-export interface ClaudeSessionControlDeps {
-    state: ClaudeSessionControlState;
-    parsePermissionMode: (value: unknown) => PermissionMode | null;
-    normalizeEffort: (value: unknown) => string | undefined;
-    parseUltracode: (value: unknown) => string | undefined;
-    setModel: (model: string) => Promise<void>;
-    setPermissionMode: (mode: PermissionMode) => Promise<void>;
-    applyEffort: (level: string) => Promise<void>;
-    applyUltracode: (enabled: boolean) => Promise<void>;
-    setRuntimeControlError: (controlId: string, value: string, error: unknown) => void;
-    clearRuntimeControlError: (controlId: string) => void;
-    publishSnapshot: () => void;
-}
-/**
- * Apply a session-control request to the live Claude session. Mirrors the host's
- * control semantics (validation, only-if-different checks, error recording,
- * clear-on-success). Whenever a live op is invoked — on success OR caught
- * failure — publishSnapshot() is called exactly once so the app-subscribed
- * /agent-session snapshot converges immediately instead of waiting for the next
- * heartbeat. If nothing changed, publishSnapshot() is not called.
- */
-export declare function applyClaudeSessionControl(control: ClaudeSessionControlInput, deps: ClaudeSessionControlDeps): Promise<void>;