@canonmsg/backend-contracts 2.3.0 → 4.0.0

package/dist/verbContract.d.ts

@@ -67,6 +67,12 @@ export declare const VERB_ID_PATTERNS: {
     readonly actionId: "^[A-Za-z0-9_.:-]{1,80}$";
     readonly questionId: "^[A-Za-z0-9_.:-]{1,120}$";
     readonly sessionRuleToolPattern: "^[\\w.*:-]{1,128}$";
+    readonly runtimeCorrelationValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+    readonly runtimeMethod: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+    readonly runtimeOptionValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+    readonly workspaceOptionId: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+    readonly runtimeHandleKey: "^[A-Za-z0-9_.:-]{1,80}$";
+    readonly runtimeControlId: "^[A-Za-z0-9_-]{1,80}$";
 };
 /**
  * Server-enforced limits, single-sourced. Each value cites its enforcement
@@ -134,6 +140,9 @@ export declare const VERB_LIMITS: {
     readonly nativeKeys: 24;
     readonly nativeValueChars: 256;
     readonly nativeHandles: 16;
+    /** Initial agent-session setup carried by send_to. */
+    readonly sessionConfigValues: 24;
+    readonly sessionConfigValueChars: 256;
     /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
     readonly minTimeoutMs: 1000;
     /** input/card/plan ceiling (30 minutes). */
@@ -181,6 +190,50 @@ export type VerbSessionSelection = {
     mode: 'specific';
     conversationId: string;
 };
+/**
+ * Public setup policy for the target agent session. Every value is a stable
+ * runtime-advertised option id, never a label, prompt, path, or other free
+ * text. The server also validates each selection against the target's live
+ * descriptor before creating a session.
+ */
+export interface VerbSessionConfig {
+    model?: string;
+    permissionMode?: string;
+    effort?: string;
+    runtimeControlValues?: Record<string, string>;
+    workspaceId?: string;
+    executionMode?: 'worktree' | 'locked';
+}
+/**
+ * Bounded runtime correlation carried in the public wire envelope. These are
+ * opaque identifiers only; workspace paths, commands, prompts, summaries,
+ * and model labels belong in encrypted content or owner-local runtime state.
+ */
+export interface VerbNativeMetadata {
+    runtime?: string;
+    method?: string;
+    requestId?: string;
+    provider?: string;
+    origin?: string;
+    surface?: string;
+    threadId?: string;
+    turnId?: string;
+    runId?: string;
+    itemId?: string;
+    toolCallId?: string;
+    approvalId?: string;
+    pluginId?: string;
+    sessionKey?: string;
+    nodeId?: string;
+    handles?: Record<string, string>;
+}
+export declare const VERB_NATIVE_METADATA_KEYS: readonly ["runtime", "method", "requestId", "provider", "origin", "surface", "threadId", "turnId", "runId", "itemId", "toolCallId", "approvalId", "pluginId", "sessionKey", "nodeId", "handles"];
+/**
+ * Keep only the typed, content-free runtime correlation contract. Invalid or
+ * unknown fields are omitted on compatibility REST paths; canon.verb-wire.v1
+ * rejects the same fields through its strict JSON Schema.
+ */
+export declare function normalizeVerbNativeMetadata(value: unknown): VerbNativeMetadata | undefined;
 export interface VerbMediaAttachment {
     kind: 'image' | 'audio' | 'video' | 'file';
     /** Must come from /media/upload (Canon storage) or the GIF picker — server allowlisted. */
@@ -242,7 +295,7 @@ export interface SendToInput {
     /** Only meaningful for user targets that are agents. Default: continue_or_create. */
     sessionSelection?: VerbSessionSelection;
     /** Coding-agent session setup; only applied when the target is an agent. */
-    sessionConfig?: Record<string, unknown> | null;
+    sessionConfig?: VerbSessionConfig | null;
     messageOptions?: VerbMessageOptions;
 }
 export type SendToResult = {
@@ -308,7 +361,7 @@ export interface RequestInputInput {
     secretName?: string;
     sensitive?: boolean;
     responseUserId?: string;
-    native?: Record<string, unknown>;
+    native?: VerbNativeMetadata;
     turnId?: string;
     /** Relative deadline; server ceiling is VERB_LIMITS.maxTimeoutMs (30 min). */
     timeoutMs?: number;
@@ -376,7 +429,7 @@ export interface RequestApprovalInput {
     category?: VerbApprovalCategory;
     details?: VerbApprovalDetail[];
     diff?: VerbUnifiedDiff;
-    native?: Record<string, unknown>;
+    native?: VerbNativeMetadata;
     runtimeId?: string;
     turnId?: string;
     responseUserId?: string;
@@ -455,7 +508,7 @@ export interface SendCardInput {
     conversationId?: string;
     card: VerbRuntimeCard;
     cardId?: string;
-    native?: Record<string, unknown>;
+    native?: VerbNativeMetadata;
     runtimeId?: string;
     turnId?: string;
 }
@@ -719,6 +772,9 @@ export declare const CANON_VERB_LIMITS_ARTIFACT: {
         readonly nativeKeys: 24;
         readonly nativeValueChars: 256;
         readonly nativeHandles: 16;
+        /** Initial agent-session setup carried by send_to. */
+        readonly sessionConfigValues: 24;
+        readonly sessionConfigValueChars: 256;
         /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
         readonly minTimeoutMs: 1000;
         /** input/card/plan ceiling (30 minutes). */
@@ -746,6 +802,12 @@ export declare const CANON_VERB_LIMITS_ARTIFACT: {
         readonly actionId: "^[A-Za-z0-9_.:-]{1,80}$";
         readonly questionId: "^[A-Za-z0-9_.:-]{1,120}$";
         readonly sessionRuleToolPattern: "^[\\w.*:-]{1,128}$";
+        readonly runtimeCorrelationValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+        readonly runtimeMethod: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+        readonly runtimeOptionValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+        readonly workspaceOptionId: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+        readonly runtimeHandleKey: "^[A-Za-z0-9_.:-]{1,80}$";
+        readonly runtimeControlId: "^[A-Za-z0-9_-]{1,80}$";
     };
     readonly byteSemantics: {
         readonly 'send_to.text': "utf8_bytes<=messageTextBytes";

package/dist/verbContract.js

@@ -67,6 +67,12 @@ export const VERB_ID_PATTERNS = {
     actionId: '^[A-Za-z0-9_.:-]{1,80}$',
     questionId: '^[A-Za-z0-9_.:-]{1,120}$',
     sessionRuleToolPattern: '^[\\w.*:-]{1,128}$',
+    runtimeCorrelationValue: '^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$',
+    runtimeMethod: '^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$',
+    runtimeOptionValue: '^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$',
+    workspaceOptionId: '^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$',
+    runtimeHandleKey: '^[A-Za-z0-9_.:-]{1,80}$',
+    runtimeControlId: '^[A-Za-z0-9_-]{1,80}$',
 };
 /**
  * Server-enforced limits, single-sourced. Each value cites its enforcement
@@ -134,6 +140,9 @@ export const VERB_LIMITS = {
     nativeKeys: 24,
     nativeValueChars: 256,
     nativeHandles: 16,
+    /** Initial agent-session setup carried by send_to. */
+    sessionConfigValues: 24,
+    sessionConfigValueChars: 256,
     /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
     minTimeoutMs: 1000,
     /** input/card/plan ceiling (30 minutes). */
@@ -181,6 +190,65 @@ export const CANON_VERB_NAMES = [
     'list_contact_requests',
     'list_conversations',
 ];
+export const VERB_NATIVE_METADATA_KEYS = [
+    'runtime',
+    'method',
+    'requestId',
+    'provider',
+    'origin',
+    'surface',
+    'threadId',
+    'turnId',
+    'runId',
+    'itemId',
+    'toolCallId',
+    'approvalId',
+    'pluginId',
+    'sessionKey',
+    'nodeId',
+    'handles',
+];
+const VERB_NATIVE_STRING_KEYS = VERB_NATIVE_METADATA_KEYS.filter((key) => key !== 'handles');
+const RUNTIME_CORRELATION_VALUE_PATTERN = new RegExp(VERB_ID_PATTERNS.runtimeCorrelationValue);
+const RUNTIME_METHOD_PATTERN = new RegExp(VERB_ID_PATTERNS.runtimeMethod);
+const RUNTIME_HANDLE_KEY_PATTERN = new RegExp(VERB_ID_PATTERNS.runtimeHandleKey);
+function isPlainRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+/**
+ * Keep only the typed, content-free runtime correlation contract. Invalid or
+ * unknown fields are omitted on compatibility REST paths; canon.verb-wire.v1
+ * rejects the same fields through its strict JSON Schema.
+ */
+export function normalizeVerbNativeMetadata(value) {
+    if (!isPlainRecord(value))
+        return undefined;
+    const native = {};
+    for (const key of VERB_NATIVE_STRING_KEYS) {
+        const raw = value[key];
+        if (typeof raw !== 'string')
+            continue;
+        const normalized = raw.trim();
+        const pattern = key === 'method'
+            ? RUNTIME_METHOD_PATTERN
+            : RUNTIME_CORRELATION_VALUE_PATTERN;
+        if (pattern.test(normalized))
+            native[key] = normalized;
+    }
+    if (isPlainRecord(value.handles)) {
+        const handles = {};
+        for (const [key, raw] of Object.entries(value.handles).slice(0, VERB_LIMITS.nativeHandles)) {
+            if (!RUNTIME_HANDLE_KEY_PATTERN.test(key) || typeof raw !== 'string')
+                continue;
+            const normalized = raw.trim();
+            if (RUNTIME_CORRELATION_VALUE_PATTERN.test(normalized))
+                handles[key] = normalized;
+        }
+        if (Object.keys(handles).length > 0)
+            native.handles = handles;
+    }
+    return Object.keys(native).length > 0 ? native : undefined;
+}
 /**
  * Error code on the 400 a create_group receives when NO member is directly
  * addable (approval-required members can only be invited to an existing

package/dist/verbSchemas.d.ts

@@ -28,6 +28,146 @@
  *   endpoints validate against these schemas directly).
  */
 import { type CanonVerbName } from './verbContract.js';
+export declare const VERB_NATIVE_METADATA_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly description: string;
+    readonly maxProperties: 24;
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly runtime: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly method: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly requestId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly provider: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly origin: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly surface: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly threadId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly turnId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly runId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly itemId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly toolCallId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly approvalId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly pluginId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly sessionKey: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly nodeId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly handles: {
+            readonly type: "object";
+            readonly maxProperties: 16;
+            readonly propertyNames: {
+                readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+            };
+            readonly additionalProperties: {
+                readonly type: "string";
+                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                readonly maxLength: 256;
+            };
+        };
+    };
+};
+export declare const VERB_SESSION_CONFIG_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly description: string;
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly model: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly permissionMode: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly effort: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly workspaceId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly executionMode: {
+            readonly enum: readonly ["worktree", "locked"];
+        };
+        readonly runtimeControlValues: {
+            readonly type: "object";
+            readonly maxProperties: 24;
+            readonly propertyNames: {
+                readonly pattern: "^[A-Za-z0-9_-]{1,80}$";
+                readonly not: {
+                    readonly enum: readonly ["model", "workspace", "executionMode", "permissionMode", "effort", "interrupt", "runtimeControlValues", "updatedAt", "updatedBy"];
+                };
+            };
+            readonly additionalProperties: {
+                readonly type: "string";
+                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                readonly maxLength: 256;
+            };
+        };
+    };
+};
 export declare const CANON_VERBS_JSON_SCHEMA: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://canonmsg.com/schemas/canon.verbs.v1.json";
@@ -372,7 +512,142 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
         readonly native: {
             readonly type: "object";
             readonly description: string;
-            readonly additionalProperties: true;
+            readonly maxProperties: 24;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly runtime: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly method: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly requestId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly provider: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly origin: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly surface: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly threadId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly turnId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly runId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly itemId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly approvalId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly pluginId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly sessionKey: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly nodeId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly handles: {
+                    readonly type: "object";
+                    readonly maxProperties: 16;
+                    readonly propertyNames: {
+                        readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+                    };
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                        readonly maxLength: 256;
+                    };
+                };
+            };
+        };
+        readonly sessionConfig: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly model: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly permissionMode: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly effort: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly workspaceId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly executionMode: {
+                    readonly enum: readonly ["worktree", "locked"];
+                };
+                readonly runtimeControlValues: {
+                    readonly type: "object";
+                    readonly maxProperties: 24;
+                    readonly propertyNames: {
+                        readonly pattern: "^[A-Za-z0-9_-]{1,80}$";
+                        readonly not: {
+                            readonly enum: readonly ["model", "workspace", "executionMode", "permissionMode", "effort", "interrupt", "runtimeControlValues", "updatedAt", "updatedBy"];
+                        };
+                    };
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                        readonly maxLength: 256;
+                    };
+                };
+            };
         };
         readonly send_to_input: {
             readonly type: "object";
@@ -413,7 +688,11 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                     $ref: string;
                 };
                 readonly sessionConfig: {
-                    readonly type: readonly ["object", "null"];
+                    readonly oneOf: readonly [{
+                        $ref: string;
+                    }, {
+                        readonly type: "null";
+                    }];
                     readonly description: string;
                 };
                 readonly messageOptions: {

package/dist/verbSchemas.js

@@ -247,12 +247,89 @@ const runtimeCardDef = {
         blocks: { type: 'array', minItems: 1, maxItems: VERB_LIMITS.cardServerBlocks },
     },
 };
-const nativeDef = {
+const runtimeCorrelationValueDef = {
+    type: 'string',
+    pattern: VERB_ID_PATTERNS.runtimeCorrelationValue,
+    maxLength: VERB_LIMITS.nativeValueChars,
+};
+const runtimeMethodDef = {
+    type: 'string',
+    pattern: VERB_ID_PATTERNS.runtimeMethod,
+    maxLength: VERB_LIMITS.nativeValueChars,
+};
+export const VERB_NATIVE_METADATA_JSON_SCHEMA = {
     type: 'object',
-    description: `Runtime correlation handles (<= ${VERB_LIMITS.nativeKeys} keys, string values <= `
-        + `${VERB_LIMITS.nativeValueChars} chars or a nested handles map <= ${VERB_LIMITS.nativeHandles}; `
-        + 'functions/src/api/interactionKinds.ts normalizeNative).',
-    additionalProperties: true,
+    description: 'Content-free runtime correlation ids. Commands, paths, prompts, summaries, '
+        + 'and model labels are not permitted in this public envelope.',
+    maxProperties: VERB_LIMITS.nativeKeys,
+    additionalProperties: false,
+    properties: {
+        runtime: runtimeCorrelationValueDef,
+        method: runtimeMethodDef,
+        requestId: runtimeCorrelationValueDef,
+        provider: runtimeCorrelationValueDef,
+        origin: runtimeCorrelationValueDef,
+        surface: runtimeCorrelationValueDef,
+        threadId: runtimeCorrelationValueDef,
+        turnId: runtimeCorrelationValueDef,
+        runId: runtimeCorrelationValueDef,
+        itemId: runtimeCorrelationValueDef,
+        toolCallId: runtimeCorrelationValueDef,
+        approvalId: runtimeCorrelationValueDef,
+        pluginId: runtimeCorrelationValueDef,
+        sessionKey: runtimeCorrelationValueDef,
+        nodeId: runtimeCorrelationValueDef,
+        handles: {
+            type: 'object',
+            maxProperties: VERB_LIMITS.nativeHandles,
+            propertyNames: { pattern: VERB_ID_PATTERNS.runtimeHandleKey },
+            additionalProperties: runtimeCorrelationValueDef,
+        },
+    },
+};
+const sessionConfigValueDef = {
+    type: 'string',
+    pattern: VERB_ID_PATTERNS.runtimeOptionValue,
+    maxLength: VERB_LIMITS.sessionConfigValueChars,
+};
+export const VERB_SESSION_CONFIG_JSON_SCHEMA = {
+    type: 'object',
+    description: 'Typed setup policy for an agent target. Values are stable runtime-advertised '
+        + 'option ids and are validated against the target descriptor before session creation; '
+        + 'labels, prompts, workspace paths, and arbitrary fields are not permitted.',
+    additionalProperties: false,
+    properties: {
+        model: sessionConfigValueDef,
+        permissionMode: sessionConfigValueDef,
+        effort: sessionConfigValueDef,
+        workspaceId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.workspaceOptionId,
+            maxLength: VERB_LIMITS.sessionConfigValueChars,
+        },
+        executionMode: { enum: ['worktree', 'locked'] },
+        runtimeControlValues: {
+            type: 'object',
+            maxProperties: VERB_LIMITS.sessionConfigValues,
+            propertyNames: {
+                pattern: VERB_ID_PATTERNS.runtimeControlId,
+                not: {
+                    enum: [
+                        'model',
+                        'workspace',
+                        'executionMode',
+                        'permissionMode',
+                        'effort',
+                        'interrupt',
+                        'runtimeControlValues',
+                        'updatedAt',
+                        'updatedBy',
+                    ],
+                },
+            },
+            additionalProperties: sessionConfigValueDef,
+        },
+    },
 };
 const timeoutFields = (maxMs, ceilingNote) => ({
     timeoutMs: {
@@ -308,7 +385,7 @@ const send_to_input = {
         },
         sessionSelection: REF('sessionSelection'),
         sessionConfig: {
-            type: ['object', 'null'],
+            oneOf: [REF('sessionConfig'), { type: 'null' }],
             description: 'Coding-agent session setup (model/permissionMode/effort/workspaceId/executionMode); '
                 + 'only applied to agent targets, stripped for humans.',
         },
@@ -1000,7 +1077,8 @@ export const CANON_VERBS_JSON_SCHEMA = {
         unifiedDiff: unifiedDiffDef,
         sessionRule: sessionRuleDef,
         runtimeCard: runtimeCardDef,
-        native: nativeDef,
+        native: VERB_NATIVE_METADATA_JSON_SCHEMA,
+        sessionConfig: VERB_SESSION_CONFIG_JSON_SCHEMA,
         send_to_input,
         send_to_result,
         request_input_input,