{ "$ref": "#/definitions/SessionEvent", "definitions": { "AbortData": { "type": "object", "properties": { "reason": { "$ref": "#/definitions/AbortReason", "description": "Finite reason code describing why the current turn was aborted" } }, "required": [ "reason" ], "additionalProperties": false, "description": "Turn abort information including the reason for termination", "title": "AbortData" }, "AbortEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "abort", "description": "Type discriminator. Always \"abort\"." }, "data": { "$ref": "#/definitions/AbortData", "description": "Turn abort information including the reason for termination" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"abort\". Turn abort information including the reason for termination", "title": "AbortEvent" }, "AbortReason": { "type": "string", "enum": [ "user_initiated", "remote_command", "user_abort", "autopilot_credit_limit" ], "description": "Finite reason code describing why the current turn was aborted", "title": "AbortReason", "x-enumDescriptions": { "user_initiated": "The local user requested the abort, for example by pressing Ctrl+C in the CLI.", "remote_command": "A remote command requested the abort.", "user_abort": "An MCP server delivered a user.abort notification.", "autopilot_credit_limit": "Autopilot stopped the run because the active objective reached its user-set --max-ai-credits limit." } }, "AssistantIdleData": { "type": "object", "properties": { "aborted": { "type": "boolean", "description": "True when the preceding agentic loop was cancelled via abort signal" } }, "additionalProperties": false, "description": "Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred", "title": "AssistantIdleData" }, "AssistantIdleEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.idle", "description": "Type discriminator. Always \"assistant.idle\"." }, "data": { "$ref": "#/definitions/AssistantIdleData", "description": "Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.idle\". Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred", "title": "AssistantIdleEvent" }, "AssistantIntentData": { "type": "object", "properties": { "intent": { "type": "string", "description": "Short description of what the agent is currently doing or planning to do" } }, "required": [ "intent" ], "additionalProperties": false, "description": "Agent intent description for current activity or plan", "title": "AssistantIntentData" }, "AssistantIntentEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.intent", "description": "Type discriminator. Always \"assistant.intent\"." }, "data": { "$ref": "#/definitions/AssistantIntentData", "description": "Agent intent description for current activity or plan" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.intent\". Agent intent description for current activity or plan", "title": "AssistantIntentEvent" }, "AssistantMessageData": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Unique identifier for this assistant message" }, "model": { "type": "string", "description": "Model that produced this assistant message, if known" }, "content": { "type": "string", "description": "The assistant's text response content" }, "toolRequests": { "type": "array", "items": { "$ref": "#/definitions/AssistantMessageToolRequest", "description": "A tool invocation request from the assistant" }, "description": "Tool invocations requested by the assistant in this message" }, "reasoningOpaque": { "type": "string", "description": "Opaque/encrypted extended thinking data from Anthropic models. Session-bound and stripped on resume." }, "reasoningText": { "type": "string", "description": "Readable reasoning text from the model's extended thinking" }, "reasoningWireField": { "type": "string", "description": "OpenAI-compatible wire field the provider used for reasoning (e.g. reasoning_content/reasoning). Populated only when non-canonical, so the dialect round-trips across turns." }, "encryptedContent": { "type": "string", "description": "Encrypted reasoning content from OpenAI models. Session-bound and stripped on resume." }, "phase": { "type": "string", "description": "Generation phase for phased-output models (e.g., thinking vs. response phases)" }, "chunkIndex": { "type": "integer", "minimum": 0, "description": "Zero-based position of this message within its model call's response. Absent when the response was not split into chunks." }, "chunkCount": { "type": "integer", "minimum": 1, "description": "Total messages the model call's response was split into, one per reasoning boundary. Absent for a single-message response; the last chunk is the one where chunkIndex is chunkCount - 1." }, "outputTokens": { "type": "integer", "minimum": 0, "description": "Actual output token count from the API response (completion_tokens), used for accurate token accounting" }, "interactionId": { "type": "string", "description": "CAPI interaction ID for correlating this message with upstream telemetry" }, "requestId": { "type": "string", "description": "GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs" }, "clientRequestId": { "type": "string", "description": "Client-minted request id (x-request-id header) echoed by the server. Distinct from requestId (x-github-request-id) and serviceRequestId (x-copilot-service-request-id)." }, "serviceRequestId": { "type": "string", "description": "Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation" }, "rte": { "type": "boolean" }, "apiCallId": { "type": "string", "description": "Provider's completion / response identifier; shared across all chunks of a single API call. Used to group multi-chunk assistant utterances." }, "serverTools": { "$ref": "#/definitions/AssistantMessageServerTools", "description": "Neutral provider-tagged server-side tool-use payload (tool search, advisor) for verbatim round-tripping" }, "turnId": { "type": "string", "description": "Identifier for the agent loop turn that produced this message, matching the corresponding assistant.turn_start event" }, "parentToolCallId": { "type": "string", "description": "Tool call ID of the parent tool invocation when this event originates from a sub-agent", "deprecated": true }, "citations": { "$ref": "#/definitions/Citations", "description": "Provider-agnostic citations linking spans of this message's content to the sources that support them. Experimental; only populated when citation emission is enabled.", "stability": "experimental" } }, "required": [ "messageId", "content" ], "additionalProperties": false, "description": "Assistant response containing text content, optional tool requests, and interaction metadata", "title": "AssistantMessageData" }, "AssistantMessageDeltaData": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Message ID this delta belongs to, matching the corresponding assistant.message event" }, "deltaContent": { "type": "string", "description": "Incremental text chunk to append to the message content" }, "parentToolCallId": { "type": "string", "description": "Tool call ID of the parent tool invocation when this event originates from a sub-agent", "deprecated": true } }, "required": [ "messageId", "deltaContent" ], "additionalProperties": false, "description": "Streaming assistant message delta for incremental response updates", "title": "AssistantMessageDeltaData" }, "AssistantMessageDeltaEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.message_delta", "description": "Type discriminator. Always \"assistant.message_delta\"." }, "data": { "$ref": "#/definitions/AssistantMessageDeltaData", "description": "Streaming assistant message delta for incremental response updates" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.message_delta\". Streaming assistant message delta for incremental response updates", "title": "AssistantMessageDeltaEvent" }, "AssistantMessageEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.message", "description": "Type discriminator. Always \"assistant.message\"." }, "data": { "$ref": "#/definitions/AssistantMessageData", "description": "Assistant response containing text content, optional tool requests, and interaction metadata" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.message\". Assistant response containing text content, optional tool requests, and interaction metadata", "title": "AssistantMessageEvent" }, "AssistantMessageServerTools": { "type": "object", "properties": { "provider": { "type": "string" }, "items": { "type": "array", "items": { "x-opaque-json": true } }, "functionCallNamespaces": { "type": "object", "additionalProperties": { "type": "string" } }, "rawContentBlocks": { "type": "array", "items": { "x-opaque-json": true } }, "advisorModel": { "type": "string" } }, "required": [ "provider" ], "additionalProperties": false, "description": "Neutral provider-tagged server-side tool-use payload (tool search, advisor) for verbatim round-tripping", "title": "AssistantMessageServerTools", "stability": "experimental" }, "AssistantMessageStartData": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Message ID this start event belongs to, matching subsequent deltas and assistant.message" }, "phase": { "type": "string", "description": "Generation phase this message belongs to for phased-output models" } }, "required": [ "messageId" ], "additionalProperties": false, "description": "Streaming assistant message start metadata", "title": "AssistantMessageStartData" }, "AssistantMessageStartEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.message_start", "description": "Type discriminator. Always \"assistant.message_start\"." }, "data": { "$ref": "#/definitions/AssistantMessageStartData", "description": "Streaming assistant message start metadata" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.message_start\". Streaming assistant message start metadata", "title": "AssistantMessageStartEvent" }, "AssistantMessageToolRequest": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Unique identifier for this tool call" }, "name": { "type": "string", "description": "Name of the tool being invoked" }, "arguments": { "description": "Arguments to pass to the tool, format depends on the tool", "x-opaque-json": true }, "type": { "$ref": "#/definitions/AssistantMessageToolRequestType", "description": "Tool call type: \"function\" for standard tool calls, \"custom\" for grammar-based tool calls. Defaults to \"function\" when absent." }, "toolTitle": { "type": "string", "description": "Human-readable display title for the tool" }, "mcpServerName": { "type": "string", "description": "Name of the MCP server hosting this tool, when the tool is an MCP tool" }, "mcpToolName": { "type": "string", "description": "Original tool name on the MCP server, when the tool is an MCP tool" }, "intentionSummary": { "type": [ "string", "null" ], "description": "Resolved intention summary describing what this specific call does" } }, "required": [ "toolCallId", "name" ], "additionalProperties": false, "description": "A tool invocation request from the assistant", "title": "AssistantMessageToolRequest" }, "AssistantMessageToolRequestType": { "type": "string", "enum": [ "function", "custom" ], "description": "Tool call type: \"function\" for standard tool calls, \"custom\" for grammar-based tool calls. Defaults to \"function\" when absent.", "title": "AssistantMessageToolRequestType", "x-enumDescriptions": { "function": "Standard function-style tool call.", "custom": "Custom grammar-based tool call." } }, "AssistantReasoningData": { "type": "object", "properties": { "reasoningId": { "type": "string", "description": "Unique identifier for this reasoning block" }, "content": { "type": "string", "description": "The complete extended thinking text from the model" }, "rte": { "type": "boolean" } }, "required": [ "reasoningId", "content" ], "additionalProperties": false, "description": "Assistant reasoning content for timeline display with complete thinking text", "title": "AssistantReasoningData" }, "AssistantReasoningDeltaData": { "type": "object", "properties": { "reasoningId": { "type": "string", "description": "Reasoning block ID this delta belongs to, matching the corresponding assistant.reasoning event" }, "deltaContent": { "type": "string", "description": "Incremental text chunk to append to the reasoning content" } }, "required": [ "reasoningId", "deltaContent" ], "additionalProperties": false, "description": "Streaming reasoning delta for incremental extended thinking updates", "title": "AssistantReasoningDeltaData" }, "AssistantReasoningDeltaEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.reasoning_delta", "description": "Type discriminator. Always \"assistant.reasoning_delta\"." }, "data": { "$ref": "#/definitions/AssistantReasoningDeltaData", "description": "Streaming reasoning delta for incremental extended thinking updates" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.reasoning_delta\". Streaming reasoning delta for incremental extended thinking updates", "title": "AssistantReasoningDeltaEvent" }, "AssistantReasoningEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.reasoning", "description": "Type discriminator. Always \"assistant.reasoning\"." }, "data": { "$ref": "#/definitions/AssistantReasoningData", "description": "Assistant reasoning content for timeline display with complete thinking text" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.reasoning\". Assistant reasoning content for timeline display with complete thinking text", "title": "AssistantReasoningEvent" }, "AssistantServerToolProgressData": { "type": "object", "properties": { "outputIndex": { "type": "integer", "description": "Position of the hosted tool call in the response output. Stable across the call's lifecycle events (unlike the provider's per-event item id, which CAPI rotates), so the host keys the live in-progress row on it." }, "kind": { "type": "string", "description": "Kind of hosted server tool that is running. Only `web_search` is emitted today." }, "status": { "type": "string", "description": "Lifecycle status of the hosted call: `in_progress`, `searching`, or `completed`." } }, "required": [ "outputIndex", "kind", "status" ], "additionalProperties": false, "description": "Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message", "title": "AssistantServerToolProgressData" }, "AssistantServerToolProgressEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.server_tool_progress", "description": "Type discriminator. Always \"assistant.server_tool_progress\"." }, "data": { "$ref": "#/definitions/AssistantServerToolProgressData", "description": "Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.server_tool_progress\". Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message", "title": "AssistantServerToolProgressEvent" }, "AssistantStreamingDeltaData": { "type": "object", "properties": { "totalResponseSizeBytes": { "type": "integer", "minimum": 0, "description": "Cumulative total bytes received from the streaming response so far" } }, "required": [ "totalResponseSizeBytes" ], "additionalProperties": false, "description": "Streaming response progress with cumulative byte count", "title": "AssistantStreamingDeltaData" }, "AssistantStreamingDeltaEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.streaming_delta", "description": "Type discriminator. Always \"assistant.streaming_delta\"." }, "data": { "$ref": "#/definitions/AssistantStreamingDeltaData", "description": "Streaming response progress with cumulative byte count" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.streaming_delta\". Streaming response progress with cumulative byte count", "title": "AssistantStreamingDeltaEvent" }, "AssistantToolCallDeltaData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Tool call ID this delta belongs to, matching the corresponding assistant.message tool request" }, "toolName": { "type": "string", "description": "Name of the tool being invoked, when known from the stream" }, "toolType": { "$ref": "#/definitions/AssistantMessageToolRequestType", "description": "Tool call type, when known from the stream" }, "inputDelta": { "type": "string", "description": "Raw provider tool input fragment to append for this tool call. Function/tool-use providers stream serialized JSON argument text (so newlines inside JSON string values may appear as escaped `\\n` until the accumulated JSON is parsed); custom tool calls stream raw custom input." } }, "required": [ "toolCallId", "inputDelta" ], "additionalProperties": false, "description": "Streaming tool-call input delta for incremental tool-call updates", "title": "AssistantToolCallDeltaData" }, "AssistantToolCallDeltaEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.tool_call_delta", "description": "Type discriminator. Always \"assistant.tool_call_delta\"." }, "data": { "$ref": "#/definitions/AssistantToolCallDeltaData", "description": "Streaming tool-call input delta for incremental tool-call updates" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.tool_call_delta\". Streaming tool-call input delta for incremental tool-call updates", "title": "AssistantToolCallDeltaEvent" }, "AssistantTurnEndData": { "type": "object", "properties": { "turnId": { "type": "string", "description": "Identifier of the turn that has ended, matching the corresponding assistant.turn_start event" }, "model": { "type": "string", "description": "Model identifier used for this turn, when known" } }, "required": [ "turnId" ], "additionalProperties": false, "description": "Turn completion metadata including the turn identifier", "title": "AssistantTurnEndData" }, "AssistantTurnEndEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.turn_end", "description": "Type discriminator. Always \"assistant.turn_end\"." }, "data": { "$ref": "#/definitions/AssistantTurnEndData", "description": "Turn completion metadata including the turn identifier" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.turn_end\". Turn completion metadata including the turn identifier", "title": "AssistantTurnEndEvent" }, "AssistantTurnRetryData": { "type": "object", "properties": { "turnId": { "type": "string", "description": "Identifier of the turn whose model inference is being retried" }, "model": { "type": "string", "description": "Model identifier used for this retry, when known" }, "reason": { "type": "string", "description": "Provider or runtime classification that caused the retry, when known" } }, "required": [ "turnId" ], "additionalProperties": false, "description": "Metadata for an additional model inference attempt within an existing assistant turn", "title": "AssistantTurnRetryData" }, "AssistantTurnRetryEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.turn_retry", "description": "Type discriminator. Always \"assistant.turn_retry\"." }, "data": { "$ref": "#/definitions/AssistantTurnRetryData", "description": "Metadata for an additional model inference attempt within an existing assistant turn" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.turn_retry\". Metadata for an additional model inference attempt within an existing assistant turn", "title": "AssistantTurnRetryEvent", "visibility": "internal" }, "AssistantTurnStartData": { "type": "object", "properties": { "turnId": { "type": "string", "description": "Identifier for this turn within the agentic loop, typically a stringified turn number" }, "model": { "type": "string", "description": "Model identifier used for this turn, when known" }, "interactionId": { "type": "string", "description": "CAPI interaction ID for correlating this turn with upstream telemetry" } }, "required": [ "turnId" ], "additionalProperties": false, "description": "Turn initialization metadata including identifier and interaction tracking", "title": "AssistantTurnStartData" }, "AssistantTurnStartEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.turn_start", "description": "Type discriminator. Always \"assistant.turn_start\"." }, "data": { "$ref": "#/definitions/AssistantTurnStartData", "description": "Turn initialization metadata including identifier and interaction tracking" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.turn_start\". Turn initialization metadata including identifier and interaction tracking", "title": "AssistantTurnStartEvent" }, "AssistantUsageApiEndpoint": { "type": "string", "enum": [ "/chat/completions", "/v1/messages", "/responses", "ws:/responses" ], "description": "API endpoint used for this model call, matching CAPI supported_endpoints vocabulary", "title": "AssistantUsageApiEndpoint", "x-enumDescriptions": { "/chat/completions": "Chat Completions API endpoint.", "/v1/messages": "Anthropic Messages API endpoint.", "/responses": "Responses API endpoint.", "ws:/responses": "WebSocket Responses API endpoint." } }, "AssistantUsageCopilotUsage": { "type": "object", "properties": { "tokenDetails": { "type": "array", "items": { "$ref": "#/definitions/AssistantUsageCopilotUsageTokenDetail", "description": "Token usage detail for a single billing category" }, "description": "Itemized token usage breakdown", "visibility": "internal" }, "totalNanoAiu": { "type": "number", "minimum": 0, "description": "Total cost in nano-AI units for this request" } }, "required": [ "totalNanoAiu" ], "additionalProperties": false, "description": "Per-request cost and usage data from the CAPI copilot_usage response field", "title": "AssistantUsageCopilotUsage" }, "AssistantUsageCopilotUsageTokenDetail": { "type": "object", "properties": { "batchSize": { "type": "integer", "minimum": 0, "description": "Number of tokens in this billing batch" }, "costPerBatch": { "type": "integer", "minimum": 0, "description": "Cost per batch of tokens" }, "tokenCount": { "type": "integer", "minimum": 0, "description": "Total token count for this entry" }, "tokenType": { "type": "string", "description": "Token category (e.g., \"input\", \"output\")" } }, "required": [ "batchSize", "costPerBatch", "tokenCount", "tokenType" ], "additionalProperties": false, "description": "Token usage detail for a single billing category", "title": "AssistantUsageCopilotUsageTokenDetail" }, "AssistantUsageData": { "type": "object", "properties": { "model": { "type": "string", "description": "Model identifier used for this API call" }, "inputTokens": { "type": "integer", "minimum": 0, "description": "Number of input tokens consumed" }, "outputTokens": { "type": "integer", "minimum": 0, "description": "Number of output tokens produced" }, "cacheReadTokens": { "type": "integer", "minimum": 0, "description": "Number of tokens read from prompt cache" }, "cacheWriteTokens": { "type": "integer", "minimum": 0, "description": "Number of tokens written to prompt cache" }, "cacheExpiresAt": { "type": "string", "format": "date-time", "description": "Updated prompt-cache expiration for this model call. Present only when the call establishes or refreshes known cache state." }, "reasoningTokens": { "type": "integer", "minimum": 0, "description": "Number of output tokens used for reasoning (e.g., chain-of-thought)" }, "cost": { "type": "number", "description": "Model multiplier cost for billing purposes", "stability": "experimental" }, "duration": { "type": "integer", "minimum": 0, "format": "duration", "description": "Duration of the API call in milliseconds" }, "timeToFirstTokenMs": { "type": "number", "minimum": 0, "format": "duration", "description": "Time to first token in milliseconds. Only available for streaming requests" }, "interTokenLatencyMs": { "type": "number", "minimum": 0, "format": "duration", "description": "Average inter-token latency in milliseconds. Only available for streaming requests" }, "initiator": { "type": "string", "description": "What initiated this API call (e.g., \"sub-agent\", \"mcp-sampling\"); absent for user-initiated calls" }, "interactionType": { "type": "string", "description": "Coarse classification of the interaction that produced this call, mirroring the session's per-request agent context (e.g. `conversation-agent`, `conversation-subagent`, `conversation-sampling`, `conversation-background`, `conversation-compaction`, `conversation-user`). Non-billing; lets consumers attribute a model call to a call class (e.g. sub-agent/sidekick) independently of the billing initiator. Absent when the runtime did not classify the request." }, "apiCallId": { "type": "string", "description": "Completion ID from the model provider (e.g., chatcmpl-abc123)" }, "providerCallId": { "type": "string", "description": "GitHub request tracing ID (x-github-request-id header) for server-side log correlation" }, "serviceRequestId": { "type": "string", "description": "Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation" }, "rte": { "type": "boolean" }, "apiEndpoint": { "$ref": "#/definitions/AssistantUsageApiEndpoint", "description": "API endpoint used for this model call, matching CAPI supported_endpoints vocabulary" }, "parentToolCallId": { "type": "string", "description": "Parent tool call ID when this usage originates from a sub-agent", "deprecated": true }, "quotaSnapshots": { "type": "object", "additionalProperties": { "$ref": "#/definitions/AssistantUsageQuotaSnapshot", "description": "Internal per-quota snapshot for assistant usage, including entitlement, consumed requests, overage, reset date, and remaining quota.", "visibility": "internal" }, "description": "Per-quota resource usage snapshots, keyed by quota identifier", "visibility": "internal" }, "copilotUsage": { "$ref": "#/definitions/AssistantUsageCopilotUsage", "description": "Per-request cost and usage data from the CAPI copilot_usage response field" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\")" }, "availableToolCount": { "type": "integer", "minimum": 0, "description": "Number of tools available to the model for this call", "visibility": "internal" }, "toolTokenCount": { "type": "integer", "minimum": 0, "description": "Number of tokens used by tool definitions for this call", "visibility": "internal" }, "numToolCalls": { "type": "integer", "minimum": 0, "description": "Number of tool calls returned by the model", "visibility": "internal" }, "toolCounts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Tool-call counts keyed by tool name", "visibility": "internal" }, "finishReason": { "type": "string", "description": "Finish reason reported by the model for this API call (e.g. \"stop\", \"length\", \"tool_calls\", \"content_filter\"). Normalized to OpenAI vocabulary; for Anthropic models a \"refusal\" stop reason maps to \"content_filter\"." }, "contentFilterTriggered": { "type": "boolean", "description": "Whether the model response was blocked or truncated by content filtering (finish_reason === 'content_filter'). For Anthropic models this corresponds to a 'refusal' stop reason." } }, "required": [ "model" ], "additionalProperties": false, "description": "LLM API call usage metrics including tokens, costs, quotas, and billing information", "title": "AssistantUsageData" }, "AssistantUsageEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "assistant.usage", "description": "Type discriminator. Always \"assistant.usage\"." }, "data": { "$ref": "#/definitions/AssistantUsageData", "description": "LLM API call usage metrics including tokens, costs, quotas, and billing information" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"assistant.usage\". LLM API call usage metrics including tokens, costs, quotas, and billing information", "title": "AssistantUsageEvent" }, "AssistantUsageQuotaSnapshot": { "type": "object", "properties": { "isUnlimitedEntitlement": { "type": "boolean", "description": "Whether the user has an unlimited usage entitlement", "visibility": "internal" }, "entitlementRequests": { "type": "integer", "minimum": -1, "description": "Total requests allowed by the entitlement", "visibility": "internal" }, "usedRequests": { "type": "integer", "minimum": 0, "description": "Number of requests already consumed", "visibility": "internal" }, "usageAllowedWithExhaustedQuota": { "type": "boolean", "description": "Whether usage is still permitted after quota exhaustion", "visibility": "internal" }, "overage": { "type": "number", "minimum": 0, "description": "Number of additional usage requests made this period", "visibility": "internal" }, "overageAllowedWithExhaustedQuota": { "type": "boolean", "description": "Whether additional usage is allowed when quota is exhausted", "visibility": "internal" }, "remainingPercentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "Percentage of quota remaining (0 to 100)", "visibility": "internal" }, "resetDate": { "type": "string", "format": "date-time", "description": "Date when the quota resets", "visibility": "internal" }, "hasQuota": { "type": "boolean", "description": "Whether the user currently has quota available for use", "visibility": "internal" }, "tokenBasedBilling": { "type": "boolean", "description": "Whether this snapshot uses token-based billing (AI-credits allocation)", "visibility": "internal" }, "overageEntitlement": { "type": "number", "minimum": 0, "description": "Pay-as-you-go additional-usage budget cap in AI credits (1 credit = $0.01); present only when CAPI emits a finite value", "visibility": "internal" } }, "required": [ "isUnlimitedEntitlement", "entitlementRequests", "usedRequests", "usageAllowedWithExhaustedQuota", "overage", "overageAllowedWithExhaustedQuota", "remainingPercentage" ], "additionalProperties": false, "description": "Internal per-quota snapshot for assistant usage, including entitlement, consumed requests, overage, reset date, and remaining quota.", "title": "AssistantUsageQuotaSnapshot", "visibility": "internal" }, "Attachment": { "anyOf": [ { "$ref": "#/definitions/AttachmentFile", "description": "File attachment" }, { "$ref": "#/definitions/AttachmentDirectory", "description": "Directory attachment" }, { "$ref": "#/definitions/AttachmentSelection", "description": "Code selection attachment from an editor" }, { "$ref": "#/definitions/AttachmentGitHubReference", "description": "GitHub issue, pull request, or discussion reference" }, { "$ref": "#/definitions/AttachmentGitHubCommit", "description": "Pointer to a GitHub commit." }, { "$ref": "#/definitions/AttachmentGitHubRelease", "description": "Pointer to a GitHub release." }, { "$ref": "#/definitions/AttachmentGitHubActionsJob", "description": "Pointer to a GitHub Actions job." }, { "$ref": "#/definitions/AttachmentGitHubRepository", "description": "Pointer to a GitHub repository." }, { "$ref": "#/definitions/AttachmentGitHubFileDiff", "description": "Pointer to a single-file diff. At least one of `head` and `base` must be present." }, { "$ref": "#/definitions/AttachmentGitHubTreeComparison", "description": "Pointer to a comparison between two git revisions." }, { "$ref": "#/definitions/AttachmentGitHubUrl", "description": "Generic GitHub URL reference." }, { "$ref": "#/definitions/AttachmentGitHubFile", "description": "Pointer to a file in a GitHub repository at a specific ref." }, { "$ref": "#/definitions/AttachmentGitHubSnippet", "description": "Pointer to a line range inside a file in a GitHub repository." }, { "$ref": "#/definitions/AttachmentBlob", "description": "Blob attachment with inline base64-encoded data" }, { "$ref": "#/definitions/AttachmentExtensionContext", "description": "Structured context contributed by an extension. Composer pills displayed in the host are forwarded back through session.send.attachments, then rendered into the model prompt as an XML block." } ], "description": "A user message attachment — a file, directory, code selection, blob, GitHub reference, GitHub-anchored pointer, or extension-supplied context payload", "title": "Attachment" }, "AttachmentBlob": { "type": "object", "properties": { "type": { "type": "string", "const": "blob", "description": "Attachment type discriminator" }, "data": { "type": "string", "description": "Base64-encoded content. Present on input and for external consumers; replaced by an internal `assetId` reference in persisted events when interned to a content-addressed asset.", "contentEncoding": "base64" }, "mimeType": { "type": "string", "description": "MIME type of the inline data" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" }, "assetId": { "type": "string", "description": "Internal: content-addressed id of the session.binary_asset event holding this attachment's model-facing bytes (e.g. \"sha256:...\"). Absent externally." }, "byteLength": { "type": "integer", "minimum": 0, "description": "Internal: decoded byte length of the attachment's model-facing bytes. Absent externally." }, "omittedReason": { "$ref": "#/definitions/OmittedBinaryOmittedReason", "description": "Internal: why model-facing bytes are absent from persistence. Absent externally." } }, "required": [ "type", "mimeType" ], "additionalProperties": false, "description": "Blob attachment with inline base64-encoded data", "title": "AttachmentBlob" }, "AttachmentDirectory": { "type": "object", "properties": { "type": { "type": "string", "const": "directory", "description": "Attachment type discriminator" }, "path": { "type": "string", "description": "Absolute directory path" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" }, "taggedFilesEntry": { "type": "string", "description": "Frozen rendered line this attachment contributed to the prompt block (e.g. \"* /path (12 items)\"). Captured at send time so resumed history reproduces the exact text the model saw, independent of later filesystem changes." } }, "required": [ "type", "path", "displayName" ], "additionalProperties": false, "description": "Directory attachment", "title": "AttachmentDirectory" }, "AttachmentExtensionContext": { "type": "object", "properties": { "type": { "type": "string", "const": "extension_context", "description": "Attachment type discriminator" }, "extensionId": { "type": "string", "description": "Owning extension identifier. Runtime-derived from the caller's connection when produced via session.extensions.sendAttachmentsToMessage; preserved verbatim on subsequent transports." }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier when the push was bound to a canvas instance" }, "instanceId": { "type": "string", "description": "Open canvas instance identifier when the push was bound to a canvas instance" }, "title": { "type": "string", "minLength": 1, "description": "Human-readable composer pill label" }, "payload": { "description": "Caller-supplied JSON payload", "x-opaque-json": true }, "capturedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp captured by the runtime when the push was accepted" } }, "required": [ "type", "extensionId", "title", "capturedAt" ], "additionalProperties": false, "description": "Structured context contributed by an extension. Composer pills displayed in the host are forwarded back through session.send.attachments, then rendered into the model prompt as an XML block.", "title": "AttachmentExtensionContext" }, "AttachmentFile": { "type": "object", "properties": { "type": { "type": "string", "const": "file", "description": "Attachment type discriminator" }, "path": { "type": "string", "description": "Absolute file path" }, "displayName": { "type": "string", "description": "User-facing display name for the attachment" }, "lineRange": { "$ref": "#/definitions/AttachmentFileLineRange", "description": "Optional line range to scope the attachment to a specific section of the file" }, "mimeType": { "type": "string", "description": "Internal: MIME type of the file's model-facing bytes (post-resize for images). Set when the file's bytes are interned to an asset. Absent externally." }, "assetId": { "type": "string", "description": "Internal: content-addressed id of the session.binary_asset event holding this attachment's model-facing bytes (e.g. \"sha256:...\"). Absent externally." }, "byteLength": { "type": "integer", "minimum": 0, "description": "Internal: decoded byte length of the attachment's model-facing bytes. Absent externally." }, "omittedReason": { "$ref": "#/definitions/OmittedBinaryOmittedReason", "description": "Internal: why model-facing bytes are absent from persistence. Absent externally." }, "taggedFilesEntry": { "type": "string", "description": "Frozen rendered line this attachment contributed to the prompt block (e.g. \"* /path (123 lines)\"). Captured at send time so resumed history reproduces the exact text the model saw, independent of later filesystem changes. Present only for attachments routed to (mutually exclusive with assetId, which marks bytes sent natively)." } }, "required": [ "type", "path", "displayName" ], "additionalProperties": false, "description": "File attachment", "title": "AttachmentFile" }, "AttachmentFileLineRange": { "type": "object", "properties": { "start": { "type": "integer", "exclusiveMinimum": 0, "description": "Start line number (1-based)" }, "end": { "type": "integer", "exclusiveMinimum": 0, "description": "End line number (1-based, inclusive)" } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "Optional line range to scope the attachment to a specific section of the file", "title": "AttachmentFileLineRange" }, "AttachmentGitHubActionsJob": { "type": "object", "properties": { "type": { "type": "string", "const": "github_actions_job", "description": "Attachment type discriminator" }, "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository the workflow run belongs to" }, "jobId": { "type": "integer", "exclusiveMinimum": 0, "description": "Job id within the workflow run" }, "jobName": { "type": "string", "description": "Display name of the job" }, "workflowName": { "type": "string", "description": "Display name of the workflow the job ran in" }, "url": { "type": "string", "description": "URL to the job on GitHub" }, "conclusion": { "type": "string", "description": "Terminal conclusion of the job when finished (e.g., success, failure, cancelled). Absent for in-progress jobs." } }, "required": [ "type", "repo", "jobId", "jobName", "workflowName", "url" ], "additionalProperties": false, "description": "Pointer to a GitHub Actions job.", "title": "AttachmentGitHubActionsJob" }, "AttachmentGitHubCommit": { "type": "object", "properties": { "type": { "type": "string", "const": "github_commit", "description": "Attachment type discriminator" }, "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository the commit belongs to" }, "oid": { "type": "string", "description": "Full commit SHA" }, "message": { "type": "string", "description": "First line of the commit message" }, "url": { "type": "string", "description": "URL to the commit on GitHub" } }, "required": [ "type", "repo", "oid", "message", "url" ], "additionalProperties": false, "description": "Pointer to a GitHub commit.", "title": "AttachmentGitHubCommit" }, "AttachmentGitHubFile": { "type": "object", "properties": { "type": { "type": "string", "const": "github_file", "description": "Attachment type discriminator" }, "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository the file lives in" }, "ref": { "type": "string", "description": "Git ref the file is read at (branch, tag, or commit SHA)" }, "path": { "type": "string", "description": "Repository-relative path to the file" }, "url": { "type": "string", "description": "URL to the file on GitHub" } }, "required": [ "type", "repo", "ref", "path", "url" ], "additionalProperties": false, "description": "Pointer to a file in a GitHub repository at a specific ref.", "title": "AttachmentGitHubFile" }, "AttachmentGitHubFileDiff": { "type": "object", "properties": { "type": { "type": "string", "const": "github_file_diff", "description": "Attachment type discriminator" }, "url": { "type": "string", "description": "URL to the diff on GitHub (e.g., a commit, compare, or PR-file URL)" }, "head": { "$ref": "#/definitions/AttachmentGitHubFileDiffSide", "description": "File location on the head side of the diff. Absent for deletions." }, "base": { "$ref": "#/definitions/AttachmentGitHubFileDiffSide", "description": "File location on the base side of the diff. Absent for additions." } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "Pointer to a single-file diff. At least one of `head` and `base` must be present.", "title": "AttachmentGitHubFileDiff" }, "AttachmentGitHubFileDiffSide": { "type": "object", "properties": { "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository the file lives in" }, "ref": { "type": "string", "description": "Git ref (branch, tag, or commit SHA) the file is read at" }, "path": { "type": "string", "description": "Repository-relative path to the file" } }, "required": [ "repo", "ref", "path" ], "additionalProperties": false, "description": "One side of a file diff (head or base)", "title": "AttachmentGitHubFileDiffSide" }, "AttachmentGitHubReference": { "type": "object", "properties": { "type": { "type": "string", "const": "github_reference", "description": "Attachment type discriminator" }, "number": { "type": "integer", "exclusiveMinimum": 0, "description": "Issue, pull request, or discussion number" }, "title": { "type": "string", "description": "Title of the referenced item" }, "referenceType": { "$ref": "#/definitions/AttachmentGitHubReferenceType", "description": "Type of GitHub reference" }, "state": { "type": "string", "description": "Current state of the referenced item (e.g., open, closed, merged)" }, "url": { "type": "string", "description": "URL to the referenced item on GitHub" } }, "required": [ "type", "number", "title", "referenceType", "state", "url" ], "additionalProperties": false, "description": "GitHub issue, pull request, or discussion reference", "title": "AttachmentGitHubReference" }, "AttachmentGitHubReferenceType": { "type": "string", "enum": [ "issue", "pr", "discussion" ], "description": "Type of GitHub reference", "title": "AttachmentGitHubReferenceType", "x-enumDescriptions": { "issue": "GitHub issue reference.", "pr": "GitHub pull request reference.", "discussion": "GitHub discussion reference." } }, "AttachmentGitHubRelease": { "type": "object", "properties": { "type": { "type": "string", "const": "github_release", "description": "Attachment type discriminator" }, "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository the release belongs to" }, "tagName": { "type": "string", "description": "Git tag the release is anchored to" }, "name": { "type": "string", "description": "Human-readable release name" }, "url": { "type": "string", "description": "URL to the release on GitHub" } }, "required": [ "type", "repo", "tagName", "name", "url" ], "additionalProperties": false, "description": "Pointer to a GitHub release.", "title": "AttachmentGitHubRelease" }, "AttachmentGitHubRepository": { "type": "object", "properties": { "type": { "type": "string", "const": "github_repository", "description": "Attachment type discriminator" }, "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository pointer" }, "url": { "type": "string", "description": "URL to the repository on GitHub" }, "description": { "type": "string", "description": "Short description of the repository" }, "ref": { "type": "string", "description": "Git ref this attachment is anchored at (branch, tag, or commit). When absent the default branch is implied." } }, "required": [ "type", "repo", "url" ], "additionalProperties": false, "description": "Pointer to a GitHub repository.", "title": "AttachmentGitHubRepository" }, "AttachmentGitHubSnippet": { "type": "object", "properties": { "type": { "type": "string", "const": "github_snippet", "description": "Attachment type discriminator" }, "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository the file lives in" }, "ref": { "type": "string", "description": "Git ref the file is read at (branch, tag, or commit SHA)" }, "path": { "type": "string", "description": "Repository-relative path to the file" }, "url": { "type": "string", "description": "URL to the snippet on GitHub (with line anchor)" }, "lineRange": { "$ref": "#/definitions/AttachmentFileLineRange", "description": "Line range the snippet covers" } }, "required": [ "type", "repo", "ref", "path", "url", "lineRange" ], "additionalProperties": false, "description": "Pointer to a line range inside a file in a GitHub repository.", "title": "AttachmentGitHubSnippet" }, "AttachmentGitHubTreeComparison": { "type": "object", "properties": { "type": { "type": "string", "const": "github_tree_comparison", "description": "Attachment type discriminator" }, "url": { "type": "string", "description": "URL to the comparison on GitHub" }, "base": { "$ref": "#/definitions/AttachmentGitHubTreeComparisonSide", "description": "Base side of the comparison" }, "head": { "$ref": "#/definitions/AttachmentGitHubTreeComparisonSide", "description": "Head side of the comparison" } }, "required": [ "type", "url", "base", "head" ], "additionalProperties": false, "description": "Pointer to a comparison between two git revisions.", "title": "AttachmentGitHubTreeComparison" }, "AttachmentGitHubTreeComparisonSide": { "type": "object", "properties": { "repo": { "$ref": "#/definitions/GitHubRepoRef", "description": "Repository the revision belongs to" }, "revision": { "type": "string", "description": "Git revision (branch, tag, or commit SHA)" } }, "required": [ "repo", "revision" ], "additionalProperties": false, "description": "One side of a tree comparison (head or base)", "title": "AttachmentGitHubTreeComparisonSide" }, "AttachmentGitHubUrl": { "type": "object", "properties": { "type": { "type": "string", "const": "github_url", "description": "Attachment type discriminator" }, "url": { "type": "string", "description": "URL to the GitHub resource" } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "Generic GitHub URL reference.", "title": "AttachmentGitHubUrl" }, "AttachmentSelection": { "type": "object", "properties": { "type": { "type": "string", "const": "selection", "description": "Attachment type discriminator" }, "filePath": { "type": "string", "description": "Absolute path to the file containing the selection" }, "displayName": { "type": "string", "description": "User-facing display name for the selection" }, "text": { "type": "string", "description": "The selected text content" }, "selection": { "$ref": "#/definitions/AttachmentSelectionDetails", "description": "Position range of the selection within the file" } }, "required": [ "type", "filePath", "displayName", "text", "selection" ], "additionalProperties": false, "description": "Code selection attachment from an editor", "title": "AttachmentSelection" }, "AttachmentSelectionDetails": { "type": "object", "properties": { "start": { "$ref": "#/definitions/AttachmentSelectionDetailsStart", "description": "Start position of the selection" }, "end": { "$ref": "#/definitions/AttachmentSelectionDetailsEnd", "description": "End position of the selection" } }, "required": [ "start", "end" ], "additionalProperties": false, "description": "Position range of the selection within the file", "title": "AttachmentSelectionDetails" }, "AttachmentSelectionDetailsEnd": { "type": "object", "properties": { "line": { "type": "integer", "minimum": 0, "description": "End line number (0-based)" }, "character": { "type": "integer", "minimum": 0, "description": "End character offset within the line (0-based)" } }, "required": [ "line", "character" ], "additionalProperties": false, "description": "End position of the selection", "title": "AttachmentSelectionDetailsEnd" }, "AttachmentSelectionDetailsStart": { "type": "object", "properties": { "line": { "type": "integer", "minimum": 0, "description": "Start line number (0-based)" }, "character": { "type": "integer", "minimum": 0, "description": "Start character offset within the line (0-based)" } }, "required": [ "line", "character" ], "additionalProperties": false, "description": "Start position of the selection", "title": "AttachmentSelectionDetailsStart" }, "AutoApprovalJudgeFailureReason": { "type": "string", "enum": [ "timeout", "abort", "empty_response", "model_error", "parse_error" ], "description": "Why the auto-approval judge produced no usable recommendation. Present only alongside an `error` recommendation, where the human-readable reason is a fixed string and therefore cannot distinguish these cases. Intended to make a judge failure reportable by a consumer that has no access to the host's logs.", "title": "AutoApprovalJudgeFailureReason", "x-enumDescriptions": { "timeout": "The judge model call exceeded its deadline.", "abort": "The judge model call was cancelled before it returned.", "empty_response": "The judge model call completed but returned no content.", "model_error": "The judge model call failed (for example a transport, authentication, or rate-limit error).", "parse_error": "The judge model replied, but the reply carried no ALLOW/DENY verdict." }, "stability": "experimental" }, "AutoApprovalRecommendation": { "type": "string", "enum": [ "approve", "requireApproval", "excluded", "error" ], "description": "Outcome of the auto-approval safety judge for a permission request. Present only when auto mode is enabled; its absence means the judge did not evaluate the request (auto mode was off).", "title": "AutoApprovalRecommendation", "x-enumDescriptions": { "approve": "The judge evaluated the request and recommends automatically approving it.", "requireApproval": "The judge evaluated the request and does not recommend auto-approving it; explicit approval is required. Whether that means prompting, denying, or something else is the consumer's decision.", "excluded": "Auto mode is enabled, but this request category is never auto-approvable (for example, sandbox-bypass requests), so the judge was not consulted.", "error": "The judge was consulted but did not return a usable recommendation, so the request requires explicit approval." }, "stability": "experimental" }, "AutoModeResolvedData": { "type": "object", "properties": { "chosenModel": { "type": "string", "description": "The concrete model the session will use after any intent refinement" }, "reasoningBucket": { "$ref": "#/definitions/AutoModeResolvedReasoningBucket", "description": "Coarse request-difficulty bucket, for explaining why a model was chosen (\"picked X because this looks like high-reasoning work\")" }, "categoryScores": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Per-category classifier scores (0-1) behind the bucket: the granular HYDRA capability scores (reasoning, code_gen, debugging, tool_use), or the binary needs_reasoning/no_reasoning scores when HYDRA didn't run. Lets clients show a breakdown rather than just the bucket." }, "predictedLabel": { "type": "string", "description": "The predicted classifier label (e.g. `needs_reasoning`), when available" }, "confidence": { "type": "number", "minimum": 0.0, "maximum": 1.0, "description": "Classifier confidence for the predicted label, when available" }, "candidateModels": { "type": "array", "items": { "type": "string" }, "description": "Ordered candidate model list the router returned, when not a fallback" }, "routingMethod": { "type": "string", "description": "The routing method the server applied, when Auto Intent ran" }, "availableModels": { "type": "array", "items": { "type": "string" }, "description": "Models offered to the router for this resolution" }, "fallback": { "type": "boolean", "description": "Whether the router fell back to the standard Auto selection" }, "fallbackReason": { "type": "string", "description": "Server-provided reason for falling back, when available" }, "stickyOverride": { "type": "boolean", "description": "Whether a sticky model choice overrode the router result" }, "routerLatencyMs": { "type": "number", "minimum": 0.0, "description": "Server-reported router processing time in milliseconds" }, "endToEndLatencyMs": { "type": "number", "minimum": 0.0, "description": "End-to-end client wait time for the router request in milliseconds" }, "chosenShortfall": { "type": "number", "description": "The chosen model's score shortfall relative to the top candidate" }, "hasImage": { "type": "boolean", "description": "Whether the routed prompt contained an image" } }, "required": [ "chosenModel" ], "additionalProperties": false, "description": "Auto Intent resolution: the concrete model the session settled on for the first prompt of an auto-mode session, and why. Lets SDK clients render the chosen model and the full reason it was picked. The core selection fields (chosenModel/reasoningBucket/categoryScores) are stable; the routing-analytics fields (predictedLabel/confidence/candidateModels) mirror the upstream intent service and may evolve, hence the event's experimental stability.", "title": "AutoModeResolvedData", "stability": "experimental" }, "AutoModeResolvedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.auto_mode_resolved", "description": "Type discriminator. Always \"session.auto_mode_resolved\"." }, "data": { "$ref": "#/definitions/AutoModeResolvedData", "description": "Auto Intent resolution: the concrete model the session settled on for the first prompt of an auto-mode session, and why. Lets SDK clients render the chosen model and the full reason it was picked. The core selection fields (chosenModel/reasoningBucket/categoryScores) are stable; the routing-analytics fields (predictedLabel/confidence/candidateModels) mirror the upstream intent service and may evolve, hence the event's experimental stability." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.auto_mode_resolved\". Auto Intent resolution: the concrete model the session settled on for the first prompt of an auto-mode session, and why. Lets SDK clients render the chosen model and the full reason it was picked. The core selection fields (chosenModel/reasoningBucket/categoryScores) are stable; the routing-analytics fields (predictedLabel/confidence/candidateModels) mirror the upstream intent service and may evolve, hence the event's experimental stability.", "title": "AutoModeResolvedEvent", "stability": "experimental" }, "AutoModeResolvedReasoningBucket": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Coarse request-difficulty bucket for UX explainability", "title": "AutoModeResolvedReasoningBucket", "x-enumDescriptions": { "low": "The request looks low-reasoning; a lighter model is appropriate.", "medium": "The request needs a moderate amount of reasoning.", "high": "The request looks high-reasoning; a stronger model is appropriate." } }, "AutoModeSwitchCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved request; clients should dismiss any UI for this request" }, "response": { "$ref": "#/definitions/AutoModeSwitchResponse", "description": "The user's auto-mode-switch choice" } }, "required": [ "requestId", "response" ], "additionalProperties": false, "description": "Auto mode switch completion notification", "title": "AutoModeSwitchCompletedData" }, "AutoModeSwitchCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "auto_mode_switch.completed", "description": "Type discriminator. Always \"auto_mode_switch.completed\"." }, "data": { "$ref": "#/definitions/AutoModeSwitchCompletedData", "description": "Auto mode switch completion notification" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"auto_mode_switch.completed\". Auto mode switch completion notification", "title": "AutoModeSwitchCompletedEvent" }, "AutoModeSwitchRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request; used to respond via session.respondToAutoModeSwitch()" }, "errorCode": { "type": "string", "description": "The rate limit error code that triggered this request" }, "retryAfterSeconds": { "type": "integer", "minimum": 0, "format": "duration", "description": "Seconds until the rate limit resets, when known. Lets clients render a humanized reset time alongside the prompt." } }, "required": [ "requestId" ], "additionalProperties": false, "description": "Auto mode switch request notification requiring user approval", "title": "AutoModeSwitchRequestedData" }, "AutoModeSwitchRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "auto_mode_switch.requested", "description": "Type discriminator. Always \"auto_mode_switch.requested\"." }, "data": { "$ref": "#/definitions/AutoModeSwitchRequestedData", "description": "Auto mode switch request notification requiring user approval" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"auto_mode_switch.requested\". Auto mode switch request notification requiring user approval", "title": "AutoModeSwitchRequestedEvent" }, "AutoModeSwitchResponse": { "type": "string", "enum": [ "yes", "yes_always", "no" ], "description": "The user's auto-mode-switch choice", "title": "AutoModeSwitchResponse", "x-enumDescriptions": { "yes": "Switch models for this request.", "yes_always": "Switch models now and keep using the replacement automatically.", "no": "Do not switch models." } }, "AutopilotObjectiveChangedData": { "type": "object", "properties": { "operation": { "$ref": "#/definitions/AutopilotObjectiveChangedOperation", "description": "The type of operation performed on the autopilot objective state file" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "Current autopilot objective id, if one exists" }, "status": { "$ref": "#/definitions/AutopilotObjectiveChangedStatus", "description": "Current autopilot objective status, if one exists" } }, "required": [ "operation" ], "additionalProperties": false, "description": "Autopilot objective state file operation details indicating what changed", "title": "AutopilotObjectiveChangedData" }, "AutopilotObjectiveChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.autopilot_objective_changed", "description": "Type discriminator. Always \"session.autopilot_objective_changed\"." }, "data": { "$ref": "#/definitions/AutopilotObjectiveChangedData", "description": "Autopilot objective state file operation details indicating what changed" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.autopilot_objective_changed\". Autopilot objective state file operation details indicating what changed", "title": "AutopilotObjectiveChangedEvent" }, "AutopilotObjectiveChangedOperation": { "type": "string", "enum": [ "create", "update", "delete" ], "description": "The type of operation performed on the autopilot objective state file", "title": "AutopilotObjectiveChangedOperation", "x-enumDescriptions": { "create": "Autopilot objective state file was created for a new objective.", "update": "Autopilot objective state file was updated for an existing objective.", "delete": "Autopilot objective state file was deleted or cleared." } }, "AutopilotObjectiveChangedStatus": { "type": "string", "enum": [ "active", "paused", "cap_reached", "completed" ], "description": "Current autopilot objective status, if one exists", "title": "AutopilotObjectiveChangedStatus", "x-enumDescriptions": { "active": "Objective is active and can drive autopilot continuations.", "paused": "Objective is paused and will not drive autopilot continuations.", "cap_reached": "Legacy objective state indicating the previous continuation cap was reached.", "completed": "Objective was completed by the agent." } }, "BackgroundTasksChangedData": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Empty payload for `session.background_tasks_changed`, indicating background task state changed.", "title": "BackgroundTasksChangedData" }, "BackgroundTasksChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.background_tasks_changed", "description": "Type discriminator. Always \"session.background_tasks_changed\"." }, "data": { "$ref": "#/definitions/BackgroundTasksChangedData", "description": "Empty payload for `session.background_tasks_changed`, indicating background task state changed." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.background_tasks_changed\". Empty payload for `session.background_tasks_changed`, indicating background task state changed.", "title": "BackgroundTasksChangedEvent" }, "BinaryAssetData": { "type": "object", "properties": { "assetId": { "type": "string", "description": "Content-addressed id for this binary asset (e.g. \"sha256:...\")." }, "type": { "$ref": "#/definitions/BinaryAssetType", "description": "Binary asset type discriminator. Use \"image\" for images and \"resource\" otherwise." }, "mimeType": { "type": "string", "description": "MIME type of the binary asset" }, "byteLength": { "type": "integer", "minimum": 0, "description": "Decoded byte length of the binary asset" }, "data": { "type": "string", "description": "Base64-encoded binary data", "contentEncoding": "base64" }, "description": { "type": "string", "description": "Human-readable description of the binary data" }, "metadata": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Optional metadata from the producing tool." } }, "required": [ "assetId", "type", "mimeType", "byteLength", "data" ], "additionalProperties": false, "description": "Canonical bytes for a content-addressed binary asset shared by reference across events", "title": "BinaryAssetData" }, "BinaryAssetEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.binary_asset", "description": "Type discriminator. Always \"session.binary_asset\"." }, "data": { "$ref": "#/definitions/BinaryAssetData", "description": "Canonical bytes for a content-addressed binary asset shared by reference across events" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.binary_asset\". Canonical bytes for a content-addressed binary asset shared by reference across events", "title": "BinaryAssetEvent", "stability": "experimental" }, "BinaryAssetReference": { "type": "object", "properties": { "type": { "$ref": "#/definitions/BinaryAssetReferenceType", "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data." }, "assetId": { "type": "string", "description": "Content-addressed id of the session.binary_asset event that holds this binary's bytes (e.g. \"sha256:...\")." }, "mimeType": { "type": "string", "description": "MIME type of the referenced binary data" }, "byteLength": { "type": "integer", "minimum": 0, "description": "Decoded byte length of the referenced binary data" }, "description": { "type": "string", "description": "Human-readable description of the binary data" }, "metadata": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Optional metadata from the producing tool." } }, "required": [ "type", "assetId", "mimeType", "byteLength" ], "additionalProperties": false, "description": "A reference to binary data persisted once on a session.binary_asset event and shared by id", "title": "BinaryAssetReference", "stability": "experimental" }, "BinaryAssetReferenceType": { "type": "string", "enum": [ "image", "resource" ], "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data.", "title": "BinaryAssetReferenceType", "x-enumDescriptions": { "image": "Binary image data.", "resource": "Other binary resource data." } }, "BinaryAssetType": { "type": "string", "enum": [ "image", "resource" ], "description": "Binary asset type discriminator. Use \"image\" for images and \"resource\" otherwise.", "title": "BinaryAssetType", "x-enumDescriptions": { "image": "Binary image data.", "resource": "Other binary resource data." } }, "CanvasClosedData": { "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "description": "Stable caller-supplied identifier of the canvas instance that was closed" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" } }, "required": [ "instanceId", "extensionId", "canvasId" ], "additionalProperties": false, "description": "Payload of `session.canvas.closed` with the closed canvas instance ID, provider ID, and canvas ID.", "title": "CanvasClosedData", "stability": "experimental" }, "CanvasClosedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.canvas.closed", "description": "Type discriminator. Always \"session.canvas.closed\"." }, "data": { "$ref": "#/definitions/CanvasClosedData", "description": "Payload of `session.canvas.closed` with the closed canvas instance ID, provider ID, and canvas ID." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.closed\". Payload of `session.canvas.closed` with the closed canvas instance ID, provider ID, and canvas ID.", "title": "CanvasClosedEvent", "stability": "experimental" }, "CanvasOpenedData": { "type": "object", "properties": { "instanceId": { "type": "string", "description": "Stable caller-supplied canvas instance identifier" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "extensionName": { "type": "string", "description": "Owning extension display name, when available" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "icon": { "type": "string", "description": "Host-local PNG path for the canvas icon, when supplied" }, "title": { "type": "string", "description": "Rendered title" }, "status": { "type": "string", "description": "Provider-supplied status text" }, "url": { "type": "string", "description": "URL for web-rendered canvases" }, "input": { "description": "Input supplied when the instance was opened", "x-opaque-json": true } }, "required": [ "instanceId", "extensionId", "canvasId" ], "additionalProperties": false, "description": "Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input.", "title": "CanvasOpenedData", "stability": "experimental" }, "CanvasOpenedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.canvas.opened", "description": "Type discriminator. Always \"session.canvas.opened\"." }, "data": { "$ref": "#/definitions/CanvasOpenedData", "description": "Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.opened\". Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input.", "title": "CanvasOpenedEvent", "stability": "experimental" }, "CanvasRecordedData": { "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "description": "Stable caller-supplied canvas instance identifier" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "title": { "type": "string", "description": "Rendered title" }, "input": { "description": "Input supplied when the instance was opened", "x-opaque-json": true } }, "required": [ "instanceId", "extensionId", "canvasId" ], "additionalProperties": false, "description": "Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability.", "title": "CanvasRecordedData", "stability": "experimental" }, "CanvasRecordedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.canvas.recorded", "description": "Type discriminator. Always \"session.canvas.recorded\"." }, "data": { "$ref": "#/definitions/CanvasRecordedData", "description": "Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.recorded\". Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability.", "title": "CanvasRecordedEvent", "stability": "experimental" }, "CanvasRegistryChangedCanvas": { "type": "object", "properties": { "extensionId": { "type": "string", "description": "Owning provider identifier" }, "extensionName": { "type": "string", "description": "Owning extension display name, when available" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" }, "displayName": { "type": "string", "description": "Human-readable canvas name" }, "description": { "type": "string", "minLength": 1, "description": "Short, single-sentence description shown to the agent in canvas catalogs." }, "icon": { "type": "string", "description": "Host-local PNG path for the canvas icon, when supplied" }, "inputSchema": { "description": "JSON Schema for canvas open input", "x-opaque-json": true }, "actions": { "type": "array", "items": { "$ref": "#/definitions/CanvasRegistryChangedCanvasAction", "description": "A single action within a canvas declaration, with its name, optional description, and optional input schema." }, "description": "Actions the agent or host may invoke" } }, "required": [ "extensionId", "canvasId", "displayName", "description" ], "additionalProperties": false, "description": "A single canvas declaration in `session.canvas.registry_changed`, including provider IDs, display metadata, input schema, and actions.", "title": "CanvasRegistryChangedCanvas", "stability": "experimental" }, "CanvasRegistryChangedCanvasAction": { "type": "object", "properties": { "name": { "type": "string", "description": "Action name" }, "description": { "type": "string", "description": "Action description" }, "inputSchema": { "description": "JSON Schema for action input", "x-opaque-json": true } }, "required": [ "name" ], "additionalProperties": false, "description": "A single action within a canvas declaration, with its name, optional description, and optional input schema.", "title": "CanvasRegistryChangedCanvasAction", "stability": "experimental" }, "CanvasRegistryChangedData": { "type": "object", "properties": { "canvases": { "type": "array", "items": { "$ref": "#/definitions/CanvasRegistryChangedCanvas", "description": "A single canvas declaration in `session.canvas.registry_changed`, including provider IDs, display metadata, input schema, and actions." }, "description": "Canvas declarations currently available" } }, "required": [ "canvases" ], "additionalProperties": false, "description": "Payload of `session.canvas.registry_changed` listing the canvas declarations currently available.", "title": "CanvasRegistryChangedData", "stability": "experimental" }, "CanvasRegistryChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.canvas.registry_changed", "description": "Type discriminator. Always \"session.canvas.registry_changed\"." }, "data": { "$ref": "#/definitions/CanvasRegistryChangedData", "description": "Payload of `session.canvas.registry_changed` listing the canvas declarations currently available." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.registry_changed\". Payload of `session.canvas.registry_changed` listing the canvas declarations currently available.", "title": "CanvasRegistryChangedEvent", "stability": "experimental" }, "CanvasRemovedData": { "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "description": "Stable caller-supplied identifier of the canvas instance that was closed" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" } }, "required": [ "instanceId", "extensionId", "canvasId" ], "additionalProperties": false, "description": "Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay.", "title": "CanvasRemovedData", "stability": "experimental" }, "CanvasRemovedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.canvas.removed", "description": "Type discriminator. Always \"session.canvas.removed\"." }, "data": { "$ref": "#/definitions/CanvasRemovedData", "description": "Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.removed\". Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay.", "title": "CanvasRemovedEvent", "stability": "experimental" }, "CanvasUnavailableData": { "type": "object", "properties": { "instanceId": { "type": "string", "minLength": 1, "description": "Stable caller-supplied identifier of the canvas instance whose provider became unavailable" }, "extensionId": { "type": "string", "description": "Owning provider identifier" }, "canvasId": { "type": "string", "description": "Provider-local canvas identifier" } }, "required": [ "instanceId", "extensionId", "canvasId" ], "additionalProperties": false, "description": "Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume.", "title": "CanvasUnavailableData", "stability": "experimental" }, "CanvasUnavailableEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.canvas.unavailable", "description": "Type discriminator. Always \"session.canvas.unavailable\"." }, "data": { "$ref": "#/definitions/CanvasUnavailableData", "description": "Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.unavailable\". Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume.", "title": "CanvasUnavailableEvent", "stability": "experimental" }, "CapabilitiesChangedData": { "type": "object", "properties": { "ui": { "$ref": "#/definitions/CapabilitiesChangedUI", "description": "UI capability changes" } }, "additionalProperties": false, "description": "Session capability change notification", "title": "CapabilitiesChangedData" }, "CapabilitiesChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "capabilities.changed", "description": "Type discriminator. Always \"capabilities.changed\"." }, "data": { "$ref": "#/definitions/CapabilitiesChangedData", "description": "Session capability change notification" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"capabilities.changed\". Session capability change notification", "title": "CapabilitiesChangedEvent" }, "CapabilitiesChangedUI": { "type": "object", "properties": { "elicitation": { "type": "boolean", "description": "Whether elicitation is now supported" }, "mcpApps": { "type": "boolean", "description": "Whether MCP Apps (SEP-1865) UI passthrough is now supported" }, "canvases": { "type": "boolean", "description": "Whether canvas rendering is now supported" } }, "additionalProperties": false, "description": "UI capability changes", "title": "CapabilitiesChangedUI" }, "CitableSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for this source within the tool result. Used for deduplication and may be used by future provider integrations to correlate response citations back to the originating source." }, "title": { "type": "string", "description": "Human-readable title of the source." }, "content": { "type": "string", "description": "The source text made available to the model as citable content." }, "url": { "type": "string", "description": "URL of the source, when it is a web resource." }, "path": { "type": "string", "description": "File path relative to the agent's workspace root, when the source is a file." } }, "required": [ "id", "content" ], "additionalProperties": false, "description": "A source supplied by a tool that should be made available to the model as citable content.", "title": "CitableSource", "stability": "experimental" }, "CitationLocation": { "anyOf": [ { "$ref": "#/definitions/CitationLocationChar", "description": "A character range within the source's text content." }, { "$ref": "#/definitions/CitationLocationPage", "description": "A page range within a paginated source document." }, { "$ref": "#/definitions/CitationLocationBlock", "description": "A content-block range within a structured source document." } ], "description": "Location within a cited source (character, page, or content-block range) that supports a span.", "title": "CitationLocation", "stability": "experimental" }, "CitationLocationBlock": { "type": "object", "properties": { "type": { "type": "string", "const": "block", "description": "Citation location type discriminator" }, "startBlock": { "type": "integer", "minimum": 0, "description": "Index of the first content block of the cited range (zero-based, inclusive)." }, "endBlock": { "type": "integer", "minimum": 0, "description": "Index of the last content block of the cited range (zero-based, exclusive)." } }, "required": [ "type", "startBlock", "endBlock" ], "additionalProperties": false, "description": "A content-block range within a structured source document.", "title": "CitationLocationBlock", "stability": "experimental" }, "CitationLocationChar": { "type": "object", "properties": { "type": { "type": "string", "const": "char", "description": "Citation location type discriminator" }, "startIndex": { "type": "integer", "minimum": 0, "description": "Start character offset within the source text (zero-based, inclusive)." }, "endIndex": { "type": "integer", "minimum": 0, "description": "End character offset within the source text (zero-based, exclusive)." } }, "required": [ "type", "startIndex", "endIndex" ], "additionalProperties": false, "description": "A character range within the source's text content.", "title": "CitationLocationChar", "stability": "experimental" }, "CitationLocationPage": { "type": "object", "properties": { "type": { "type": "string", "const": "page", "description": "Citation location type discriminator" }, "startPage": { "type": "integer", "minimum": 0, "description": "First page number of the cited range." }, "endPage": { "type": "integer", "minimum": 0, "description": "Last page number of the cited range (inclusive)." } }, "required": [ "type", "startPage", "endPage" ], "additionalProperties": false, "description": "A page range within a paginated source document.", "title": "CitationLocationPage", "stability": "experimental" }, "CitationProvider": { "type": "string", "enum": [ "anthropic", "openai", "client" ], "description": "The system that produced a citation.", "title": "CitationProvider", "x-enumDescriptions": { "anthropic": "Citation produced by an Anthropic (Claude) model response.", "openai": "Citation produced by an OpenAI model response.", "client": "Citation synthesized client-side by the runtime from tool output." }, "stability": "experimental" }, "CitationReference": { "type": "object", "properties": { "sourceId": { "type": "string", "description": "Identifier of the CitationSource this reference points to (CitationSource.id)." }, "citedText": { "type": "string", "description": "The exact text from the source that supports the cited span, when provided by the model." }, "location": { "$ref": "#/definitions/CitationLocation", "description": "Location within the source that supports the cited span, when the provider reports one." }, "providerMetadata": { "description": "Provider-native citation correlation data (e.g. Anthropic search_result_index / document_index), passed through opaquely for debugging and forward compatibility.", "x-opaque-json": true } }, "required": [ "sourceId" ], "additionalProperties": false, "description": "A single citation occurrence linking a span of generated text to a supporting source.", "title": "CitationReference", "stability": "experimental" }, "Citations": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/definitions/CitationSource", "description": "A source that backs one or more cited spans in the assistant's response." }, "description": "Deduplicated set of sources referenced by the citation spans." }, "spans": { "type": "array", "items": { "$ref": "#/definitions/CitationSpan", "description": "A contiguous span of generated assistant text and the source references that support it." }, "description": "Spans of generated text annotated with the sources that support them." } }, "required": [ "sources", "spans" ], "additionalProperties": false, "description": "Provider-agnostic citations linking spans of the assistant's response to their supporting sources.", "title": "Citations", "stability": "experimental" }, "CitationSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable, turn-scoped identifier for this source, referenced by CitationReference.sourceId." }, "provider": { "$ref": "#/definitions/CitationProvider", "description": "The system that produced this citation." }, "title": { "type": "string", "description": "Human-readable title of the source." }, "url": { "type": "string", "description": "URL of the source, when it is a web resource." }, "path": { "type": "string", "description": "File path relative to the agent's workspace root, when the source is a file." } }, "required": [ "id", "provider" ], "additionalProperties": false, "description": "A source that backs one or more cited spans in the assistant's response.", "title": "CitationSource", "stability": "experimental" }, "CitationSpan": { "type": "object", "properties": { "startIndex": { "type": "integer", "minimum": 0, "description": "Start offset of the cited span within the final assistant message content (UTF-16 code units, zero-based, inclusive)." }, "endIndex": { "type": "integer", "minimum": 0, "description": "End offset of the cited span within the final assistant message content (UTF-16 code units, zero-based, exclusive)." }, "references": { "type": "array", "items": { "$ref": "#/definitions/CitationReference", "description": "A single citation occurrence linking a span of generated text to a supporting source." }, "description": "The sources that support this span of generated text." } }, "required": [ "startIndex", "endIndex", "references" ], "additionalProperties": false, "description": "A contiguous span of generated assistant text and the source references that support it.", "title": "CitationSpan", "stability": "experimental" }, "CommandCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved command request; clients should dismiss any UI for this request" } }, "required": [ "requestId" ], "additionalProperties": false, "description": "Queued command completion notification signaling UI dismissal", "title": "CommandCompletedData" }, "CommandCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "command.completed", "description": "Type discriminator. Always \"command.completed\"." }, "data": { "$ref": "#/definitions/CommandCompletedData", "description": "Queued command completion notification signaling UI dismissal" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"command.completed\". Queued command completion notification signaling UI dismissal", "title": "CommandCompletedEvent" }, "CommandExecuteData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier; used to respond via session.commands.handlePendingCommand()" }, "command": { "type": "string", "description": "The full command text (e.g., /deploy production)" }, "commandName": { "type": "string", "description": "Command name without leading /" }, "args": { "type": "string", "description": "Raw argument string after the command name" } }, "required": [ "requestId", "command", "commandName", "args" ], "additionalProperties": false, "description": "Registered command dispatch request routed to the owning client", "title": "CommandExecuteData" }, "CommandExecuteEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "command.execute", "description": "Type discriminator. Always \"command.execute\"." }, "data": { "$ref": "#/definitions/CommandExecuteData", "description": "Registered command dispatch request routed to the owning client" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"command.execute\". Registered command dispatch request routed to the owning client", "title": "CommandExecuteEvent" }, "CommandQueuedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request; used to respond via session.respondToQueuedCommand()" }, "command": { "type": "string", "description": "The slash command text to be executed (e.g., /help, /clear)" } }, "required": [ "requestId", "command" ], "additionalProperties": false, "description": "Queued slash command dispatch request for client execution", "title": "CommandQueuedData" }, "CommandQueuedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "command.queued", "description": "Type discriminator. Always \"command.queued\"." }, "data": { "$ref": "#/definitions/CommandQueuedData", "description": "Queued slash command dispatch request for client execution" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"command.queued\". Queued slash command dispatch request for client execution", "title": "CommandQueuedEvent" }, "CommandsChangedCommand": { "type": "object", "properties": { "name": { "type": "string", "description": "Slash command name without the leading slash." }, "description": { "type": "string", "description": "Optional human-readable command description." } }, "required": [ "name" ], "additionalProperties": false, "description": "A single slash command available in the session, as listed by the `commands.changed` event.", "title": "CommandsChangedCommand" }, "CommandsChangedData": { "type": "object", "properties": { "commands": { "type": "array", "items": { "$ref": "#/definitions/CommandsChangedCommand", "description": "A single slash command available in the session, as listed by the `commands.changed` event." }, "description": "Current list of registered SDK commands" } }, "required": [ "commands" ], "additionalProperties": false, "description": "SDK command registration change notification", "title": "CommandsChangedData" }, "CommandsChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "commands.changed", "description": "Type discriminator. Always \"commands.changed\"." }, "data": { "$ref": "#/definitions/CommandsChangedData", "description": "SDK command registration change notification" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"commands.changed\". SDK command registration change notification", "title": "CommandsChangedEvent" }, "CompactionCompleteCompactionTokensUsed": { "type": "object", "properties": { "inputTokens": { "type": "integer", "minimum": 0, "description": "Input tokens consumed by the compaction LLM call" }, "outputTokens": { "type": "integer", "minimum": 0, "description": "Output tokens produced by the compaction LLM call" }, "cacheReadTokens": { "type": "integer", "minimum": 0, "description": "Cached input tokens reused in the compaction LLM call" }, "cacheWriteTokens": { "type": "integer", "minimum": 0, "description": "Tokens written to prompt cache in the compaction LLM call" }, "copilotUsage": { "$ref": "#/definitions/CompactionCompleteCompactionTokensUsedCopilotUsage", "description": "Per-request cost and usage data from the CAPI copilot_usage response field", "visibility": "internal" }, "duration": { "type": "integer", "minimum": 0, "format": "duration", "description": "Duration of the compaction LLM call in milliseconds" }, "model": { "type": "string", "description": "Model identifier used for the compaction LLM call" } }, "additionalProperties": false, "description": "Token usage breakdown for the compaction LLM call (aligned with assistant.usage format)", "title": "CompactionCompleteCompactionTokensUsed" }, "CompactionCompleteCompactionTokensUsedCopilotUsage": { "type": "object", "properties": { "tokenDetails": { "type": "array", "items": { "$ref": "#/definitions/CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail", "description": "Token usage detail for a single billing category" }, "description": "Itemized token usage breakdown", "visibility": "internal" }, "totalNanoAiu": { "type": "number", "minimum": 0, "description": "Total cost in nano-AI units for this request" } }, "required": [ "totalNanoAiu" ], "additionalProperties": false, "description": "Per-request cost and usage data from the CAPI copilot_usage response field", "title": "CompactionCompleteCompactionTokensUsedCopilotUsage", "visibility": "internal" }, "CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail": { "type": "object", "properties": { "batchSize": { "type": "integer", "minimum": 0, "description": "Number of tokens in this billing batch" }, "costPerBatch": { "type": "integer", "minimum": 0, "description": "Cost per batch of tokens" }, "tokenCount": { "type": "integer", "minimum": 0, "description": "Total token count for this entry" }, "tokenType": { "type": "string", "description": "Token category (e.g., \"input\", \"output\")" } }, "required": [ "batchSize", "costPerBatch", "tokenCount", "tokenType" ], "additionalProperties": false, "description": "Token usage detail for a single billing category", "title": "CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail" }, "CompactionCompleteData": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether compaction completed successfully" }, "error": { "type": "string", "description": "Error message if compaction failed" }, "preCompactionTokens": { "type": "integer", "minimum": 0, "description": "Total tokens in conversation before compaction" }, "postCompactionTokens": { "type": "integer", "minimum": 0, "description": "Total tokens in conversation after compaction" }, "preCompactionMessagesLength": { "type": "integer", "minimum": 0, "description": "Number of messages before compaction" }, "messagesRemoved": { "type": "integer", "minimum": 0, "description": "Number of messages removed during compaction" }, "tokensRemoved": { "type": "integer", "minimum": 0, "description": "Number of tokens removed during compaction" }, "customInstructions": { "type": "string", "description": "User-supplied focus instructions provided to a manual `/compact` invocation. Omitted for automatic compaction and for manual compaction with no focus text." }, "summaryContent": { "type": "string", "description": "LLM-generated summary of the compacted conversation history" }, "checkpointNumber": { "type": "integer", "minimum": 0, "description": "Checkpoint snapshot number created for recovery" }, "checkpointPath": { "type": "string", "description": "File path where the checkpoint was stored" }, "compactionTokensUsed": { "$ref": "#/definitions/CompactionCompleteCompactionTokensUsed", "description": "Token usage breakdown for the compaction LLM call (aligned with assistant.usage format)" }, "requestId": { "type": "string", "description": "GitHub request tracing ID (x-github-request-id header) for the compaction LLM call" }, "serviceRequestId": { "type": "string", "description": "Copilot service request ID (x-copilot-service-request-id header) for the compaction LLM call" }, "systemTokens": { "type": "integer", "minimum": 0, "description": "Token count from system message(s) after compaction" }, "conversationTokens": { "type": "integer", "minimum": 0, "description": "Token count from non-system messages (user, assistant, tool) after compaction" }, "toolDefinitionsTokens": { "type": "integer", "minimum": 0, "description": "Token count from tool definitions after compaction" }, "statusCode": { "type": "integer", "minimum": 0, "description": "For failed compaction only: the HTTP status code of the compaction LLM call failure, when it carried one. Absent for successful compaction and for failures without an HTTP status (e.g. an empty model response or a transport error)." }, "tokenLimit": { "type": "integer", "minimum": 0, "description": "Model context window token limit the compaction was targeting, when known" }, "trigger": { "$ref": "#/definitions/CompactionTrigger", "description": "What initiated this compaction, when known" } }, "required": [ "success" ], "additionalProperties": false, "description": "Conversation compaction results including success status, metrics, and optional error details", "title": "CompactionCompleteData" }, "CompactionCompleteEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.compaction_complete", "description": "Type discriminator. Always \"session.compaction_complete\"." }, "data": { "$ref": "#/definitions/CompactionCompleteData", "description": "Conversation compaction results including success status, metrics, and optional error details" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.compaction_complete\". Conversation compaction results including success status, metrics, and optional error details", "title": "CompactionCompleteEvent" }, "CompactionStartData": { "type": "object", "properties": { "model": { "type": "string", "description": "Model identifier used for compaction, when known" }, "systemTokens": { "type": "integer", "minimum": 0, "description": "Token count from system message(s) at compaction start" }, "conversationTokens": { "type": "integer", "minimum": 0, "description": "Token count from non-system messages (user, assistant, tool) at compaction start" }, "toolDefinitionsTokens": { "type": "integer", "minimum": 0, "description": "Token count from tool definitions at compaction start" }, "currentTokens": { "type": "integer", "minimum": 0, "description": "Total context tokens (system + conversation + tool definitions) at compaction start, when known" }, "tokenLimit": { "type": "integer", "minimum": 0, "description": "Model context window token limit the compaction is targeting, when known" }, "trigger": { "$ref": "#/definitions/CompactionTrigger", "description": "What initiated this compaction, when known" } }, "additionalProperties": false, "description": "Context window breakdown at the start of LLM-powered conversation compaction", "title": "CompactionStartData" }, "CompactionStartEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.compaction_start", "description": "Type discriminator. Always \"session.compaction_start\"." }, "data": { "$ref": "#/definitions/CompactionStartData", "description": "Context window breakdown at the start of LLM-powered conversation compaction" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.compaction_start\". Context window breakdown at the start of LLM-powered conversation compaction", "title": "CompactionStartEvent" }, "CompactionTrigger": { "type": "string", "enum": [ "threshold", "context_limit_retry", "manual", "memory_pressure", "model_switch" ], "description": "What initiated a conversation compaction", "title": "CompactionTrigger", "x-enumDescriptions": { "threshold": "Background compaction started automatically because context utilization crossed the background threshold.", "context_limit_retry": "Compaction forced by a context-limit model response (e.g. HTTP 413) before retrying the request.", "manual": "User-requested compaction, e.g. the /compact command or the history.compact API.", "memory_pressure": "Emergency compaction triggered by high process memory usage.", "model_switch": "Compaction requested while switching to a model with a smaller context window." } }, "ContextChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.context_changed", "description": "Type discriminator. Always \"session.context_changed\"." }, "data": { "$ref": "#/definitions/WorkingDirectoryContext", "description": "Updated working directory and git context after the change" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.context_changed\". Updated working directory and git context after the change", "title": "ContextChangedEvent" }, "ContextClearedData": { "type": "object", "properties": { "initialMessage": { "type": "string", "description": "Optional initial message set after clearing" }, "messagesCleared": { "type": "integer", "minimum": 0, "description": "Number of conversation messages that were cleared" } }, "required": [ "messagesCleared" ], "additionalProperties": false, "description": "Context-cleared details emitted when the host clears the conversation (the session.history.clearContext RPC / Session.clearContextMessages)", "title": "ContextClearedData" }, "ContextClearedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.context_cleared", "description": "Type discriminator. Always \"session.context_cleared\"." }, "data": { "$ref": "#/definitions/ContextClearedData", "description": "Context-cleared details emitted when the host clears the conversation (the session.history.clearContext RPC / Session.clearContextMessages)" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.context_cleared\". Context-cleared details emitted when the host clears the conversation (the session.history.clearContext RPC / Session.clearContextMessages)", "title": "ContextClearedEvent" }, "ContextTier": { "type": "string", "enum": [ "default", "long_context" ], "description": "Allowed values for the `ContextTier` enumeration.", "title": "ContextTier", "x-enumDescriptions": { "default": "Default context tier with standard context window size.", "long_context": "Extended context tier with a larger context window." } }, "CustomAgentsUpdatedAgent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the agent" }, "name": { "type": "string", "description": "Internal name of the agent" }, "displayName": { "type": "string", "description": "Human-readable display name" }, "description": { "type": "string", "description": "Description of what the agent does" }, "source": { "type": "string", "description": "Source location: user, project, inherited, remote, or plugin" }, "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "List of tool names available to this agent, or null when all tools are available" }, "userInvocable": { "type": "boolean", "description": "Whether the agent can be selected by the user" }, "model": { "type": "string", "description": "Model override for this agent, if set" } }, "required": [ "id", "name", "displayName", "description", "source", "tools", "userInvocable" ], "additionalProperties": false, "description": "A single loaded custom agent in `session.custom_agents_updated`, with identity, source, tools, invocability, and model override.", "title": "CustomAgentsUpdatedAgent" }, "CustomAgentsUpdatedData": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/definitions/CustomAgentsUpdatedAgent", "description": "A single loaded custom agent in `session.custom_agents_updated`, with identity, source, tools, invocability, and model override." }, "description": "Array of loaded custom agent metadata" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal warnings from agent loading" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Fatal errors from agent loading" } }, "required": [ "agents", "warnings", "errors" ], "additionalProperties": false, "description": "Payload of `session.custom_agents_updated` with loaded custom agents plus non-fatal warnings and fatal errors.", "title": "CustomAgentsUpdatedData" }, "CustomAgentsUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.custom_agents_updated", "description": "Type discriminator. Always \"session.custom_agents_updated\"." }, "data": { "$ref": "#/definitions/CustomAgentsUpdatedData", "description": "Payload of `session.custom_agents_updated` with loaded custom agents plus non-fatal warnings and fatal errors." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.custom_agents_updated\". Payload of `session.custom_agents_updated` with loaded custom agents plus non-fatal warnings and fatal errors.", "title": "CustomAgentsUpdatedEvent" }, "CustomNotificationData": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "description": "Namespace for the custom notification producer" }, "name": { "type": "string", "minLength": 1, "description": "Source-defined custom notification name" }, "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Optional source-defined payload schema version" }, "subject": { "$ref": "#/definitions/CustomNotificationSubject", "description": "Optional source-defined string identifiers describing the payload subject" }, "payload": { "$ref": "#/definitions/CustomNotificationPayload", "description": "Source-defined JSON payload for the custom notification" } }, "required": [ "source", "name", "payload" ], "additionalProperties": false, "description": "Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.", "title": "CustomNotificationData" }, "CustomNotificationEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.custom_notification", "description": "Type discriminator. Always \"session.custom_notification\"." }, "data": { "$ref": "#/definitions/CustomNotificationData", "description": "Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.custom_notification\". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.", "title": "CustomNotificationEvent" }, "CustomNotificationPayload": { "description": "Source-defined JSON payload for the custom notification", "title": "CustomNotificationPayload", "x-opaque-json": true }, "CustomNotificationSubject": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional source-defined string identifiers describing the payload subject", "title": "CustomNotificationSubject" }, "ElicitationCompletedAction": { "type": "string", "enum": [ "accept", "decline", "cancel" ], "description": "The user action: \"accept\" (submitted form), \"decline\" (explicitly refused), or \"cancel\" (dismissed)", "title": "ElicitationCompletedAction", "x-enumDescriptions": { "accept": "The user submitted the requested form.", "decline": "The user explicitly declined the request.", "cancel": "The user dismissed the request." } }, "ElicitationCompletedContent": { "description": "Opaque JSON value submitted for one field in accepted `elicitation.completed` form content.", "title": "ElicitationCompletedContent", "x-opaque-json": true }, "ElicitationCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved elicitation request; clients should dismiss any UI for this request" }, "action": { "$ref": "#/definitions/ElicitationCompletedAction", "description": "The user action: \"accept\" (submitted form), \"decline\" (explicitly refused), or \"cancel\" (dismissed)" }, "content": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ElicitationCompletedContent", "description": "Opaque JSON value submitted for one field in accepted `elicitation.completed` form content." }, "description": "The submitted form data when action is 'accept'; keys match the requested schema fields" } }, "required": [ "requestId" ], "additionalProperties": false, "description": "Elicitation request completion with the user's response", "title": "ElicitationCompletedData" }, "ElicitationCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "elicitation.completed", "description": "Type discriminator. Always \"elicitation.completed\"." }, "data": { "$ref": "#/definitions/ElicitationCompletedData", "description": "Elicitation request completion with the user's response" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"elicitation.completed\". Elicitation request completion with the user's response", "title": "ElicitationCompletedEvent" }, "ElicitationRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this elicitation request; used to respond via session.respondToElicitation()" }, "toolCallId": { "type": "string", "description": "Tool call ID from the LLM completion; used to correlate with CompletionChunk.toolCall.id for remote UIs" }, "elicitationSource": { "type": "string", "description": "The source that initiated the request (MCP server name, or absent for agent-initiated)" }, "message": { "type": "string", "description": "Message describing what information is needed from the user" }, "mode": { "$ref": "#/definitions/ElicitationRequestedMode", "description": "Elicitation mode; \"form\" for structured input, \"url\" for browser-based. Defaults to \"form\" when absent." }, "requestedSchema": { "$ref": "#/definitions/ElicitationRequestedSchema", "description": "JSON Schema describing the form fields to present to the user (form mode only)" }, "url": { "type": "string", "description": "URL to open in the user's browser (url mode only)" } }, "required": [ "requestId", "message" ], "description": "Elicitation request; may be form-based (structured input) or URL-based (browser redirect)", "title": "ElicitationRequestedData" }, "ElicitationRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "elicitation.requested", "description": "Type discriminator. Always \"elicitation.requested\"." }, "data": { "$ref": "#/definitions/ElicitationRequestedData", "description": "Elicitation request; may be form-based (structured input) or URL-based (browser redirect)" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"elicitation.requested\". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)", "title": "ElicitationRequestedEvent" }, "ElicitationRequestedMode": { "type": "string", "enum": [ "form", "url" ], "description": "Elicitation mode; \"form\" for structured input, \"url\" for browser-based. Defaults to \"form\" when absent.", "title": "ElicitationRequestedMode", "x-enumDescriptions": { "form": "Structured form-based elicitation.", "url": "Browser URL-based elicitation." } }, "ElicitationRequestedSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "Schema type indicator (always 'object')" }, "properties": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Form field definitions, keyed by field name" }, "required": { "type": "array", "items": { "type": "string" }, "description": "List of required field names" } }, "required": [ "type", "properties" ], "additionalProperties": false, "description": "JSON Schema describing the form fields to present to the user (form mode only)", "title": "ElicitationRequestedSchema" }, "EmbeddedBlobResourceContents": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI identifying the resource" }, "mimeType": { "type": "string", "description": "MIME type of the blob content" }, "blob": { "type": "string", "description": "Base64-encoded binary content of the resource", "contentEncoding": "base64" } }, "required": [ "uri", "blob" ], "additionalProperties": false, "description": "Embedded binary resource contents identified by a URI, with an optional MIME type and a base64-encoded blob.", "title": "EmbeddedBlobResourceContents" }, "EmbeddedTextResourceContents": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI identifying the resource" }, "mimeType": { "type": "string", "description": "MIME type of the text content" }, "text": { "type": "string", "description": "Text content of the resource" } }, "required": [ "uri", "text" ], "additionalProperties": false, "description": "Embedded text resource contents identified by a URI, with an optional MIME type and a text payload.", "title": "EmbeddedTextResourceContents" }, "ErrorData": { "type": "object", "properties": { "errorType": { "type": "string", "description": "Category of error (e.g., \"authentication\", \"authorization\", \"quota\", \"rate_limit\", \"context_limit\", \"query\")" }, "errorCode": { "type": "string", "description": "Fine-grained error code from the upstream provider, when available. For `errorType: \"rate_limit\"`, this is one of the `RateLimitErrorCode` values (e.g., `\"user_weekly_rate_limited\"`, `\"user_global_rate_limited\"`, `\"rate_limited\"`, `\"user_model_rate_limited\"`, `\"integration_rate_limited\"`). For `errorType: \"quota\"`, this is the CAPI quota error code (e.g., `\"quota_exceeded\"`, `\"session_quota_exceeded\"`, `\"billing_not_configured\"`)." }, "eligibleForAutoSwitch": { "type": "boolean", "description": "Only set on `errorType: \"rate_limit\"`. When `true`, the runtime will follow this error with an `auto_mode_switch.requested` event (or silently switch if `continueOnAutoMode` is enabled). UI clients can use this flag to suppress duplicate rendering of the rate-limit error when they show their own auto-mode-switch prompt." }, "message": { "type": "string", "description": "Human-readable error message" }, "stack": { "type": "string", "description": "Error stack trace, when available" }, "statusCode": { "type": "integer", "minimum": 0, "maximum": 999, "description": "HTTP status code from the upstream request, if applicable" }, "providerCallId": { "type": "string", "description": "GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs" }, "serviceRequestId": { "type": "string", "description": "Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation" }, "url": { "type": "string", "description": "Optional URL associated with this error that the user can open in a browser" } }, "required": [ "errorType", "message" ], "additionalProperties": false, "description": "Error details for timeline display including message and optional diagnostic information", "title": "ErrorData" }, "ErrorEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.error", "description": "Type discriminator. Always \"session.error\"." }, "data": { "$ref": "#/definitions/ErrorData", "description": "Error details for timeline display including message and optional diagnostic information" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.error\". Error details for timeline display including message and optional diagnostic information", "title": "ErrorEvent" }, "ExitPlanModeAction": { "type": "string", "enum": [ "exit_only", "interactive", "autopilot", "autopilot_fleet" ], "description": "Exit plan mode action", "title": "ExitPlanModeAction", "x-enumDescriptions": { "exit_only": "Exit plan mode without starting implementation.", "interactive": "Exit plan mode and continue in interactive mode.", "autopilot": "Exit plan mode and continue autonomously.", "autopilot_fleet": "Exit plan mode and continue with parallel autonomous workers." } }, "ExitPlanModeCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved exit plan mode request; clients should dismiss any UI for this request" }, "approved": { "type": "boolean", "description": "Whether the plan was approved by the user" }, "selectedAction": { "$ref": "#/definitions/ExitPlanModeAction", "description": "Action selected by the user" }, "autoApproveEdits": { "type": "boolean", "description": "Whether edits should be auto-approved without confirmation" }, "feedback": { "type": "string", "description": "Free-form feedback from the user if they requested changes to the plan" } }, "required": [ "requestId" ], "additionalProperties": false, "description": "Plan mode exit completion with the user's approval decision and optional feedback", "title": "ExitPlanModeCompletedData" }, "ExitPlanModeCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "exit_plan_mode.completed", "description": "Type discriminator. Always \"exit_plan_mode.completed\"." }, "data": { "$ref": "#/definitions/ExitPlanModeCompletedData", "description": "Plan mode exit completion with the user's approval decision and optional feedback" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"exit_plan_mode.completed\". Plan mode exit completion with the user's approval decision and optional feedback", "title": "ExitPlanModeCompletedEvent" }, "ExitPlanModeRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request; used to respond via session.respondToExitPlanMode()" }, "summary": { "type": "string", "description": "Summary of the plan that was created" }, "planContent": { "type": "string", "description": "Full content of the plan file" }, "actions": { "type": "array", "items": { "$ref": "#/definitions/ExitPlanModeAction", "description": "Exit plan mode action" }, "description": "Available actions the user can take" }, "recommendedAction": { "$ref": "#/definitions/ExitPlanModeAction", "description": "Recommended action to preselect for the user" } }, "required": [ "requestId", "summary", "planContent", "actions", "recommendedAction" ], "additionalProperties": false, "description": "Plan approval request with plan content and available user actions", "title": "ExitPlanModeRequestedData" }, "ExitPlanModeRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "exit_plan_mode.requested", "description": "Type discriminator. Always \"exit_plan_mode.requested\"." }, "data": { "$ref": "#/definitions/ExitPlanModeRequestedData", "description": "Plan approval request with plan content and available user actions" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"exit_plan_mode.requested\". Plan approval request with plan content and available user actions", "title": "ExitPlanModeRequestedEvent" }, "ExtensionsAttachmentsPushedData": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/definitions/Attachment", "description": "A user message attachment — a file, directory, code selection, blob, GitHub reference, GitHub-anchored pointer, or extension-supplied context payload" }, "description": "Attachments contributed by an extension; the host should surface these as composer pills and forward them via the next session.send call." } }, "required": [ "attachments" ], "additionalProperties": false, "description": "Payload of `session.extensions.attachments_pushed` with extension-contributed attachments for the next send.", "title": "ExtensionsAttachmentsPushedData" }, "ExtensionsAttachmentsPushedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.extensions.attachments_pushed", "description": "Type discriminator. Always \"session.extensions.attachments_pushed\"." }, "data": { "$ref": "#/definitions/ExtensionsAttachmentsPushedData", "description": "Payload of `session.extensions.attachments_pushed` with extension-contributed attachments for the next send." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.extensions.attachments_pushed\". Payload of `session.extensions.attachments_pushed` with extension-contributed attachments for the next send.", "title": "ExtensionsAttachmentsPushedEvent" }, "ExtensionsLoadedData": { "type": "object", "properties": { "extensions": { "type": "array", "items": { "$ref": "#/definitions/ExtensionsLoadedExtension", "description": "A single extension discovered by `session.extensions_loaded`, including qualified ID, source, and current status." }, "description": "Array of discovered extensions and their status" } }, "required": [ "extensions" ], "additionalProperties": false, "description": "Payload of `session.extensions_loaded` listing discovered extensions and their statuses.", "title": "ExtensionsLoadedData" }, "ExtensionsLoadedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.extensions_loaded", "description": "Type discriminator. Always \"session.extensions_loaded\"." }, "data": { "$ref": "#/definitions/ExtensionsLoadedData", "description": "Payload of `session.extensions_loaded` listing discovered extensions and their statuses." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.extensions_loaded\". Payload of `session.extensions_loaded` listing discovered extensions and their statuses.", "title": "ExtensionsLoadedEvent" }, "ExtensionsLoadedExtension": { "type": "object", "properties": { "id": { "type": "string", "description": "Source-qualified extension ID (e.g., 'project:my-ext', 'user:auth-helper', 'plugin:my-plugin:my-ext')" }, "name": { "type": "string", "description": "Extension name (directory name)" }, "source": { "$ref": "#/definitions/ExtensionsLoadedExtensionSource", "description": "Discovery source" }, "status": { "$ref": "#/definitions/ExtensionsLoadedExtensionStatus", "description": "Current status: running, disabled, failed, or starting" } }, "required": [ "id", "name", "source", "status" ], "additionalProperties": false, "description": "A single extension discovered by `session.extensions_loaded`, including qualified ID, source, and current status.", "title": "ExtensionsLoadedExtension" }, "ExtensionsLoadedExtensionSource": { "type": "string", "enum": [ "project", "user", "plugin", "session" ], "description": "Discovery source", "title": "ExtensionsLoadedExtensionSource", "x-enumDescriptions": { "project": "Extension discovered from the current project.", "user": "Extension discovered from the user's extension directory.", "plugin": "Extension contributed by an installed plugin.", "session": "Extension discovered from the current session's state directory." } }, "ExtensionsLoadedExtensionStatus": { "type": "string", "enum": [ "running", "disabled", "failed", "starting" ], "description": "Current status: running, disabled, failed, or starting", "title": "ExtensionsLoadedExtensionStatus", "x-enumDescriptions": { "running": "The extension process is running.", "disabled": "The extension is installed but disabled.", "failed": "The extension failed to start or crashed.", "starting": "The extension process is starting." } }, "ExternalToolCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved external tool request; clients should dismiss any UI for this request" } }, "required": [ "requestId" ], "additionalProperties": false, "description": "External tool completion notification signaling UI dismissal", "title": "ExternalToolCompletedData" }, "ExternalToolCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "external_tool.completed", "description": "Type discriminator. Always \"external_tool.completed\"." }, "data": { "$ref": "#/definitions/ExternalToolCompletedData", "description": "External tool completion notification signaling UI dismissal" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"external_tool.completed\". External tool completion notification signaling UI dismissal", "title": "ExternalToolCompletedEvent" }, "ExternalToolRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request; used to respond via session.respondToExternalTool()" }, "sessionId": { "type": "string", "description": "Session ID that this external tool request belongs to" }, "toolCallId": { "type": "string", "description": "Tool call ID assigned to this external tool invocation" }, "toolName": { "type": "string", "description": "Name of the external tool to invoke" }, "arguments": { "description": "Arguments to pass to the external tool", "x-opaque-json": true }, "workingDirectory": { "type": "string", "description": "Active session working directory, when known." }, "traceparent": { "type": "string", "description": "W3C Trace Context traceparent header for the execute_tool span" }, "tracestate": { "type": "string", "description": "W3C Trace Context tracestate header for the execute_tool span" } }, "required": [ "requestId", "sessionId", "toolCallId", "toolName" ], "additionalProperties": false, "description": "External tool invocation request for client-side tool execution", "title": "ExternalToolRequestedData" }, "ExternalToolRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "external_tool.requested", "description": "Type discriminator. Always \"external_tool.requested\"." }, "data": { "$ref": "#/definitions/ExternalToolRequestedData", "description": "External tool invocation request for client-side tool execution" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"external_tool.requested\". External tool invocation request for client-side tool execution", "title": "ExternalToolRequestedEvent" }, "FactoryPermissionOperation": { "type": "string", "enum": [ "run", "author" ], "description": "Operation gated by a factory permission request.", "title": "FactoryPermissionOperation", "x-enumDescriptions": { "run": "Running a registered factory, which spends subagents, active time, and AI credits under the approved limits.", "author": "Authoring a factory, which writes JavaScript into a session-scoped extension and loads it." } }, "FactoryPermissionPhase": { "type": "object", "properties": { "title": { "type": "string", "description": "Phase title" }, "detail": { "type": "string", "description": "Optional phase detail" } }, "required": [ "title" ], "additionalProperties": false, "description": "A declared phase shown in a factory permission prompt.", "title": "FactoryPermissionPhase" }, "FactoryRunUpdatedData": { "type": "object", "properties": { "runId": { "type": "string" }, "revision": { "type": "integer", "minimum": 1, "description": "Monotonic revision now available for the run." } }, "required": [ "runId", "revision" ], "additionalProperties": false, "description": "Ephemeral invalidation signal for a changed factory run.", "title": "FactoryRunUpdatedData", "stability": "experimental" }, "FactoryRunUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "factory.run_updated", "description": "Type discriminator. Always \"factory.run_updated\"." }, "data": { "$ref": "#/definitions/FactoryRunUpdatedData", "description": "Ephemeral invalidation signal for a changed factory run." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"factory.run_updated\". Ephemeral invalidation signal for a changed factory run.", "title": "FactoryRunUpdatedEvent", "stability": "experimental" }, "GitHubMcpToolConfig": { "type": "object", "properties": { "enableAllTools": { "type": "boolean", "description": "Whether to use the read-write endpoint and request all toolsets" }, "additionalToolsets": { "type": "array", "items": { "type": "string" }, "description": "Additional GitHub MCP toolsets requested by the session" }, "additionalTools": { "type": "array", "items": { "type": "string" }, "description": "Additional GitHub MCP tools requested by the session" }, "enableInsidersMode": { "type": "boolean", "description": "Whether to request the GitHub MCP insiders build" } }, "additionalProperties": false, "description": "Per-session configuration for the built-in GitHub MCP server", "title": "GitHubMcpToolConfig" }, "GitHubRepoRef": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "Numeric GitHub repository id" }, "name": { "type": "string", "description": "Repository name (without owner)" }, "owner": { "type": "string", "description": "Repository owner login (user or organization)" } }, "required": [ "name", "owner" ], "additionalProperties": false, "description": "Pointer to a GitHub repository.", "title": "GitHubRepoRef" }, "HandoffData": { "type": "object", "properties": { "handoffTime": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the handoff occurred" }, "sourceType": { "$ref": "#/definitions/HandoffSourceType", "description": "Origin type of the session being handed off" }, "repository": { "$ref": "#/definitions/HandoffRepository", "description": "Repository context for the handed-off session" }, "context": { "type": "string", "description": "Additional context information for the handoff" }, "summary": { "type": "string", "description": "Summary of the work done in the source session" }, "remoteSessionId": { "type": "string", "description": "Session ID of the remote session being handed off" }, "host": { "type": "string", "description": "GitHub host URL for the source session (e.g., https://github.com or https://tenant.ghe.com)" } }, "required": [ "handoffTime", "sourceType" ], "additionalProperties": false, "description": "Session handoff metadata including source, context, and repository information", "title": "HandoffData" }, "HandoffEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.handoff", "description": "Type discriminator. Always \"session.handoff\"." }, "data": { "$ref": "#/definitions/HandoffData", "description": "Session handoff metadata including source, context, and repository information" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.handoff\". Session handoff metadata including source, context, and repository information", "title": "HandoffEvent" }, "HandoffRepository": { "type": "object", "properties": { "owner": { "type": "string", "description": "Repository owner (user or organization)" }, "name": { "type": "string", "description": "Repository name" }, "branch": { "type": "string", "description": "Git branch name, if applicable" } }, "required": [ "owner", "name" ], "additionalProperties": false, "description": "Repository context for the handed-off session", "title": "HandoffRepository" }, "HandoffSourceType": { "type": "string", "enum": [ "remote", "local" ], "description": "Origin type of the session being handed off", "title": "HandoffSourceType", "x-enumDescriptions": { "remote": "The handoff originated from a remote session.", "local": "The handoff originated from a local session." } }, "HeaderEntry": { "type": "object", "properties": { "name": { "type": "string", "description": "HTTP response header name as observed by the runtime." }, "value": { "type": "string", "description": "HTTP response header value as observed by the runtime." } }, "required": [ "name", "value" ], "additionalProperties": false, "description": "Single HTTP header entry as a name/value pair.", "title": "HeaderEntry" }, "HookEndData": { "type": "object", "properties": { "hookInvocationId": { "type": "string", "description": "Identifier matching the corresponding hook.start event" }, "hookType": { "type": "string", "description": "Type of hook that was invoked (e.g., \"preToolUse\", \"postToolUse\", \"sessionStart\")" }, "output": { "description": "Output data produced by the hook", "x-opaque-json": true }, "success": { "type": "boolean", "description": "Whether the hook completed successfully" }, "error": { "$ref": "#/definitions/HookEndError", "description": "Error details when the hook failed" } }, "required": [ "hookInvocationId", "hookType", "success" ], "additionalProperties": false, "description": "Hook invocation completion details including output, success status, and error information", "title": "HookEndData" }, "HookEndError": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "stack": { "type": "string", "description": "Error stack trace, when available" }, "source": { "type": "string", "description": "Source label of the hook that errored (e.g. the plugin it was loaded from), when known" } }, "required": [ "message" ], "additionalProperties": false, "description": "Error details when the hook failed", "title": "HookEndError" }, "HookEndEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "hook.end", "description": "Type discriminator. Always \"hook.end\"." }, "data": { "$ref": "#/definitions/HookEndData", "description": "Hook invocation completion details including output, success status, and error information" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"hook.end\". Hook invocation completion details including output, success status, and error information", "title": "HookEndEvent" }, "HookProgressData": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable progress message from the hook process" }, "temporary": { "type": "boolean", "description": "When true, this status message replaces the previous temporary one instead of accumulating" } }, "required": [ "message" ], "additionalProperties": false, "description": "Ephemeral progress update from a running hook process", "title": "HookProgressData" }, "HookProgressEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "hook.progress", "description": "Type discriminator. Always \"hook.progress\"." }, "data": { "$ref": "#/definitions/HookProgressData", "description": "Ephemeral progress update from a running hook process" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"hook.progress\". Ephemeral progress update from a running hook process", "title": "HookProgressEvent" }, "HookStartData": { "type": "object", "properties": { "hookInvocationId": { "type": "string", "description": "Unique identifier for this hook invocation" }, "hookType": { "type": "string", "description": "Type of hook being invoked (e.g., \"preToolUse\", \"postToolUse\", \"sessionStart\")" }, "input": { "description": "Input data passed to the hook", "x-opaque-json": true } }, "required": [ "hookInvocationId", "hookType" ], "additionalProperties": false, "description": "Hook invocation start details including type and input data", "title": "HookStartData" }, "HookStartEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "hook.start", "description": "Type discriminator. Always \"hook.start\"." }, "data": { "$ref": "#/definitions/HookStartData", "description": "Hook invocation start details including type and input data" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"hook.start\". Hook invocation start details including type and input data", "title": "HookStartEvent" }, "IdleData": { "type": "object", "properties": { "aborted": { "type": "boolean", "description": "True when the preceding agentic loop was cancelled via abort signal" } }, "additionalProperties": false, "description": "Payload indicating the session is idle with no background agents or attached shell commands in flight", "title": "IdleData" }, "IdleEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.idle", "description": "Type discriminator. Always \"session.idle\"." }, "data": { "$ref": "#/definitions/IdleData", "description": "Payload indicating the session is idle with no background agents or attached shell commands in flight" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.idle\". Payload indicating the session is idle with no background agents or attached shell commands in flight", "title": "IdleEvent" }, "InfoData": { "type": "object", "properties": { "infoType": { "type": "string", "description": "Category of informational message (e.g., \"notification\", \"timing\", \"context_window\", \"mcp\", \"snapshot\", \"configuration\", \"authentication\", \"model\")" }, "message": { "type": "string", "description": "Human-readable informational message for display in the timeline" }, "url": { "type": "string", "description": "Optional URL associated with this message that the user can open in a browser" }, "tip": { "type": "string", "description": "Optional actionable tip displayed with this message" } }, "required": [ "infoType", "message" ], "additionalProperties": false, "description": "Informational message for timeline display with categorization", "title": "InfoData" }, "InfoEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.info", "description": "Type discriminator. Always \"session.info\"." }, "data": { "$ref": "#/definitions/InfoData", "description": "Informational message for timeline display with categorization" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.info\". Informational message for timeline display with categorization", "title": "InfoEvent" }, "ManagedSettingsEnforcedAction": { "type": "string", "enum": [ "bypass_permissions_blocked" ], "description": "The category of runtime action that enterprise managed settings governed (blocked or capped)", "title": "ManagedSettingsEnforcedAction", "x-enumDescriptions": { "bypass_permissions_blocked": "An attempt to turn on a bypass-permissions (\"yolo\") escalation was refused or capped because policy disables bypass-permissions mode." } }, "ManagedSettingsEnforcedData": { "type": "object", "properties": { "action": { "$ref": "#/definitions/ManagedSettingsEnforcedAction", "description": "The category of runtime action that managed policy governed." }, "escalation": { "$ref": "#/definitions/ManagedSettingsEnforcedEscalation", "description": "For a `bypass_permissions_blocked` action, which permission-escalation primitive was refused. Absent for actions without a specific escalation primitive." }, "setting": { "type": "string", "description": "The managed setting key responsible for the enforcement (e.g. `permissions.disableBypassPermissionsMode`)." }, "failClosed": { "type": "boolean", "description": "Whether the enforcement was forced by fail-closed handling (managed policy could not be determined) rather than an explicit managed setting. When true, `setting` still names the restriction that was applied." }, "message": { "type": "string", "description": "A human-readable explanation of why the action was governed, suitable for surfacing to the user." } }, "required": [ "action", "setting", "failClosed", "message" ], "additionalProperties": false, "description": "Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes.", "title": "ManagedSettingsEnforcedData", "stability": "experimental" }, "ManagedSettingsEnforcedEscalation": { "type": "string", "enum": [ "allow_all", "approve_all", "auto_approval", "unrestricted_paths", "unrestricted_urls" ], "description": "For a `bypass_permissions_blocked` action, which permission-escalation primitive was refused", "title": "ManagedSettingsEnforcedEscalation", "x-enumDescriptions": { "allow_all": "Full allow-all (\"/allow-all on\") permissions — auto-approving tools, paths, and URLs.", "approve_all": "Auto-approval of all tool permission requests.", "auto_approval": "Advisory auto-approval (\"/allow-all auto\") mode — keeps normal prompt paths and adds LLM-advised approval, distinct from full allow-all.", "unrestricted_paths": "Unrestricted filesystem access outside the session's allowed directories.", "unrestricted_urls": "Unrestricted URL fetch access." } }, "ManagedSettingsEnforcedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.managed_settings_enforced", "description": "Type discriminator. Always \"session.managed_settings_enforced\"." }, "data": { "$ref": "#/definitions/ManagedSettingsEnforcedData", "description": "Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.managed_settings_enforced\". Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes.", "title": "ManagedSettingsEnforcedEvent", "stability": "experimental" }, "ManagedSettingsResolvedData": { "type": "object", "properties": { "source": { "$ref": "#/definitions/ManagedSettingsResolvedSource", "description": "Channel summary: `server`, `device`, or `client` when exactly one channel contributed; `mixed` when multiple channels contributed; otherwise `none`. Consult the per-channel booleans for exact provenance." }, "serverManaged": { "type": "boolean", "description": "Whether the server (account/org) managed-settings layer was present" }, "deviceManaged": { "type": "boolean", "description": "Whether an actual device MDM/plist/registry/file managed-settings layer was present" }, "clientManaged": { "type": "boolean", "description": "Whether a session-local permissions layer injected by the SDK host was present" }, "failClosed": { "type": "boolean", "description": "Whether managed policy could not be determined (e.g. a failed server fetch) and the session fell back to the fail-closed restriction. When true, restrictions such as disabling bypass-permissions are enforced even though `settings` may be absent." }, "bypassPermissionsDisabled": { "type": "boolean", "description": "Whether enterprise policy disables bypass-permissions (\"yolo\") mode for this session. Deny-wins across layers, and forced on when `failClosed` is true." }, "permissionsAllowIntersected": { "type": "boolean", "description": "Whether at least two managed sources supplied permission allowlists, so enforcement intersects them and the flattened settings payload omits `permissions.allow`." }, "managedKeys": { "type": "array", "items": { "type": "string" }, "description": "The setting keys under enterprise management in the effective managed settings (e.g. `model`, `enabledPlugins`, `permissions`). Empty when no managed settings are in force." }, "settings": { "description": "The effective (resolved) managed settings values, so clients can render exactly what is enforced. Absent when no managed policy is in force.", "x-opaque-json": true } }, "required": [ "source", "serverManaged", "deviceManaged", "failClosed", "bypassPermissionsDisabled", "managedKeys" ], "additionalProperties": false, "description": "Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted. Device values take precedence over server values per ordinary key, while permissions compose restrictively across device, server, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes.", "title": "ManagedSettingsResolvedData", "stability": "experimental" }, "ManagedSettingsResolvedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.managed_settings_resolved", "description": "Type discriminator. Always \"session.managed_settings_resolved\"." }, "data": { "$ref": "#/definitions/ManagedSettingsResolvedData", "description": "Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted. Device values take precedence over server values per ordinary key, while permissions compose restrictively across device, server, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.managed_settings_resolved\". Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted. Device values take precedence over server values per ordinary key, while permissions compose restrictively across device, server, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes.", "title": "ManagedSettingsResolvedEvent", "stability": "experimental" }, "ManagedSettingsResolvedSource": { "type": "string", "enum": [ "server", "device", "client", "mixed", "none" ], "description": "Summary of which managed-settings channels contributed to the effective session policy. Use the per-channel booleans for exact provenance.", "title": "ManagedSettingsResolvedSource", "x-enumDescriptions": { "server": "Only the server/account channel contributed.", "device": "Only the device MDM/plist/registry/file channel contributed.", "client": "Only session-local SDK-host injection contributed.", "mixed": "More than one channel contributed. Ordinary keys resolve device over server per key, while permissions compose restrictively across all present layers.", "none": "No managed policy is in force (no channel contributed)." } }, "McpAppToolCallCompleteData": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Name of the MCP server hosting the tool" }, "toolName": { "type": "string", "description": "MCP tool name that was invoked" }, "arguments": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Arguments passed to the tool by the app view, if any" }, "success": { "type": "boolean", "description": "True when the call completed without throwing AND the MCP CallToolResult did not set isError" }, "durationMs": { "type": "number", "description": "Wall-clock duration of the underlying tools/call in milliseconds" }, "result": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Standard MCP CallToolResult returned by the server. Present whether or not the call set isError." }, "error": { "$ref": "#/definitions/McpAppToolCallCompleteError", "description": "Set when the underlying tools/call threw an error before returning a CallToolResult" }, "toolMeta": { "$ref": "#/definitions/McpAppToolCallCompleteToolMeta", "description": "The tool's `_meta.ui` block at the time of the call, so consumers can decide whether to forward the result to the model without re-listing tools." } }, "required": [ "serverName", "toolName", "success", "durationMs" ], "additionalProperties": false, "description": "MCP App view called a tool on a connected MCP server (SEP-1865)", "title": "McpAppToolCallCompleteData" }, "McpAppToolCallCompleteError": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "message" ], "additionalProperties": false, "description": "Set when the underlying tools/call threw an error before returning a CallToolResult", "title": "McpAppToolCallCompleteError" }, "McpAppToolCallCompleteEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp_app.tool_call_complete", "description": "Type discriminator. Always \"mcp_app.tool_call_complete\"." }, "data": { "$ref": "#/definitions/McpAppToolCallCompleteData", "description": "MCP App view called a tool on a connected MCP server (SEP-1865)" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp_app.tool_call_complete\". MCP App view called a tool on a connected MCP server (SEP-1865)", "title": "McpAppToolCallCompleteEvent" }, "McpAppToolCallCompleteToolMeta": { "type": "object", "properties": { "ui": { "$ref": "#/definitions/McpAppToolCallCompleteToolMetaUI", "description": "MCP App tool `_meta.ui` resource URI and SEP-1865 visibility captured with an `mcp_app.tool_call_complete` result." } }, "description": "The tool's `_meta.ui` block at the time of the call, so consumers can decide whether to forward the result to the model without re-listing tools.", "title": "McpAppToolCallCompleteToolMeta" }, "McpAppToolCallCompleteToolMetaUI": { "type": "object", "properties": { "resourceUri": { "type": "string", "description": "`ui://` URI declared by the tool's `_meta.ui.resourceUri`" }, "visibility": { "type": "array", "items": { "type": "string" }, "description": "Tool visibility per SEP-1865 (typically a subset of `[\"model\",\"app\"]`)" } }, "description": "MCP App tool `_meta.ui` resource URI and SEP-1865 visibility captured with an `mcp_app.tool_call_complete` result.", "title": "McpAppToolCallCompleteToolMetaUI" }, "McpHeadersRefreshCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved headers refresh request" }, "outcome": { "$ref": "#/definitions/McpHeadersRefreshCompletedOutcome", "description": "How the pending MCP headers refresh request resolved." } }, "required": [ "requestId", "outcome" ], "additionalProperties": false, "description": "MCP headers refresh request completion notification", "title": "McpHeadersRefreshCompletedData" }, "McpHeadersRefreshCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp.headers_refresh_completed", "description": "Type discriminator. Always \"mcp.headers_refresh_completed\"." }, "data": { "$ref": "#/definitions/McpHeadersRefreshCompletedData", "description": "MCP headers refresh request completion notification" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp.headers_refresh_completed\". MCP headers refresh request completion notification", "title": "McpHeadersRefreshCompletedEvent" }, "McpHeadersRefreshCompletedOutcome": { "type": "string", "enum": [ "headers", "none", "timeout" ], "description": "How the pending MCP headers refresh request resolved.", "title": "McpHeadersRefreshCompletedOutcome", "x-enumDescriptions": { "headers": "The host supplied dynamic headers.", "none": "The host responded with no dynamic headers.", "timeout": "No response arrived within the bounded window." } }, "McpHeadersRefreshRequiredData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this headers refresh request; used to respond via session.mcp.headers.handlePendingHeadersRefreshRequest()" }, "serverName": { "type": "string", "description": "Display name of the remote MCP server requesting headers" }, "serverUrl": { "type": "string", "description": "URL of the remote MCP server requesting headers" }, "reason": { "$ref": "#/definitions/McpHeadersRefreshRequiredReason", "description": "Why dynamic headers are being requested." } }, "required": [ "requestId", "serverName", "serverUrl", "reason" ], "additionalProperties": false, "description": "Dynamic headers refresh request for a remote MCP server", "title": "McpHeadersRefreshRequiredData" }, "McpHeadersRefreshRequiredEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp.headers_refresh_required", "description": "Type discriminator. Always \"mcp.headers_refresh_required\"." }, "data": { "$ref": "#/definitions/McpHeadersRefreshRequiredData", "description": "Dynamic headers refresh request for a remote MCP server" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp.headers_refresh_required\". Dynamic headers refresh request for a remote MCP server", "title": "McpHeadersRefreshRequiredEvent" }, "McpHeadersRefreshRequiredReason": { "type": "string", "enum": [ "startup", "ttl-expired", "auth-failed" ], "description": "Why dynamic headers are being requested.", "title": "McpHeadersRefreshRequiredReason", "x-enumDescriptions": { "startup": "The transport is making its first dynamic header request for this server.", "ttl-expired": "The previously cached dynamic headers expired.", "auth-failed": "The server returned 401 and stale dynamic headers were invalidated." } }, "McpListChangedData": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Name of the MCP server whose list changed" } }, "required": [ "serverName" ], "additionalProperties": false, "description": "Payload identifying the MCP server associated with a list change.", "title": "McpListChangedData" }, "McpOauthCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved OAuth request" }, "outcome": { "$ref": "#/definitions/McpOauthCompletionOutcome", "description": "How the pending OAuth request was completed" } }, "required": [ "requestId", "outcome" ], "additionalProperties": false, "description": "MCP OAuth request completion notification", "title": "McpOauthCompletedData" }, "McpOauthCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp.oauth_completed", "description": "Type discriminator. Always \"mcp.oauth_completed\"." }, "data": { "$ref": "#/definitions/McpOauthCompletedData", "description": "MCP OAuth request completion notification" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp.oauth_completed\". MCP OAuth request completion notification", "title": "McpOauthCompletedEvent" }, "McpOauthCompletionOutcome": { "type": "string", "enum": [ "token", "cancelled" ], "description": "How the pending MCP OAuth request was completed", "title": "McpOauthCompletionOutcome", "x-enumDescriptions": { "token": "The request completed with a token-backed OAuth provider.", "cancelled": "The request completed without an OAuth provider." } }, "McpOauthHttpResponse": { "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": 100, "maximum": 999, "description": "HTTP status code returned with the auth challenge." }, "headers": { "type": "array", "items": { "$ref": "#/definitions/HeaderEntry", "description": "Single HTTP header entry as a name/value pair." }, "description": "HTTP response headers as observed by the runtime. Order and casing are transport-dependent, and duplicate header names may appear multiple times." }, "body": { "type": "string", "description": "Complete UTF-8 response body for host-specific challenge handling, including an empty string for an empty body. Omitted when the complete body is not valid UTF-8; body read failures fail the HTTP operation rather than exposing a partial response." } }, "required": [ "statusCode", "headers" ], "additionalProperties": false, "description": "Raw HTTP response details from the OAuth auth challenge, as observed by the runtime.", "title": "McpOauthHttpResponse" }, "McpOauthRequestReason": { "type": "string", "enum": [ "initial", "refresh", "reauth", "upscope" ], "description": "Reason the runtime is requesting host-provided MCP OAuth credentials", "title": "McpOauthRequestReason", "x-enumDescriptions": { "initial": "Initial credentials are required before connecting to the MCP server.", "refresh": "The current host-provided credential was rejected and a replacement is requested.", "reauth": "The server requires a new host authorization flow before continuing.", "upscope": "The server requires a credential with additional scope or audience." } }, "McpOauthRequiredData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this OAuth request; used to respond via session.mcp.oauth.handlePendingRequest" }, "serverName": { "type": "string", "description": "Display name of the MCP server that requires OAuth" }, "serverUrl": { "type": "string", "description": "URL of the MCP server that requires OAuth" }, "staticClientConfig": { "$ref": "#/definitions/McpOauthRequiredStaticClientConfig", "description": "Static OAuth client configuration, if the server specifies one" }, "wwwAuthenticateParams": { "$ref": "#/definitions/McpOauthWWWAuthenticateParams", "description": "OAuth WWW-Authenticate parameters parsed from the auth challenge, if available" }, "httpResponse": { "$ref": "#/definitions/McpOauthHttpResponse", "description": "Raw HTTP response details from the OAuth auth challenge, as observed by the runtime. Header order and casing are transport-dependent, and duplicate header names may appear multiple times." }, "resourceMetadata": { "type": "string", "description": "Raw OAuth protected-resource metadata document fetched for the MCP server, if available" }, "reason": { "$ref": "#/definitions/McpOauthRequestReason", "description": "Why the runtime is requesting host-provided OAuth credentials." } }, "required": [ "requestId", "serverName", "serverUrl", "reason" ], "additionalProperties": false, "description": "OAuth authentication request for an MCP server", "title": "McpOauthRequiredData" }, "McpOauthRequiredEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp.oauth_required", "description": "Type discriminator. Always \"mcp.oauth_required\"." }, "data": { "$ref": "#/definitions/McpOauthRequiredData", "description": "OAuth authentication request for an MCP server" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp.oauth_required\". OAuth authentication request for an MCP server", "title": "McpOauthRequiredEvent" }, "McpOauthRequiredStaticClientConfig": { "type": "object", "properties": { "clientId": { "type": "string", "description": "OAuth client ID for the server" }, "clientSecret": { "type": "string", "description": "Optional OAuth client secret for confidential static clients, when the runtime can resolve one" }, "publicClient": { "type": "boolean", "description": "Whether this is a public OAuth client" }, "grantType": { "type": "string", "const": "client_credentials", "description": "Optional non-default OAuth grant type. When set to 'client_credentials', the OAuth flow runs headlessly using the client_id + keychain-stored secret (no browser, no callback server)." } }, "required": [ "clientId" ], "additionalProperties": false, "description": "Static OAuth client configuration, if the server specifies one", "title": "McpOauthRequiredStaticClientConfig" }, "McpOauthWWWAuthenticateParams": { "type": "object", "properties": { "resourceMetadataUrl": { "type": "string", "description": "Protected resource metadata URL from the WWW-Authenticate resource_metadata parameter, if present" }, "scope": { "type": "string", "description": "Requested OAuth scopes from the WWW-Authenticate scope parameter, if present" }, "error": { "type": "string", "description": "OAuth error from the WWW-Authenticate error parameter, if present" } }, "additionalProperties": false, "description": "OAuth WWW-Authenticate parameters parsed from an MCP auth challenge", "title": "McpOauthWWWAuthenticateParams" }, "McpPromptsListChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp.prompts.list_changed", "description": "Type discriminator. Always \"mcp.prompts.list_changed\"." }, "data": { "$ref": "#/definitions/McpListChangedData", "description": "Payload identifying the MCP server associated with a list change." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp.prompts.list_changed\". Payload identifying the MCP server associated with a list change.", "title": "McpPromptsListChangedEvent" }, "McpResourcesListChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp.resources.list_changed", "description": "Type discriminator. Always \"mcp.resources.list_changed\"." }, "data": { "$ref": "#/definitions/McpListChangedData", "description": "Payload identifying the MCP server associated with a list change." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp.resources.list_changed\". Payload identifying the MCP server associated with a list change.", "title": "McpResourcesListChangedEvent" }, "McpServersLoadedData": { "type": "object", "properties": { "servers": { "type": "array", "items": { "$ref": "#/definitions/McpServersLoadedServer", "description": "A single MCP server status summary in `session.mcp_servers_loaded`, including name, status, source, transport, and plugin metadata." }, "description": "Array of MCP server status summaries" } }, "required": [ "servers" ], "additionalProperties": false, "description": "Payload of `session.mcp_servers_loaded` listing MCP server status summaries.", "title": "McpServersLoadedData" }, "McpServersLoadedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.mcp_servers_loaded", "description": "Type discriminator. Always \"session.mcp_servers_loaded\"." }, "data": { "$ref": "#/definitions/McpServersLoadedData", "description": "Payload of `session.mcp_servers_loaded` listing MCP server status summaries." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.mcp_servers_loaded\". Payload of `session.mcp_servers_loaded` listing MCP server status summaries.", "title": "McpServersLoadedEvent" }, "McpServersLoadedServer": { "type": "object", "properties": { "name": { "type": "string", "description": "Server name (config key)" }, "status": { "$ref": "#/definitions/McpServerStatus", "description": "Connection status: connected, failed, needs-auth, pending, disabled, stopped, or not_configured" }, "source": { "$ref": "#/definitions/McpServerSource", "description": "Configuration source: user, workspace, plugin, or builtin" }, "error": { "type": "string", "description": "Error message if the server failed to connect" }, "transport": { "$ref": "#/definitions/McpServerTransport", "description": "Transport mechanism: stdio, http, sse (deprecated), or memory (in-process MCP server)" }, "pluginName": { "type": "string", "description": "Name of the plugin that supplied the effective MCP server config, only when source is plugin" }, "pluginVersion": { "type": "string", "description": "Version of the plugin that supplied the effective MCP server config, only when source is plugin" } }, "required": [ "name", "status" ], "additionalProperties": false, "description": "A single MCP server status summary in `session.mcp_servers_loaded`, including name, status, source, transport, and plugin metadata.", "title": "McpServersLoadedServer" }, "McpServerSource": { "type": "string", "enum": [ "user", "workspace", "plugin", "builtin" ], "description": "Configuration source: user, workspace, plugin, or builtin", "title": "McpServerSource", "x-enumDescriptions": { "user": "Server configured in the user's global MCP configuration.", "workspace": "Server configured by the current workspace.", "plugin": "Server contributed by an installed plugin.", "builtin": "Server bundled with the runtime." } }, "McpServerStatus": { "type": "string", "enum": [ "connected", "failed", "needs-auth", "pending", "disabled", "stopped", "not_configured" ], "description": "Connection status: connected, failed, needs-auth, pending, disabled, stopped, or not_configured", "title": "McpServerStatus", "x-enumDescriptions": { "connected": "The server is connected and available.", "failed": "The server failed to connect or initialize.", "needs-auth": "The server requires authentication before it can connect.", "pending": "The server connection is still being established.", "disabled": "The server is configured but disabled.", "stopped": "The server was intentionally stopped and can be restarted on demand when policy permits; a server quarantined by restrictive managed policy stays stopped and cannot be restarted until the policy allows it.", "not_configured": "The server is not configured for this session." } }, "McpServerStatusChangedData": { "type": "object", "properties": { "serverName": { "type": "string", "description": "Name of the MCP server whose status changed" }, "status": { "$ref": "#/definitions/McpServerStatus", "description": "Connection status: connected, failed, needs-auth, pending, disabled, stopped, or not_configured" }, "error": { "type": "string", "description": "Error message if the server entered a failed state" } }, "required": [ "serverName", "status" ], "additionalProperties": false, "description": "Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error.", "title": "McpServerStatusChangedData" }, "McpServerStatusChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.mcp_server_status_changed", "description": "Type discriminator. Always \"session.mcp_server_status_changed\"." }, "data": { "$ref": "#/definitions/McpServerStatusChangedData", "description": "Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.mcp_server_status_changed\". Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error.", "title": "McpServerStatusChangedEvent" }, "McpServerTransport": { "type": "string", "enum": [ "stdio", "http", "sse", "memory" ], "description": "Transport mechanism: stdio, http, sse (deprecated), or memory (in-process MCP server)", "title": "McpServerTransport", "x-enumDescriptions": { "stdio": "Server communicates over stdio with a local child process.", "http": "Server communicates over streamable HTTP.", "sse": "Server communicates over Server-Sent Events (deprecated).", "memory": "Server is backed by an in-memory runtime implementation." } }, "McpToolsListChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "mcp.tools.list_changed", "description": "Type discriminator. Always \"mcp.tools.list_changed\"." }, "data": { "$ref": "#/definitions/McpListChangedData", "description": "Payload identifying the MCP server associated with a list change." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"mcp.tools.list_changed\". Payload identifying the MCP server associated with a list change.", "title": "McpToolsListChangedEvent" }, "MemoryChangedData": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Signal-only event: the agent successfully stored a memory (store_memory) or voted on one (vote_memory). No payload — consumers should re-fetch memories to pick up the change. Used to refresh memory context (e.g. re-running the context sidekick) so newly written memories surface in subsequent turns.", "title": "MemoryChangedData", "visibility": "internal" }, "MemoryChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.memory_changed", "description": "Type discriminator. Always \"session.memory_changed\"." }, "data": { "$ref": "#/definitions/MemoryChangedData", "description": "Signal-only event: the agent successfully stored a memory (store_memory) or voted on one (vote_memory). No payload — consumers should re-fetch memories to pick up the change. Used to refresh memory context (e.g. re-running the context sidekick) so newly written memories surface in subsequent turns." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.memory_changed\". Signal-only event: the agent successfully stored a memory (store_memory) or voted on one (vote_memory). No payload — consumers should re-fetch memories to pick up the change. Used to refresh memory context (e.g. re-running the context sidekick) so newly written memories surface in subsequent turns.", "title": "MemoryChangedEvent", "visibility": "internal" }, "ModeChangedData": { "type": "object", "properties": { "previousMode": { "$ref": "#/definitions/SessionMode", "description": "The session mode the agent is operating in" }, "newMode": { "$ref": "#/definitions/SessionMode", "description": "The session mode the agent is operating in" } }, "required": [ "previousMode", "newMode" ], "additionalProperties": false, "description": "Agent mode change details including previous and new modes", "title": "ModeChangedData" }, "ModeChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.mode_changed", "description": "Type discriminator. Always \"session.mode_changed\"." }, "data": { "$ref": "#/definitions/ModeChangedData", "description": "Agent mode change details including previous and new modes" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.mode_changed\". Agent mode change details including previous and new modes", "title": "ModeChangedEvent" }, "ModelCallFailureBadRequestKind": { "type": "string", "enum": [ "bodyless", "structured_error" ], "description": "For HTTP 400 failures only: whether the response carried a structured CAPI error envelope (structured_error, a deterministic validation failure) or no error body (bodyless, the transient gateway/proxy signature). Absent for non-400 failures.", "title": "ModelCallFailureBadRequestKind", "x-enumDescriptions": { "bodyless": "The 400 response carried no error body (transient gateway/proxy signature).", "structured_error": "The 400 response carried a structured CAPI error envelope (deterministic validation failure)." } }, "ModelCallFailureData": { "type": "object", "properties": { "model": { "type": "string", "description": "Model identifier used for the failed API call" }, "initiator": { "type": "string", "description": "What initiated this API call (e.g., \"sub-agent\", \"mcp-sampling\"); absent for user-initiated calls" }, "apiCallId": { "type": "string", "description": "Completion ID from the model provider (e.g., chatcmpl-abc123)" }, "providerCallId": { "type": "string", "description": "GitHub request tracing ID (x-github-request-id header) for server-side log correlation" }, "serviceRequestId": { "type": "string", "description": "Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation" }, "rte": { "type": "boolean" }, "statusCode": { "type": "integer", "minimum": 0, "maximum": 999, "description": "HTTP status code from the failed request" }, "durationMs": { "type": "integer", "minimum": 0, "format": "duration", "description": "Duration of the failed API call in milliseconds" }, "apiEndpoint": { "$ref": "#/definitions/AssistantUsageApiEndpoint", "description": "API endpoint used for this model call, matching CAPI supported_endpoints vocabulary" }, "transport": { "$ref": "#/definitions/ModelCallFailureTransport", "description": "Transport used for the failed model call (http or websocket)" }, "failureKind": { "$ref": "#/definitions/ModelCallFailureKind", "description": "Whether the failure originated from an API response or the request transport" }, "maxPromptTokens": { "type": "integer", "minimum": 0, "description": "Effective maximum prompt-token limit for the failed call" }, "maxOutputTokens": { "type": "integer", "minimum": 0, "description": "Effective maximum output-token limit for the failed call" }, "isByok": { "type": "boolean", "description": "Whether the failed call used a bring-your-own-key provider" }, "isAuto": { "type": "boolean", "description": "Whether the session selected Auto mode for the failed call" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort level used for the failed model call, if applicable" }, "source": { "$ref": "#/definitions/ModelCallFailureSource", "description": "Where the failed model call originated" }, "errorMessage": { "type": "string", "description": "Raw provider/runtime error message for restricted telemetry" }, "badRequestKind": { "$ref": "#/definitions/ModelCallFailureBadRequestKind", "description": "For HTTP 400 failures only: whether the response carried a structured CAPI error envelope (structured_error, a deterministic validation failure) or no error body (bodyless, the transient gateway/proxy signature). Absent for non-400 failures." }, "errorCode": { "type": "string", "description": "For HTTP 400 failures only: the `code` from the CAPI error envelope (e.g. 'model_max_prompt_tokens_exceeded') identifying which deterministic validation failure occurred. Raw server-controlled string, emitted only through restricted telemetry. Absent for bodyless or non-400 failures." }, "errorType": { "type": "string", "description": "For HTTP 400 failures only: the `type` from the CAPI error envelope (e.g. 'websocket_error'), a coarser companion to errorCode for envelopes that carry no code. Raw server-controlled string, emitted only through restricted telemetry. Absent for bodyless or non-400 failures." }, "quotaSnapshots": { "type": "object", "additionalProperties": { "$ref": "#/definitions/AssistantUsageQuotaSnapshot", "description": "Internal per-quota snapshot for assistant usage, including entitlement, consumed requests, overage, reset date, and remaining quota.", "visibility": "internal" }, "description": "Per-quota usage snapshots parsed from the failed response's quota headers, keyed by quota identifier. Present when the error response carried quota headers (e.g. a 402 once the additional spend limit is reached) so the UI can refresh the quota display on failure.", "visibility": "internal" }, "requestFingerprint": { "$ref": "#/definitions/ModelCallFailureRequestFingerprint", "description": "Content-free structural summary of the failing request. Contains only counts and shape flags (no prompt content), so it is safe for unrestricted telemetry. Populated only for client-error (4xx) failures." } }, "required": [ "source" ], "additionalProperties": false, "description": "Failed LLM API call metadata for telemetry", "title": "ModelCallFailureData" }, "ModelCallFailureEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "model.call_failure", "description": "Type discriminator. Always \"model.call_failure\"." }, "data": { "$ref": "#/definitions/ModelCallFailureData", "description": "Failed LLM API call metadata for telemetry" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"model.call_failure\". Failed LLM API call metadata for telemetry", "title": "ModelCallFailureEvent" }, "ModelCallFailureKind": { "type": "string", "enum": [ "api", "transport" ], "description": "Boundary that produced a model call failure", "title": "ModelCallFailureKind", "x-enumDescriptions": { "api": "The provider returned an API error response.", "transport": "The request transport failed before a usable API response completed." } }, "ModelCallFailureRequestFingerprint": { "type": "object", "properties": { "messageCount": { "type": "integer", "minimum": 0, "description": "Total number of messages in the request" }, "toolResultMessageCount": { "type": "integer", "minimum": 0, "description": "Number of \"tool\" result messages in the request" }, "toolCallCount": { "type": "integer", "minimum": 0, "description": "Total number of tool calls across assistant messages" }, "namelessToolCallCount": { "type": "integer", "minimum": 0, "description": "Tool calls whose name is missing or empty (rejected by strict providers)" }, "imagePartCount": { "type": "integer", "minimum": 0, "description": "Total number of image content parts" }, "imagePartsMissingMediaType": { "type": "integer", "minimum": 0, "description": "Image parts whose media type cannot be determined (rejected by strict providers)" }, "lastMessageRole": { "type": "string", "description": "Role of the final message in the request" } }, "required": [ "messageCount", "toolResultMessageCount", "toolCallCount", "namelessToolCallCount", "imagePartCount", "imagePartsMissingMediaType" ], "additionalProperties": false, "description": "Content-free structural summary of the failing request for diagnosing malformed 4xx calls", "title": "ModelCallFailureRequestFingerprint" }, "ModelCallFailureSource": { "type": "string", "enum": [ "top_level", "subagent", "mcp_sampling" ], "description": "Where the failed model call originated", "title": "ModelCallFailureSource", "x-enumDescriptions": { "top_level": "Model call from the top-level agent.", "subagent": "Model call from a sub-agent.", "mcp_sampling": "Model call from MCP sampling." } }, "ModelCallFailureTransport": { "type": "string", "enum": [ "http", "websocket" ], "description": "Transport used for a failed model call", "title": "ModelCallFailureTransport", "x-enumDescriptions": { "http": "HTTP transport, including SSE streams.", "websocket": "WebSocket transport." } }, "ModelCallStartData": { "type": "object", "properties": { "turnId": { "type": "string", "description": "Identifier of the assistant turn that initiated the model call" }, "model": { "type": "string", "description": "Model identifier used for this API call, when known" }, "previousResponseId": { "type": "string", "description": "Previous response or interaction identifier included in the model request, when present", "visibility": "internal" } }, "required": [ "turnId" ], "additionalProperties": false, "description": "Model API dispatch metadata for internal telemetry", "title": "ModelCallStartData" }, "ModelCallStartEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "model.call_start", "description": "Type discriminator. Always \"model.call_start\"." }, "data": { "$ref": "#/definitions/ModelCallStartData", "description": "Model API dispatch metadata for internal telemetry" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"model.call_start\". Model API dispatch metadata for internal telemetry", "title": "ModelCallStartEvent", "visibility": "internal" }, "ModelChangeData": { "type": "object", "properties": { "previousModel": { "type": "string", "description": "Model that was previously selected, if any" }, "newModel": { "type": "string", "description": "Newly selected model identifier" }, "previousReasoningEffort": { "type": "string", "description": "Reasoning effort level before the model change, if applicable" }, "reasoningEffort": { "type": [ "string", "null" ], "description": "Reasoning effort level after the model change, if applicable" }, "previousReasoningSummary": { "$ref": "#/definitions/ReasoningSummary", "description": "Reasoning summary mode before the model change, if applicable" }, "reasoningSummary": { "$ref": "#/definitions/ReasoningSummary", "description": "Reasoning summary mode after the model change, if applicable" }, "previousVerbosity": { "$ref": "#/definitions/Verbosity", "description": "Output verbosity level before the model change, if applicable" }, "verbosity": { "$ref": "#/definitions/Verbosity", "description": "Output verbosity level after the model change, if applicable" }, "contextTier": { "anyOf": [ { "$ref": "#/definitions/ContextTier" }, { "type": "null" } ], "description": "Context tier after the model change; null explicitly clears a previously selected tier" }, "cause": { "type": "string", "description": "Reason the change happened, when not user-initiated. `\"rate_limit_auto_switch\"` for changes triggered by the auto-mode-switch rate-limit recovery path, or `\"refusal_fallback\"` when the active model declined a request (content refusal) and the runtime switched to the configured refusal-fallback model. UI clients can use this to render contextual copy." } }, "required": [ "newModel" ], "additionalProperties": false, "description": "Model change details including previous and new model identifiers", "title": "ModelChangeData" }, "ModelChangeEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.model_change", "description": "Type discriminator. Always \"session.model_change\"." }, "data": { "$ref": "#/definitions/ModelChangeData", "description": "Model change details including previous and new model identifiers" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.model_change\". Model change details including previous and new model identifiers", "title": "ModelChangeEvent" }, "OmittedBinaryOmittedReason": { "type": "string", "enum": [ "too_large", "asset_unavailable" ], "description": "Why the binary data is absent: it exceeded the inline size limit, or its asset was unavailable", "title": "OmittedBinaryOmittedReason", "x-enumDescriptions": { "too_large": "Bytes exceeded the session's inline size limit.", "asset_unavailable": "The referenced binary asset could not be found (e.g. a truncated log)." } }, "OmittedBinaryResult": { "type": "object", "properties": { "type": { "$ref": "#/definitions/OmittedBinaryType", "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data." }, "mimeType": { "type": "string", "description": "MIME type of the omitted binary data" }, "byteLength": { "type": "integer", "minimum": 0, "description": "Decoded byte length of the omitted binary data" }, "omittedReason": { "$ref": "#/definitions/OmittedBinaryOmittedReason", "description": "Why the binary data is absent: it exceeded the inline size limit, or its asset was unavailable" }, "description": { "type": "string", "description": "Human-readable description of the binary data" }, "metadata": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Optional metadata from the producing tool." } }, "required": [ "type", "mimeType", "byteLength", "omittedReason" ], "additionalProperties": false, "description": "A binary result whose data was omitted from persistence due to the inline size limit", "title": "OmittedBinaryResult", "stability": "experimental" }, "OmittedBinaryType": { "type": "string", "enum": [ "image", "resource" ], "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data.", "title": "OmittedBinaryType", "x-enumDescriptions": { "image": "Binary image data.", "resource": "Other binary resource data." } }, "PendingMessagesModifiedData": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Empty payload; the event signals that the pending message queue has changed", "title": "PendingMessagesModifiedData" }, "PendingMessagesModifiedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "pending_messages.modified", "description": "Type discriminator. Always \"pending_messages.modified\"." }, "data": { "$ref": "#/definitions/PendingMessagesModifiedData", "description": "Empty payload; the event signals that the pending message queue has changed" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"pending_messages.modified\". Empty payload; the event signals that the pending message queue has changed", "title": "PendingMessagesModifiedEvent" }, "PermissionAllowAllMode": { "type": "string", "enum": [ "off", "on", "auto" ], "description": "Allow-all mode for the session.", "title": "PermissionAllowAllMode", "x-enumDescriptions": { "off": "Permission requests follow the normal approval flow.", "on": "Tool, path, and URL permission requests are automatically approved.", "auto": "Permission requests follow the normal approval flow with an LLM advisory recommendation attached; clients may choose to auto-approve requests the judge evaluated as acceptable." }, "stability": "experimental" }, "PermissionApproved": { "type": "object", "properties": { "kind": { "type": "string", "const": "approved", "description": "The permission request was approved" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Permission response variant indicating the request was approved without persisting an approval rule.", "title": "PermissionApproved" }, "PermissionApprovedForLocation": { "type": "object", "properties": { "kind": { "type": "string", "const": "approved-for-location", "description": "Approved and persisted for this project location" }, "approval": { "$ref": "#/definitions/UserToolSessionApproval", "description": "The approval to persist for this location" }, "locationKey": { "type": "string", "description": "The location key (git root or cwd) to persist the approval to" } }, "required": [ "kind", "approval", "locationKey" ], "additionalProperties": false, "description": "Permission response variant that approves a request and persists the provided approval to a project location key.", "title": "PermissionApprovedForLocation" }, "PermissionApprovedForSession": { "type": "object", "properties": { "kind": { "type": "string", "const": "approved-for-session", "description": "Approved and remembered for the rest of the session" }, "approval": { "$ref": "#/definitions/UserToolSessionApproval", "description": "The approval to add as a session-scoped rule" } }, "required": [ "kind", "approval" ], "additionalProperties": false, "description": "Permission response variant that approves a request and remembers the provided approval for the rest of the session.", "title": "PermissionApprovedForSession" }, "PermissionAutoApproval": { "type": "object", "properties": { "recommendation": { "$ref": "#/definitions/AutoApprovalRecommendation", "description": "The auto-approval safety judge's outcome for this request." }, "reason": { "type": "string", "description": "Human-readable reason for the judge's recommendation, when available." }, "model": { "type": "string", "description": "Model id that produced the recommendation, when the judge was consulted and reported one. Absent for `excluded` (the judge was not consulted) and for failures that occurred before a model was selected." }, "failureReason": { "$ref": "#/definitions/AutoApprovalJudgeFailureReason", "description": "Classified cause of an `error` recommendation. Absent for every other recommendation." } }, "required": [ "recommendation" ], "additionalProperties": false, "description": "Auto-approval judge information attached to a permission request. Present (non-null) only when the session's allow-all mode is \"auto\"; its absence means auto mode was off and the judge did not evaluate the request. The `recommendation` conveys the judge's disposition for this request.", "title": "PermissionAutoApproval", "stability": "experimental" }, "PermissionCancelled": { "type": "object", "properties": { "kind": { "type": "string", "const": "cancelled", "description": "The permission request was cancelled before a response was used" }, "reason": { "type": "string", "description": "Optional explanation of why the request was cancelled" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Permission response variant indicating the request was cancelled before use, with an optional reason.", "title": "PermissionCancelled" }, "PermissionCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved permission request; clients should dismiss any UI for this request" }, "toolCallId": { "type": "string", "description": "Optional tool call ID associated with this permission prompt; clients may use it to correlate UI created from tool-scoped prompts" }, "result": { "$ref": "#/definitions/PermissionResult", "description": "The result of the permission request" } }, "required": [ "requestId", "result" ], "additionalProperties": false, "description": "Permission request completion notification signaling UI dismissal", "title": "PermissionCompletedData" }, "PermissionCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "permission.completed", "description": "Type discriminator. Always \"permission.completed\"." }, "data": { "$ref": "#/definitions/PermissionCompletedData", "description": "Permission request completion notification signaling UI dismissal" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"permission.completed\". Permission request completion notification signaling UI dismissal", "title": "PermissionCompletedEvent" }, "PermissionDeniedByContentExclusionPolicy": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-by-content-exclusion-policy", "description": "Denied by the organization's content exclusion policy" }, "path": { "type": "string", "description": "File path that triggered the exclusion" }, "message": { "type": "string", "description": "Human-readable explanation of why the path was excluded" } }, "required": [ "kind", "path", "message" ], "additionalProperties": false, "description": "Permission response variant denying a path under content exclusion policy, with the path and message.", "title": "PermissionDeniedByContentExclusionPolicy" }, "PermissionDeniedByPermissionRequestHook": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-by-permission-request-hook", "description": "Denied by a permission request hook registered by an extension or plugin" }, "message": { "type": "string", "description": "Optional message from the hook explaining the denial" }, "interrupt": { "type": "boolean", "description": "Whether to interrupt the current agent turn" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Permission response variant denied by a permission-request hook, with optional message and interrupt flag.", "title": "PermissionDeniedByPermissionRequestHook" }, "PermissionDeniedByRules": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-by-rules", "description": "Denied because approval rules explicitly blocked it" }, "rules": { "type": "array", "items": { "$ref": "#/definitions/PermissionRule", "description": "A permission approval or denial rule matched against a tool request, identified by a rule kind with an optional argument value." }, "description": "Rules that denied the request" } }, "required": [ "kind", "rules" ], "additionalProperties": false, "description": "Permission response variant denied because matching approval rules explicitly blocked the request.", "title": "PermissionDeniedByRules" }, "PermissionDeniedInteractivelyByUser": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-interactively-by-user", "description": "Denied by the user during an interactive prompt" }, "feedback": { "type": "string", "description": "Optional feedback from the user explaining the denial" }, "forceReject": { "type": "boolean", "description": "Whether to force-reject the current agent turn" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Permission response variant denied in an interactive user prompt, with optional feedback and force-reject flag.", "title": "PermissionDeniedInteractivelyByUser" }, "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser": { "type": "object", "properties": { "kind": { "type": "string", "const": "denied-no-approval-rule-and-could-not-request-from-user", "description": "Denied because no approval rule matched and user confirmation was unavailable" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Permission response variant denied because no approval rule matched and user confirmation was unavailable.", "title": "PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser" }, "PermissionPromptRequest": { "anyOf": [ { "$ref": "#/definitions/PermissionPromptRequestCommands", "description": "Shell command permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestWrite", "description": "File write permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestRead", "description": "File read permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestMcp", "description": "MCP tool invocation permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestUrl", "description": "URL access permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestMemory", "description": "Memory operation permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestCustomTool", "description": "Custom tool invocation permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestPath", "description": "Path access permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestHook", "description": "Hook confirmation permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestExtensionManagement", "description": "Extension management permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestFactory", "description": "Factory run or authoring permission prompt" }, { "$ref": "#/definitions/PermissionPromptRequestExtensionPermissionAccess", "description": "Extension permission access prompt" } ], "description": "Derived user-facing permission prompt details for UI consumers", "title": "PermissionPromptRequest" }, "PermissionPromptRequestCommands": { "type": "object", "properties": { "kind": { "type": "string", "const": "commands", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "fullCommandText": { "type": "string", "description": "The complete shell command text to be executed" }, "intention": { "type": "string", "description": "Human-readable description of what the command intends to do" }, "commandIdentifiers": { "type": "array", "items": { "type": "string" }, "description": "Command identifiers covered by this approval prompt" }, "canOfferSessionApproval": { "type": "boolean", "description": "Whether the UI can offer session-wide approval for this command pattern" }, "warning": { "type": "string", "description": "Optional warning message about risks of running this command" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" } }, "required": [ "kind", "fullCommandText", "intention", "commandIdentifiers", "canOfferSessionApproval" ], "additionalProperties": false, "description": "Shell command permission prompt", "title": "PermissionPromptRequestCommands" }, "PermissionPromptRequestCustomTool": { "type": "object", "properties": { "kind": { "type": "string", "const": "custom-tool", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "toolName": { "type": "string", "description": "Name of the custom tool" }, "toolDescription": { "type": "string", "description": "Description of what the custom tool does" }, "args": { "description": "Arguments to pass to the custom tool", "x-opaque-json": true }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" } }, "required": [ "kind", "toolName", "toolDescription" ], "additionalProperties": false, "description": "Custom tool invocation permission prompt", "title": "PermissionPromptRequestCustomTool" }, "PermissionPromptRequestExtensionManagement": { "type": "object", "properties": { "kind": { "type": "string", "const": "extension-management", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "operation": { "type": "string", "description": "The extension management operation (scaffold, reload)" }, "extensionName": { "type": "string", "description": "Name of the extension being managed" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" } }, "required": [ "kind", "operation" ], "additionalProperties": false, "description": "Extension management permission prompt", "title": "PermissionPromptRequestExtensionManagement" }, "PermissionPromptRequestExtensionPermissionAccess": { "type": "object", "properties": { "kind": { "type": "string", "const": "extension-permission-access", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "extensionName": { "type": "string", "description": "Name of the extension requesting permission access" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capabilities the extension is requesting" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" } }, "required": [ "kind", "extensionName", "capabilities" ], "additionalProperties": false, "description": "Extension permission access prompt", "title": "PermissionPromptRequestExtensionPermissionAccess" }, "PermissionPromptRequestFactory": { "type": "object", "properties": { "kind": { "type": "string", "const": "factory", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "operation": { "$ref": "#/definitions/FactoryPermissionOperation", "description": "Factory operation, either run or author" }, "name": { "type": "string", "description": "Factory name" }, "description": { "type": "string", "description": "Factory description" }, "phases": { "type": "array", "items": { "$ref": "#/definitions/FactoryPermissionPhase", "description": "A declared phase shown in a factory permission prompt." }, "description": "Declared factory phases" }, "maxConcurrentSubagents": { "type": "integer", "minimum": 0, "description": "Effective concurrent-subagent limit; omitted means unlimited" }, "maxTotalSubagents": { "type": "integer", "minimum": 0, "description": "Effective total-subagent limit; omitted means unlimited" }, "timeoutSeconds": { "type": "number", "description": "Effective active-time limit in seconds; omitted means unlimited" }, "maxAiCredits": { "type": "number", "description": "Effective AI-credit limit; omitted means unlimited" }, "declaredMaxConcurrentSubagents": { "type": "integer", "minimum": 0 }, "declaredMaxTotalSubagents": { "type": "integer", "minimum": 0 }, "declaredTimeoutSeconds": { "type": "number" }, "declaredMaxAiCredits": { "type": "number" }, "approvalKey": { "type": "string", "description": "Canonical key used for scoped factory approvals" }, "canPersistApproval": { "type": "boolean", "description": "Whether this factory is eligible for persistent approval" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" } }, "required": [ "kind", "operation", "name", "description", "phases", "approvalKey", "canPersistApproval" ], "additionalProperties": false, "description": "Factory run or authoring permission prompt", "title": "PermissionPromptRequestFactory" }, "PermissionPromptRequestHook": { "type": "object", "properties": { "kind": { "type": "string", "const": "hook", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "toolName": { "type": "string", "description": "Name of the tool the hook is gating" }, "toolArgs": { "description": "Arguments of the tool call being gated", "x-opaque-json": true }, "hookMessage": { "type": "string", "description": "Optional message from the hook explaining why confirmation is needed" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" } }, "required": [ "kind", "toolName" ], "additionalProperties": false, "description": "Hook confirmation permission prompt", "title": "PermissionPromptRequestHook" }, "PermissionPromptRequestMcp": { "type": "object", "properties": { "kind": { "type": "string", "const": "mcp", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "serverName": { "type": "string", "description": "Name of the MCP server providing the tool" }, "toolName": { "type": "string", "description": "Internal name of the MCP tool" }, "toolTitle": { "type": "string", "description": "Human-readable title of the MCP tool" }, "args": { "description": "Arguments to pass to the MCP tool", "x-opaque-json": true }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" } }, "required": [ "kind", "serverName", "toolName", "toolTitle" ], "additionalProperties": false, "description": "MCP tool invocation permission prompt", "title": "PermissionPromptRequestMcp" }, "PermissionPromptRequestMemory": { "type": "object", "properties": { "kind": { "type": "string", "const": "memory", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "action": { "$ref": "#/definitions/PermissionRequestMemoryAction", "description": "Whether this is a store or vote memory operation" }, "subject": { "type": "string", "description": "Topic or subject of the memory (store only)" }, "fact": { "type": "string", "description": "The fact being stored or voted on" }, "citations": { "type": "string", "description": "Source references for the stored fact (store only)" }, "direction": { "$ref": "#/definitions/PermissionRequestMemoryDirection", "description": "Vote direction (vote only)" }, "reason": { "type": "string", "description": "Reason for the vote (vote only)" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" } }, "required": [ "kind", "fact" ], "additionalProperties": false, "description": "Memory operation permission prompt", "title": "PermissionPromptRequestMemory" }, "PermissionPromptRequestPath": { "type": "object", "properties": { "kind": { "type": "string", "const": "path", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "accessKind": { "$ref": "#/definitions/PermissionPromptRequestPathAccessKind", "description": "Underlying permission kind that needs path approval" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "File paths that require explicit approval" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" } }, "required": [ "kind", "accessKind", "paths" ], "additionalProperties": false, "description": "Path access permission prompt", "title": "PermissionPromptRequestPath" }, "PermissionPromptRequestPathAccessKind": { "type": "string", "enum": [ "read", "shell", "write" ], "description": "Underlying permission kind that needs path approval", "title": "PermissionPromptRequestPathAccessKind", "x-enumDescriptions": { "read": "Read access to a filesystem path.", "shell": "Shell command access involving a filesystem path.", "write": "Write access to a filesystem path." } }, "PermissionPromptRequestRead": { "type": "object", "properties": { "kind": { "type": "string", "const": "read", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "intention": { "type": "string", "description": "Human-readable description of why the file is being read" }, "path": { "type": "string", "description": "Path of the file or directory being read" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" } }, "required": [ "kind", "intention", "path" ], "additionalProperties": false, "description": "File read permission prompt", "title": "PermissionPromptRequestRead" }, "PermissionPromptRequestUrl": { "type": "object", "properties": { "kind": { "type": "string", "const": "url", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "intention": { "type": "string", "description": "Human-readable description of why the URL is being accessed" }, "url": { "type": "string", "description": "URL to be fetched" }, "redirectedFrom": { "type": "string", "description": "Immediately preceding URL when this prompt is for a redirect target" }, "requestSandboxBypass": { "type": "boolean", "description": "True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI." }, "requestSandboxBypassReason": { "type": "string", "description": "Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true." }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" } }, "required": [ "kind", "intention", "url" ], "additionalProperties": false, "description": "URL access permission prompt", "title": "PermissionPromptRequestUrl" }, "PermissionPromptRequestWrite": { "type": "object", "properties": { "kind": { "type": "string", "const": "write", "description": "Prompt kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "intention": { "type": "string", "description": "Human-readable description of the intended file change" }, "fileName": { "type": "string", "description": "Path of the file being written to" }, "diff": { "type": "string", "description": "Unified diff showing the proposed changes" }, "newFileContents": { "type": "string", "description": "Complete new file contents for newly created files" }, "canOfferSessionApproval": { "type": "boolean", "description": "Whether the UI can offer session-wide approval for file write operations" }, "autoApproval": { "$ref": "#/definitions/PermissionAutoApproval", "description": "Auto-approval judge information for this request; present only when auto mode is enabled.", "stability": "experimental" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" } }, "required": [ "kind", "intention", "fileName", "diff", "canOfferSessionApproval" ], "additionalProperties": false, "description": "File write permission prompt", "title": "PermissionPromptRequestWrite" }, "PermissionRequest": { "anyOf": [ { "$ref": "#/definitions/PermissionRequestShell", "description": "Shell command permission request" }, { "$ref": "#/definitions/PermissionRequestWrite", "description": "File write permission request" }, { "$ref": "#/definitions/PermissionRequestRead", "description": "File or directory read permission request" }, { "$ref": "#/definitions/PermissionRequestMcp", "description": "MCP tool invocation permission request" }, { "$ref": "#/definitions/PermissionRequestUrl", "description": "URL access permission request" }, { "$ref": "#/definitions/PermissionRequestMemory", "description": "Memory operation permission request" }, { "$ref": "#/definitions/PermissionRequestCustomTool", "description": "Custom tool invocation permission request" }, { "$ref": "#/definitions/PermissionRequestHook", "description": "Hook confirmation permission request" }, { "$ref": "#/definitions/PermissionRequestExtensionManagement", "description": "Extension management permission request" }, { "$ref": "#/definitions/PermissionRequestFactory", "description": "Factory run or authoring permission request" }, { "$ref": "#/definitions/PermissionRequestExtensionPermissionAccess", "description": "Extension permission access request" } ], "description": "Details of the permission being requested", "title": "PermissionRequest" }, "PermissionRequestCustomTool": { "type": "object", "properties": { "kind": { "type": "string", "const": "custom-tool", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "toolName": { "type": "string", "description": "Name of the custom tool" }, "toolDescription": { "type": "string", "description": "Description of what the custom tool does" }, "args": { "description": "Arguments to pass to the custom tool", "x-opaque-json": true } }, "required": [ "kind", "toolName", "toolDescription" ], "additionalProperties": false, "description": "Custom tool invocation permission request", "title": "PermissionRequestCustomTool" }, "PermissionRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this permission request; used to respond via session.respondToPermission()" }, "permissionRequest": { "$ref": "#/definitions/PermissionRequest", "description": "Details of the permission being requested" }, "promptRequest": { "$ref": "#/definitions/PermissionPromptRequest", "description": "Derived user-facing permission prompt details for UI consumers" }, "riskAssessment": { "description": "Neutral risk metadata supplied by the tool host. Consumers may display this value but must not use it to bypass the permission decision.", "x-opaque-json": true }, "resolvedByHook": { "type": "boolean", "description": "When true, this permission was already resolved by a permissionRequest hook and requires no client action" } }, "required": [ "requestId", "permissionRequest" ], "additionalProperties": false, "description": "Permission request notification requiring client approval with request details", "title": "PermissionRequestedData" }, "PermissionRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "permission.requested", "description": "Type discriminator. Always \"permission.requested\"." }, "data": { "$ref": "#/definitions/PermissionRequestedData", "description": "Permission request notification requiring client approval with request details" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"permission.requested\". Permission request notification requiring client approval with request details", "title": "PermissionRequestedEvent" }, "PermissionRequestExtensionManagement": { "type": "object", "properties": { "kind": { "type": "string", "const": "extension-management", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "operation": { "type": "string", "description": "The extension management operation (scaffold, reload)" }, "extensionName": { "type": "string", "description": "Name of the extension being managed" } }, "required": [ "kind", "operation" ], "additionalProperties": false, "description": "Extension management permission request", "title": "PermissionRequestExtensionManagement" }, "PermissionRequestExtensionPermissionAccess": { "type": "object", "properties": { "kind": { "type": "string", "const": "extension-permission-access", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "extensionName": { "type": "string", "description": "Name of the extension requesting permission access" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Capabilities the extension is requesting" } }, "required": [ "kind", "extensionName", "capabilities" ], "additionalProperties": false, "description": "Extension permission access request", "title": "PermissionRequestExtensionPermissionAccess" }, "PermissionRequestFactory": { "type": "object", "properties": { "kind": { "type": "string", "const": "factory", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "operation": { "$ref": "#/definitions/FactoryPermissionOperation", "description": "Factory operation, either run or author" }, "name": { "type": "string", "description": "Factory name" }, "description": { "type": "string", "description": "Factory description" }, "phases": { "type": "array", "items": { "$ref": "#/definitions/FactoryPermissionPhase", "description": "A declared phase shown in a factory permission prompt." }, "description": "Declared factory phases" }, "maxConcurrentSubagents": { "type": "integer", "minimum": 0, "description": "Effective concurrent-subagent limit; omitted means unlimited" }, "maxTotalSubagents": { "type": "integer", "minimum": 0, "description": "Effective total-subagent limit; omitted means unlimited" }, "timeoutSeconds": { "type": "number", "description": "Effective active-time limit in seconds; omitted means unlimited" }, "maxAiCredits": { "type": "number", "description": "Effective AI-credit limit; omitted means unlimited" }, "declaredMaxConcurrentSubagents": { "type": "integer", "minimum": 0 }, "declaredMaxTotalSubagents": { "type": "integer", "minimum": 0 }, "declaredTimeoutSeconds": { "type": "number" }, "declaredMaxAiCredits": { "type": "number" }, "approvalKey": { "type": "string", "description": "Canonical key used for scoped factory approvals" }, "canPersistApproval": { "type": "boolean", "description": "Whether this factory is eligible for persistent approval" } }, "required": [ "kind", "operation", "name", "description", "phases", "approvalKey", "canPersistApproval" ], "additionalProperties": false, "description": "Factory run or authoring permission request", "title": "PermissionRequestFactory" }, "PermissionRequestHook": { "type": "object", "properties": { "kind": { "type": "string", "const": "hook", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "toolName": { "type": "string", "description": "Name of the tool the hook is gating" }, "toolArgs": { "description": "Arguments of the tool call being gated", "x-opaque-json": true }, "hookMessage": { "type": "string", "description": "Optional message from the hook explaining why confirmation is needed" } }, "required": [ "kind", "toolName" ], "additionalProperties": false, "description": "Hook confirmation permission request", "title": "PermissionRequestHook" }, "PermissionRequestMcp": { "type": "object", "properties": { "kind": { "type": "string", "const": "mcp", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "serverName": { "type": "string", "description": "Name of the MCP server providing the tool" }, "toolName": { "type": "string", "description": "Internal name of the MCP tool" }, "toolTitle": { "type": "string", "description": "Human-readable title of the MCP tool" }, "args": { "description": "Arguments to pass to the MCP tool", "x-opaque-json": true }, "readOnly": { "type": "boolean", "description": "Whether this MCP tool is read-only (no side effects)" } }, "required": [ "kind", "serverName", "toolName", "toolTitle", "readOnly" ], "additionalProperties": false, "description": "MCP tool invocation permission request", "title": "PermissionRequestMcp" }, "PermissionRequestMemory": { "type": "object", "properties": { "kind": { "type": "string", "const": "memory", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "action": { "$ref": "#/definitions/PermissionRequestMemoryAction", "description": "Whether this is a store or vote memory operation" }, "subject": { "type": "string", "description": "Topic or subject of the memory (store only)" }, "fact": { "type": "string", "description": "The fact being stored or voted on" }, "citations": { "type": "string", "description": "Source references for the stored fact (store only)" }, "direction": { "$ref": "#/definitions/PermissionRequestMemoryDirection", "description": "Vote direction (vote only)" }, "reason": { "type": "string", "description": "Reason for the vote (vote only)" } }, "required": [ "kind", "fact" ], "additionalProperties": false, "description": "Memory operation permission request", "title": "PermissionRequestMemory" }, "PermissionRequestMemoryAction": { "type": "string", "enum": [ "store", "vote" ], "default": "store", "description": "Whether this is a store or vote memory operation", "title": "PermissionRequestMemoryAction", "x-enumDescriptions": { "store": "Store a new memory.", "vote": "Vote on an existing memory." } }, "PermissionRequestMemoryDirection": { "type": "string", "enum": [ "upvote", "downvote" ], "description": "Vote direction (vote only)", "title": "PermissionRequestMemoryDirection", "x-enumDescriptions": { "upvote": "Vote that the memory is useful or accurate.", "downvote": "Vote that the memory is incorrect or outdated." } }, "PermissionRequestRead": { "type": "object", "properties": { "kind": { "type": "string", "const": "read", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" }, "intention": { "type": "string", "description": "Human-readable description of why the file is being read" }, "path": { "type": "string", "description": "Path of the file or directory being read" }, "requestSandboxBypass": { "type": "boolean", "description": "True when the model has requested to run this search outside the sandbox (it set requestSandboxBypass: true and the host opted in via sandbox.allowBypass). This is a request, not a grant: the search runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI." }, "requestSandboxBypassReason": { "type": "string", "description": "Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true." } }, "required": [ "kind", "intention", "path" ], "additionalProperties": false, "description": "File or directory read permission request", "title": "PermissionRequestRead" }, "PermissionRequestShell": { "type": "object", "properties": { "kind": { "type": "string", "const": "shell", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" }, "fullCommandText": { "type": "string", "description": "The complete shell command text to be executed" }, "intention": { "type": "string", "description": "Human-readable description of what the command intends to do" }, "commands": { "type": "array", "items": { "$ref": "#/definitions/PermissionRequestShellCommand", "description": "A parsed command identifier in a shell permission request, including whether it is read-only." }, "description": "Parsed command identifiers found in the command text" }, "commandSegments": { "type": "array", "items": { "$ref": "#/definitions/PermissionRequestShellCommandSegment", "description": "A parsed shell command segment used for argument-aware managed policy matching." }, "description": "Parsed command segments, including arguments, used for managed policy matching" }, "possiblePaths": { "type": "array", "items": { "type": "string" }, "description": "File paths that may be read or written by the command" }, "possibleUrls": { "type": "array", "items": { "$ref": "#/definitions/PermissionRequestShellPossibleUrl", "description": "A URL that may be accessed by a command in a shell permission request." }, "description": "URLs that may be accessed by the command" }, "hasWriteFileRedirection": { "type": "boolean", "description": "Whether the command includes a file write redirection (e.g., > or >>)" }, "canOfferSessionApproval": { "type": "boolean", "description": "Whether the UI can offer session-wide approval for this command pattern" }, "warning": { "type": "string", "description": "Optional warning message about risks of running this command" }, "requestSandboxBypass": { "type": "boolean", "description": "True when the model has requested to run this command outside the sandbox (it set requestSandboxBypass: true and the host opted in via sandbox.allowBypass). This is a request, not a grant: the command runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI." }, "requestSandboxBypassReason": { "type": "string", "description": "Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true." } }, "required": [ "kind", "fullCommandText", "intention", "commands", "possiblePaths", "possibleUrls", "hasWriteFileRedirection", "canOfferSessionApproval" ], "additionalProperties": false, "description": "Shell command permission request", "title": "PermissionRequestShell" }, "PermissionRequestShellCommand": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Command identifier (e.g., executable name)" }, "readOnly": { "type": "boolean", "description": "Whether this command is read-only (no side effects)" } }, "required": [ "identifier", "readOnly" ], "additionalProperties": false, "description": "A parsed command identifier in a shell permission request, including whether it is read-only.", "title": "PermissionRequestShellCommand" }, "PermissionRequestShellCommandSegment": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Command identifier (e.g., executable name)" }, "fullCommandText": { "type": "string", "description": "Full text of this command segment, including arguments" } }, "required": [ "identifier", "fullCommandText" ], "additionalProperties": false, "description": "A parsed shell command segment used for argument-aware managed policy matching.", "title": "PermissionRequestShellCommandSegment" }, "PermissionRequestShellPossibleUrl": { "type": "object", "properties": { "url": { "type": "string", "description": "URL that may be accessed by the command" } }, "required": [ "url" ], "additionalProperties": false, "description": "A URL that may be accessed by a command in a shell permission request.", "title": "PermissionRequestShellPossibleUrl" }, "PermissionRequestUrl": { "type": "object", "properties": { "kind": { "type": "string", "const": "url", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" }, "intention": { "type": "string", "description": "Human-readable description of why the URL is being accessed" }, "url": { "type": "string", "description": "URL to be fetched" }, "redirectedFrom": { "type": "string", "description": "Immediately preceding URL when this request is for a redirect target" }, "requestSandboxBypass": { "type": "boolean", "description": "True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI." }, "requestSandboxBypassReason": { "type": "string", "description": "Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true." } }, "required": [ "kind", "intention", "url" ], "additionalProperties": false, "description": "URL access permission request", "title": "PermissionRequestUrl" }, "PermissionRequestWrite": { "type": "object", "properties": { "kind": { "type": "string", "const": "write", "description": "Permission kind discriminator" }, "toolCallId": { "type": "string", "description": "Tool call ID that triggered this permission request" }, "managedApprovalRequired": { "type": "boolean", "description": "Whether managed policy requires a human response and forbids host auto-approval" }, "intention": { "type": "string", "description": "Human-readable description of the intended file change" }, "fileName": { "type": "string", "description": "Path of the file being written to" }, "diff": { "type": "string", "description": "Unified diff showing the proposed changes" }, "newFileContents": { "type": "string", "description": "Complete new file contents for newly created files" }, "canOfferSessionApproval": { "type": "boolean", "description": "Whether the UI can offer session-wide approval for file write operations" }, "requestSandboxBypass": { "type": "boolean", "description": "True when a built-in file tool (apply_patch / str_replace_editor) asked to write a path the sandbox filesystem policy would block, and the host opted in via sandbox.allowBypass. This is a request, not a grant: the write happens unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI." }, "requestSandboxBypassReason": { "type": "string", "description": "Justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true." } }, "required": [ "kind", "intention", "fileName", "diff", "canOfferSessionApproval" ], "additionalProperties": false, "description": "File write permission request", "title": "PermissionRequestWrite" }, "PermissionResult": { "anyOf": [ { "$ref": "#/definitions/PermissionApproved", "description": "Permission response variant indicating the request was approved without persisting an approval rule." }, { "$ref": "#/definitions/PermissionApprovedForSession", "description": "Permission response variant that approves a request and remembers the provided approval for the rest of the session." }, { "$ref": "#/definitions/PermissionApprovedForLocation", "description": "Permission response variant that approves a request and persists the provided approval to a project location key." }, { "$ref": "#/definitions/PermissionCancelled", "description": "Permission response variant indicating the request was cancelled before use, with an optional reason." }, { "$ref": "#/definitions/PermissionDeniedByRules", "description": "Permission response variant denied because matching approval rules explicitly blocked the request." }, { "$ref": "#/definitions/PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser", "description": "Permission response variant denied because no approval rule matched and user confirmation was unavailable." }, { "$ref": "#/definitions/PermissionDeniedInteractivelyByUser", "description": "Permission response variant denied in an interactive user prompt, with optional feedback and force-reject flag." }, { "$ref": "#/definitions/PermissionDeniedByContentExclusionPolicy", "description": "Permission response variant denying a path under content exclusion policy, with the path and message." }, { "$ref": "#/definitions/PermissionDeniedByPermissionRequestHook", "description": "Permission response variant denied by a permission-request hook, with optional message and interrupt flag." } ], "description": "The result of the permission request", "title": "PermissionResult" }, "PermissionRule": { "type": "object", "properties": { "kind": { "type": "string", "description": "The rule kind, such as Shell or GitHubMCP" }, "argument": { "type": [ "string", "null" ], "description": "Argument value matched against the request, or null when the rule kind has no argument (e.g. 'read', 'write', 'memory')." } }, "required": [ "kind", "argument" ], "additionalProperties": false, "description": "A permission approval or denial rule matched against a tool request, identified by a rule kind with an optional argument value.", "title": "PermissionRule" }, "PermissionsChangedData": { "type": "object", "properties": { "previousAllowAllPermissions": { "type": "boolean", "description": "Aggregate allow-all flag before the change" }, "allowAllPermissions": { "type": "boolean", "description": "Aggregate allow-all flag after the change" }, "previousAllowAllPermissionMode": { "$ref": "#/definitions/PermissionAllowAllMode", "description": "Allow-all mode before the change", "stability": "experimental" }, "allowAllPermissionMode": { "$ref": "#/definitions/PermissionAllowAllMode", "description": "Allow-all mode after the change", "stability": "experimental" } }, "required": [ "previousAllowAllPermissions", "allowAllPermissions" ], "additionalProperties": false, "description": "Permissions change details carrying the aggregate allow-all transition.", "title": "PermissionsChangedData" }, "PermissionsChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.permissions_changed", "description": "Type discriminator. Always \"session.permissions_changed\"." }, "data": { "$ref": "#/definitions/PermissionsChangedData", "description": "Permissions change details carrying the aggregate allow-all transition." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.permissions_changed\". Permissions change details carrying the aggregate allow-all transition.", "title": "PermissionsChangedEvent" }, "PersistedBinaryImage": { "type": "object", "properties": { "type": { "$ref": "#/definitions/PersistedBinaryImageType", "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data." }, "data": { "type": "string", "description": "Base64-encoded binary data", "contentEncoding": "base64" }, "mimeType": { "type": "string", "description": "MIME type of the binary data" }, "description": { "type": "string", "description": "Human-readable description of the binary data" }, "metadata": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Optional metadata from the producing tool." } }, "required": [ "type", "data", "mimeType" ], "additionalProperties": false, "description": "Binary result returned by a tool for the model", "title": "PersistedBinaryImage" }, "PersistedBinaryImageType": { "type": "string", "enum": [ "image", "resource" ], "description": "Binary result type discriminator. Use \"image\" for images and \"resource\" for other binary data.", "title": "PersistedBinaryImageType", "x-enumDescriptions": { "image": "Binary image data.", "resource": "Other binary resource data." } }, "PersistedBinaryResult": { "anyOf": [ { "$ref": "#/definitions/PersistedBinaryImage", "description": "Binary result returned by a tool for the model" }, { "$ref": "#/definitions/OmittedBinaryResult", "description": "A binary result whose data was omitted from persistence due to the inline size limit" }, { "$ref": "#/definitions/BinaryAssetReference", "description": "A reference to binary data persisted once on a session.binary_asset event and shared by id" } ], "description": "A model-facing binary result as persisted: full inline data, a size-omitted marker, or a deduplicated asset reference", "title": "PersistedBinaryResult", "stability": "experimental" }, "PlanChangedData": { "type": "object", "properties": { "operation": { "$ref": "#/definitions/PlanChangedOperation", "description": "The type of operation performed on the plan file" } }, "required": [ "operation" ], "additionalProperties": false, "description": "Plan file operation details indicating what changed", "title": "PlanChangedData" }, "PlanChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.plan_changed", "description": "Type discriminator. Always \"session.plan_changed\"." }, "data": { "$ref": "#/definitions/PlanChangedData", "description": "Plan file operation details indicating what changed" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.plan_changed\". Plan file operation details indicating what changed", "title": "PlanChangedEvent" }, "PlanChangedOperation": { "type": "string", "enum": [ "create", "update", "delete" ], "description": "The type of operation performed on the plan file", "title": "PlanChangedOperation", "x-enumDescriptions": { "create": "The plan file was created.", "update": "The plan file was updated.", "delete": "The plan file was deleted." } }, "ReasoningSummary": { "type": "string", "enum": [ "none", "concise", "detailed" ], "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")", "title": "ReasoningSummary", "x-enumDescriptions": { "none": "Do not request reasoning summaries from the model.", "concise": "Request a concise summary of the model's reasoning.", "detailed": "Request a detailed summary of the model's reasoning." } }, "RemoteSteerableChangedData": { "type": "object", "properties": { "remoteSteerable": { "type": "boolean", "description": "Whether this session now supports remote steering via GitHub" } }, "required": [ "remoteSteerable" ], "additionalProperties": false, "description": "Notifies that the session's remote steering capability has changed", "title": "RemoteSteerableChangedData" }, "RemoteSteerableChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.remote_steerable_changed", "description": "Type discriminator. Always \"session.remote_steerable_changed\"." }, "data": { "$ref": "#/definitions/RemoteSteerableChangedData", "description": "Notifies that the session's remote steering capability has changed" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.remote_steerable_changed\". Notifies that the session's remote steering capability has changed", "title": "RemoteSteerableChangedEvent" }, "ResumeData": { "type": "object", "properties": { "resumeTime": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the session was resumed" }, "eventCount": { "type": "integer", "minimum": 0, "description": "Total number of persisted events in the session at the time of resume" }, "eventsFileSizeBytes": { "type": "integer", "minimum": 0, "description": "On-disk byte size of the session's persisted events.jsonl file at resume time; omitted when the file does not exist or cannot be stat'd" }, "selectedModel": { "type": "string", "description": "Model currently selected at resume time" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\")" }, "reasoningSummary": { "$ref": "#/definitions/ReasoningSummary", "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")" }, "verbosity": { "$ref": "#/definitions/Verbosity", "description": "Output verbosity level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\")" }, "contextTier": { "anyOf": [ { "$ref": "#/definitions/ContextTier" }, { "type": "null" } ], "description": "Context tier currently selected at resume time; null when no tier is active" }, "sessionLimits": { "anyOf": [ { "$ref": "#/definitions/SessionLimitsConfig", "description": "Optional session limits." }, { "type": "null" } ], "description": "Session limits currently configured at resume time; null when no limits are active" }, "context": { "$ref": "#/definitions/WorkingDirectoryContext", "description": "Updated working directory and git context at resume time" }, "alreadyInUse": { "type": "boolean", "description": "Whether the session was already in use by another client at resume time" }, "sessionWasActive": { "type": "boolean", "description": "True when this resume passively joined a session that already had live work running in the runtime - an agent turn, a native queue run, a queued resume continuation, or an in-flight send (for example, an extension joining a session another client was actively driving). False (or omitted) when the session had no live work or when the resume explicitly abandoned pending work, including cold resumes and suspended sessions that remain resident in memory." }, "remoteSteerable": { "type": "boolean", "description": "Whether this session supports remote steering via GitHub" }, "continuePendingWork": { "type": "boolean", "description": "When true, tool calls and permission requests left in flight by the previous session lifetime remain pending after resume and the agentic loop awaits their results. User sends are queued behind the pending work until all such requests reach a terminal state. When false or omitted, pending work is normally marked as interrupted unless the resume passively joined live work owned by another client; sessionWasActive distinguishes that case." } }, "required": [ "resumeTime", "eventCount" ], "additionalProperties": false, "description": "Session resume metadata including current context and event count", "title": "ResumeData" }, "ResumeEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.resume", "description": "Type discriminator. Always \"session.resume\"." }, "data": { "$ref": "#/definitions/ResumeData", "description": "Session resume metadata including current context and event count" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.resume\". Session resume metadata including current context and event count", "title": "ResumeEvent" }, "SamplingCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved sampling request; clients should dismiss any UI for this request" } }, "required": [ "requestId" ], "additionalProperties": false, "description": "Sampling request completion notification signaling UI dismissal", "title": "SamplingCompletedData" }, "SamplingCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "sampling.completed", "description": "Type discriminator. Always \"sampling.completed\"." }, "data": { "$ref": "#/definitions/SamplingCompletedData", "description": "Sampling request completion notification signaling UI dismissal" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"sampling.completed\". Sampling request completion notification signaling UI dismissal", "title": "SamplingCompletedEvent" }, "SamplingRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this sampling request; used to respond via session.respondToSampling()" }, "serverName": { "type": "string", "description": "Name of the MCP server that initiated the sampling request" }, "mcpRequestId": { "description": "The JSON-RPC request ID from the MCP protocol", "x-opaque-json": true } }, "required": [ "requestId", "serverName", "mcpRequestId" ], "description": "Sampling request from an MCP server; contains the server name and a requestId for correlation", "title": "SamplingRequestedData" }, "SamplingRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "sampling.requested", "description": "Type discriminator. Always \"sampling.requested\"." }, "data": { "$ref": "#/definitions/SamplingRequestedData", "description": "Sampling request from an MCP server; contains the server name and a requestId for correlation" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"sampling.requested\". Sampling request from an MCP server; contains the server name and a requestId for correlation", "title": "SamplingRequestedEvent" }, "ScheduleCancelledData": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "Id of the scheduled prompt that was cancelled" } }, "required": [ "id" ], "additionalProperties": false, "description": "Scheduled prompt cancelled from the schedule manager dialog", "title": "ScheduleCancelledData" }, "ScheduleCancelledEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.schedule_cancelled", "description": "Type discriminator. Always \"session.schedule_cancelled\"." }, "data": { "$ref": "#/definitions/ScheduleCancelledData", "description": "Scheduled prompt cancelled from the schedule manager dialog" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.schedule_cancelled\". Scheduled prompt cancelled from the schedule manager dialog", "title": "ScheduleCancelledEvent" }, "ScheduleCreatedData": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "Sequential id assigned to the scheduled prompt within the session" }, "intervalMs": { "type": "integer", "exclusiveMinimum": 0, "format": "duration", "description": "Interval between ticks in milliseconds (relative-interval schedules)" }, "cron": { "type": "string", "description": "5-field cron expression for a recurring calendar schedule, evaluated in `tz`" }, "tz": { "type": "string", "description": "IANA timezone the `cron` expression is evaluated in" }, "at": { "type": "integer", "exclusiveMinimum": 0, "description": "Absolute fire time (epoch milliseconds) for a one-shot calendar schedule" }, "prompt": { "type": "string", "description": "Prompt text that gets enqueued on every tick" }, "recurring": { "type": "boolean", "description": "Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)" }, "selfPaced": { "type": "boolean", "description": "True for a self-paced (`dynamic`) schedule: no fixed cadence; the model arms each next run via the `manage_schedule` `wakeup` action. `nextRunAt` is model-controlled rather than auto-computed." }, "displayPrompt": { "type": "string", "description": "Optional user-facing label shown in the timeline instead of the actual prompt (e.g. `/skill-name args` when the prompt is a skill invocation expansion)" }, "origin": { "$ref": "#/definitions/ScheduleOrigin", "description": "Who created the schedule (`user` or `model`). Persisted so a resumed session keeps gating non-user schedules from firing skills that opted out of model invocation. Absent on entries created before this field existed; a missing origin fails closed (treated the same as a non-user origin), so such a schedule may not resolve a `disable-model-invocation` skill." } }, "required": [ "id", "prompt" ], "additionalProperties": false, "description": "Scheduled prompt registered via /every or /after", "title": "ScheduleCreatedData" }, "ScheduleCreatedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.schedule_created", "description": "Type discriminator. Always \"session.schedule_created\"." }, "data": { "$ref": "#/definitions/ScheduleCreatedData", "description": "Scheduled prompt registered via /every or /after" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.schedule_created\". Scheduled prompt registered via /every or /after", "title": "ScheduleCreatedEvent" }, "ScheduleOrigin": { "type": "string", "enum": [ "user", "model" ], "description": "Who created the schedule: `user` (an explicit user action such as `/every` or `/after`) or `model` (the agent via the `manage_schedule` tool). Gates whether a scheduled skill that opted out of model invocation may fire: only user-created schedules may.", "title": "ScheduleOrigin", "x-enumDescriptions": { "user": "The schedule was created by an explicit user action, such as `/every` or `/after`.", "model": "The schedule was created by the agent via the `manage_schedule` tool." } }, "ScheduleRearmedData": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "Id of the self-paced schedule that was re-armed" }, "nextRunAt": { "type": "integer", "exclusiveMinimum": 0, "description": "Absolute time (epoch milliseconds) the model armed the next run to fire" } }, "required": [ "id", "nextRunAt" ], "additionalProperties": false, "description": "Self-paced schedule re-armed for its next run", "title": "ScheduleRearmedData" }, "ScheduleRearmedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.schedule_rearmed", "description": "Type discriminator. Always \"session.schedule_rearmed\"." }, "data": { "$ref": "#/definitions/ScheduleRearmedData", "description": "Self-paced schedule re-armed for its next run" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.schedule_rearmed\". Self-paced schedule re-armed for its next run", "title": "ScheduleRearmedEvent" }, "SessionEvent": { "anyOf": [ { "$ref": "#/definitions/StartEvent", "description": "Session event \"session.start\". Session initialization metadata including context and configuration" }, { "$ref": "#/definitions/ResumeEvent", "description": "Session event \"session.resume\". Session resume metadata including current context and event count" }, { "$ref": "#/definitions/RemoteSteerableChangedEvent", "description": "Session event \"session.remote_steerable_changed\". Notifies that the session's remote steering capability has changed" }, { "$ref": "#/definitions/ErrorEvent", "description": "Session event \"session.error\". Error details for timeline display including message and optional diagnostic information" }, { "$ref": "#/definitions/IdleEvent", "description": "Session event \"session.idle\". Payload indicating the session is idle with no background agents or attached shell commands in flight" }, { "$ref": "#/definitions/TitleChangedEvent", "description": "Session event \"session.title_changed\". Session title change payload containing the new display title" }, { "$ref": "#/definitions/ScheduleCreatedEvent", "description": "Session event \"session.schedule_created\". Scheduled prompt registered via /every or /after" }, { "$ref": "#/definitions/ScheduleCancelledEvent", "description": "Session event \"session.schedule_cancelled\". Scheduled prompt cancelled from the schedule manager dialog" }, { "$ref": "#/definitions/ScheduleRearmedEvent", "description": "Session event \"session.schedule_rearmed\". Self-paced schedule re-armed for its next run" }, { "$ref": "#/definitions/AutopilotObjectiveChangedEvent", "description": "Session event \"session.autopilot_objective_changed\". Autopilot objective state file operation details indicating what changed" }, { "$ref": "#/definitions/InfoEvent", "description": "Session event \"session.info\". Informational message for timeline display with categorization" }, { "$ref": "#/definitions/WarningEvent", "description": "Session event \"session.warning\". Warning message for timeline display with categorization" }, { "$ref": "#/definitions/ModelChangeEvent", "description": "Session event \"session.model_change\". Model change details including previous and new model identifiers" }, { "$ref": "#/definitions/ModeChangedEvent", "description": "Session event \"session.mode_changed\". Agent mode change details including previous and new modes" }, { "$ref": "#/definitions/SessionLimitsChangedEvent", "description": "Session event \"session.session_limits_changed\". Session limits update details. Null clears the limits." }, { "$ref": "#/definitions/PermissionsChangedEvent", "description": "Session event \"session.permissions_changed\". Permissions change details carrying the aggregate allow-all transition." }, { "$ref": "#/definitions/PlanChangedEvent", "description": "Session event \"session.plan_changed\". Plan file operation details indicating what changed" }, { "$ref": "#/definitions/TodosChangedEvent", "description": "Session event \"session.todos_changed\". Signal-only event: the agent's todos or todo_deps table was written to. No payload — clients should call session.plan.readSqlTodosWithDependencies() to fetch the current state. Events arrive in order; clients can debounce on arrival if needed." }, { "$ref": "#/definitions/MemoryChangedEvent", "description": "Session event \"session.memory_changed\". Signal-only event: the agent successfully stored a memory (store_memory) or voted on one (vote_memory). No payload — consumers should re-fetch memories to pick up the change. Used to refresh memory context (e.g. re-running the context sidekick) so newly written memories surface in subsequent turns.", "visibility": "internal" }, { "$ref": "#/definitions/WorkspaceFileChangedEvent", "description": "Session event \"session.workspace_file_changed\". Workspace file change details including path and operation type" }, { "$ref": "#/definitions/HandoffEvent", "description": "Session event \"session.handoff\". Session handoff metadata including source, context, and repository information" }, { "$ref": "#/definitions/TruncationEvent", "description": "Session event \"session.truncation\". Conversation truncation statistics including token counts and removed content metrics" }, { "$ref": "#/definitions/SnapshotRewindEvent", "description": "Session event \"session.snapshot_rewind\". Session rewind details including target event and count of removed events" }, { "$ref": "#/definitions/ShutdownEvent", "description": "Session event \"session.shutdown\". Session termination metrics including usage statistics, code changes, and shutdown reason" }, { "$ref": "#/definitions/UsageCheckpointEvent", "description": "Session event \"session.usage_checkpoint\". Durable session usage checkpoint for reconstructing aggregate accounting on resume" }, { "$ref": "#/definitions/ContextChangedEvent", "description": "Session event \"session.context_changed\". Updated working directory and git context after the change" }, { "$ref": "#/definitions/UsageInfoEvent", "description": "Session event \"session.usage_info\". Current context window usage statistics including token and message counts" }, { "$ref": "#/definitions/ContextClearedEvent", "description": "Session event \"session.context_cleared\". Context-cleared details emitted when the host clears the conversation (the session.history.clearContext RPC / Session.clearContextMessages)" }, { "$ref": "#/definitions/CompactionStartEvent", "description": "Session event \"session.compaction_start\". Context window breakdown at the start of LLM-powered conversation compaction" }, { "$ref": "#/definitions/CompactionCompleteEvent", "description": "Session event \"session.compaction_complete\". Conversation compaction results including success status, metrics, and optional error details" }, { "$ref": "#/definitions/TaskCompleteEvent", "description": "Session event \"session.task_complete\". Task completion notification with summary from the agent" }, { "$ref": "#/definitions/UserMessageEvent", "description": "Session event \"user.message\". Payload of `user.message` with displayed and model-transformed content, attachments, source/delivery metadata, mode, and telemetry IDs." }, { "$ref": "#/definitions/PendingMessagesModifiedEvent", "description": "Session event \"pending_messages.modified\". Empty payload; the event signals that the pending message queue has changed" }, { "$ref": "#/definitions/AssistantTurnStartEvent", "description": "Session event \"assistant.turn_start\". Turn initialization metadata including identifier and interaction tracking" }, { "$ref": "#/definitions/AssistantTurnRetryEvent", "description": "Session event \"assistant.turn_retry\". Metadata for an additional model inference attempt within an existing assistant turn", "visibility": "internal" }, { "$ref": "#/definitions/AssistantIntentEvent", "description": "Session event \"assistant.intent\". Agent intent description for current activity or plan" }, { "$ref": "#/definitions/AssistantServerToolProgressEvent", "description": "Session event \"assistant.server_tool_progress\". Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message" }, { "$ref": "#/definitions/AssistantReasoningEvent", "description": "Session event \"assistant.reasoning\". Assistant reasoning content for timeline display with complete thinking text" }, { "$ref": "#/definitions/AssistantReasoningDeltaEvent", "description": "Session event \"assistant.reasoning_delta\". Streaming reasoning delta for incremental extended thinking updates" }, { "$ref": "#/definitions/AssistantToolCallDeltaEvent", "description": "Session event \"assistant.tool_call_delta\". Streaming tool-call input delta for incremental tool-call updates" }, { "$ref": "#/definitions/AssistantStreamingDeltaEvent", "description": "Session event \"assistant.streaming_delta\". Streaming response progress with cumulative byte count" }, { "$ref": "#/definitions/AssistantMessageEvent", "description": "Session event \"assistant.message\". Assistant response containing text content, optional tool requests, and interaction metadata" }, { "$ref": "#/definitions/AssistantMessageStartEvent", "description": "Session event \"assistant.message_start\". Streaming assistant message start metadata" }, { "$ref": "#/definitions/AssistantMessageDeltaEvent", "description": "Session event \"assistant.message_delta\". Streaming assistant message delta for incremental response updates" }, { "$ref": "#/definitions/AssistantTurnEndEvent", "description": "Session event \"assistant.turn_end\". Turn completion metadata including the turn identifier" }, { "$ref": "#/definitions/AssistantIdleEvent", "description": "Session event \"assistant.idle\". Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred" }, { "$ref": "#/definitions/AssistantUsageEvent", "description": "Session event \"assistant.usage\". LLM API call usage metrics including tokens, costs, quotas, and billing information" }, { "$ref": "#/definitions/ModelCallFailureEvent", "description": "Session event \"model.call_failure\". Failed LLM API call metadata for telemetry" }, { "$ref": "#/definitions/ModelCallStartEvent", "description": "Session event \"model.call_start\". Model API dispatch metadata for internal telemetry", "visibility": "internal" }, { "$ref": "#/definitions/AbortEvent", "description": "Session event \"abort\". Turn abort information including the reason for termination" }, { "$ref": "#/definitions/ToolUserRequestedEvent", "description": "Session event \"tool.user_requested\". User-initiated tool invocation request with tool name and arguments" }, { "$ref": "#/definitions/ToolExecutionStartEvent", "description": "Session event \"tool.execution_start\". Tool execution startup details including MCP server information when applicable" }, { "$ref": "#/definitions/ToolExecutionPartialResultEvent", "description": "Session event \"tool.execution_partial_result\". Streaming tool execution output for incremental result display" }, { "$ref": "#/definitions/ToolExecutionProgressEvent", "description": "Session event \"tool.execution_progress\". Tool execution progress notification with status message" }, { "$ref": "#/definitions/ToolExecutionCompleteEvent", "description": "Session event \"tool.execution_complete\". Tool execution completion results including success status, detailed output, and error information" }, { "$ref": "#/definitions/ToolSearchActivatedEvent", "description": "Session event \"tool_search.activated\". Persisted generic client-side tool activations restored when a session resumes." }, { "$ref": "#/definitions/SkillInvokedEvent", "description": "Session event \"skill.invoked\". Skill invocation details including content, allowed tools, and plugin metadata" }, { "$ref": "#/definitions/SubagentStartedEvent", "description": "Session event \"subagent.started\". Sub-agent startup details including parent tool call and agent information" }, { "$ref": "#/definitions/SubagentCompletedEvent", "description": "Session event \"subagent.completed\". Sub-agent completion details for successful execution" }, { "$ref": "#/definitions/SubagentFailedEvent", "description": "Session event \"subagent.failed\". Sub-agent failure details including error message and agent information" }, { "$ref": "#/definitions/SubagentSelectedEvent", "description": "Session event \"subagent.selected\". Custom agent selection details including name and available tools" }, { "$ref": "#/definitions/SubagentDeselectedEvent", "description": "Session event \"subagent.deselected\". Empty payload; the event signals that the custom agent was deselected, returning to the default agent" }, { "$ref": "#/definitions/HookStartEvent", "description": "Session event \"hook.start\". Hook invocation start details including type and input data" }, { "$ref": "#/definitions/HookEndEvent", "description": "Session event \"hook.end\". Hook invocation completion details including output, success status, and error information" }, { "$ref": "#/definitions/HookProgressEvent", "description": "Session event \"hook.progress\". Ephemeral progress update from a running hook process" }, { "$ref": "#/definitions/BinaryAssetEvent", "description": "Session event \"session.binary_asset\". Canonical bytes for a content-addressed binary asset shared by reference across events" }, { "$ref": "#/definitions/SystemMessageEvent", "description": "Session event \"system.message\". System/developer instruction content with role and optional template metadata" }, { "$ref": "#/definitions/SystemNotificationEvent", "description": "Session event \"system.notification\". System-generated notification for runtime events like background task completion" }, { "$ref": "#/definitions/PermissionRequestedEvent", "description": "Session event \"permission.requested\". Permission request notification requiring client approval with request details" }, { "$ref": "#/definitions/PermissionCompletedEvent", "description": "Session event \"permission.completed\". Permission request completion notification signaling UI dismissal" }, { "$ref": "#/definitions/UserInputRequestedEvent", "description": "Session event \"user_input.requested\". User input request notification with question and optional predefined choices" }, { "$ref": "#/definitions/UserInputCompletedEvent", "description": "Session event \"user_input.completed\". User input request completion with the user's response" }, { "$ref": "#/definitions/ElicitationRequestedEvent", "description": "Session event \"elicitation.requested\". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)" }, { "$ref": "#/definitions/ElicitationCompletedEvent", "description": "Session event \"elicitation.completed\". Elicitation request completion with the user's response" }, { "$ref": "#/definitions/SamplingRequestedEvent", "description": "Session event \"sampling.requested\". Sampling request from an MCP server; contains the server name and a requestId for correlation" }, { "$ref": "#/definitions/SamplingCompletedEvent", "description": "Session event \"sampling.completed\". Sampling request completion notification signaling UI dismissal" }, { "$ref": "#/definitions/McpOauthRequiredEvent", "description": "Session event \"mcp.oauth_required\". OAuth authentication request for an MCP server" }, { "$ref": "#/definitions/McpOauthCompletedEvent", "description": "Session event \"mcp.oauth_completed\". MCP OAuth request completion notification" }, { "$ref": "#/definitions/McpHeadersRefreshRequiredEvent", "description": "Session event \"mcp.headers_refresh_required\". Dynamic headers refresh request for a remote MCP server" }, { "$ref": "#/definitions/McpHeadersRefreshCompletedEvent", "description": "Session event \"mcp.headers_refresh_completed\". MCP headers refresh request completion notification" }, { "$ref": "#/definitions/CustomNotificationEvent", "description": "Session event \"session.custom_notification\". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined." }, { "$ref": "#/definitions/ExternalToolRequestedEvent", "description": "Session event \"external_tool.requested\". External tool invocation request for client-side tool execution" }, { "$ref": "#/definitions/ExternalToolCompletedEvent", "description": "Session event \"external_tool.completed\". External tool completion notification signaling UI dismissal" }, { "$ref": "#/definitions/CommandQueuedEvent", "description": "Session event \"command.queued\". Queued slash command dispatch request for client execution" }, { "$ref": "#/definitions/CommandExecuteEvent", "description": "Session event \"command.execute\". Registered command dispatch request routed to the owning client" }, { "$ref": "#/definitions/CommandCompletedEvent", "description": "Session event \"command.completed\". Queued command completion notification signaling UI dismissal" }, { "$ref": "#/definitions/AutoModeSwitchRequestedEvent", "description": "Session event \"auto_mode_switch.requested\". Auto mode switch request notification requiring user approval" }, { "$ref": "#/definitions/AutoModeSwitchCompletedEvent", "description": "Session event \"auto_mode_switch.completed\". Auto mode switch completion notification" }, { "$ref": "#/definitions/SessionLimitsExhaustedRequestedEvent", "description": "Session event \"session_limits_exhausted.requested\". Session limit exhaustion notification requiring user action." }, { "$ref": "#/definitions/SessionLimitsExhaustedCompletedEvent", "description": "Session event \"session_limits_exhausted.completed\". Session limit exhaustion prompt completion notification." }, { "$ref": "#/definitions/AutoModeResolvedEvent", "description": "Session event \"session.auto_mode_resolved\". Auto Intent resolution: the concrete model the session settled on for the first prompt of an auto-mode session, and why. Lets SDK clients render the chosen model and the full reason it was picked. The core selection fields (chosenModel/reasoningBucket/categoryScores) are stable; the routing-analytics fields (predictedLabel/confidence/candidateModels) mirror the upstream intent service and may evolve, hence the event's experimental stability." }, { "$ref": "#/definitions/ManagedSettingsResolvedEvent", "description": "Session event \"session.managed_settings_resolved\". Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted. Device values take precedence over server values per ordinary key, while permissions compose restrictively across device, server, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes." }, { "$ref": "#/definitions/ManagedSettingsEnforcedEvent", "description": "Session event \"session.managed_settings_enforced\". Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes." }, { "$ref": "#/definitions/CommandsChangedEvent", "description": "Session event \"commands.changed\". SDK command registration change notification" }, { "$ref": "#/definitions/CapabilitiesChangedEvent", "description": "Session event \"capabilities.changed\". Session capability change notification" }, { "$ref": "#/definitions/ExitPlanModeRequestedEvent", "description": "Session event \"exit_plan_mode.requested\". Plan approval request with plan content and available user actions" }, { "$ref": "#/definitions/ExitPlanModeCompletedEvent", "description": "Session event \"exit_plan_mode.completed\". Plan mode exit completion with the user's approval decision and optional feedback" }, { "$ref": "#/definitions/ToolsUpdatedEvent", "description": "Session event \"session.tools_updated\". Payload of `session.tools_updated` identifying the model whose resolved tools were updated." }, { "$ref": "#/definitions/BackgroundTasksChangedEvent", "description": "Session event \"session.background_tasks_changed\". Empty payload for `session.background_tasks_changed`, indicating background task state changed." }, { "$ref": "#/definitions/FactoryRunUpdatedEvent", "description": "Session event \"factory.run_updated\". Ephemeral invalidation signal for a changed factory run." }, { "$ref": "#/definitions/SkillsLoadedEvent", "description": "Session event \"session.skills_loaded\". Payload of `session.skills_loaded` listing resolved skill metadata." }, { "$ref": "#/definitions/CustomAgentsUpdatedEvent", "description": "Session event \"session.custom_agents_updated\". Payload of `session.custom_agents_updated` with loaded custom agents plus non-fatal warnings and fatal errors." }, { "$ref": "#/definitions/McpServersLoadedEvent", "description": "Session event \"session.mcp_servers_loaded\". Payload of `session.mcp_servers_loaded` listing MCP server status summaries." }, { "$ref": "#/definitions/McpServerStatusChangedEvent", "description": "Session event \"session.mcp_server_status_changed\". Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error." }, { "$ref": "#/definitions/McpToolsListChangedEvent", "description": "Session event \"mcp.tools.list_changed\". Payload identifying the MCP server associated with a list change." }, { "$ref": "#/definitions/McpResourcesListChangedEvent", "description": "Session event \"mcp.resources.list_changed\". Payload identifying the MCP server associated with a list change." }, { "$ref": "#/definitions/McpPromptsListChangedEvent", "description": "Session event \"mcp.prompts.list_changed\". Payload identifying the MCP server associated with a list change." }, { "$ref": "#/definitions/ExtensionsLoadedEvent", "description": "Session event \"session.extensions_loaded\". Payload of `session.extensions_loaded` listing discovered extensions and their statuses." }, { "$ref": "#/definitions/CanvasOpenedEvent", "description": "Session event \"session.canvas.opened\". Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input." }, { "$ref": "#/definitions/CanvasRegistryChangedEvent", "description": "Session event \"session.canvas.registry_changed\". Payload of `session.canvas.registry_changed` listing the canvas declarations currently available." }, { "$ref": "#/definitions/CanvasClosedEvent", "description": "Session event \"session.canvas.closed\". Payload of `session.canvas.closed` with the closed canvas instance ID, provider ID, and canvas ID." }, { "$ref": "#/definitions/CanvasUnavailableEvent", "description": "Session event \"session.canvas.unavailable\". Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume." }, { "$ref": "#/definitions/CanvasRecordedEvent", "description": "Session event \"session.canvas.recorded\". Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability." }, { "$ref": "#/definitions/CanvasRemovedEvent", "description": "Session event \"session.canvas.removed\". Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay." }, { "$ref": "#/definitions/ExtensionsAttachmentsPushedEvent", "description": "Session event \"session.extensions.attachments_pushed\". Payload of `session.extensions.attachments_pushed` with extension-contributed attachments for the next send." }, { "$ref": "#/definitions/McpAppToolCallCompleteEvent", "description": "Session event \"mcp_app.tool_call_complete\". MCP App view called a tool on a connected MCP server (SEP-1865)" } ], "description": "Union of all session event variants emitted by the Copilot CLI runtime." }, "SessionLimitsChangedData": { "type": "object", "properties": { "sessionLimits": { "anyOf": [ { "$ref": "#/definitions/SessionLimitsConfig", "description": "Optional session limits." }, { "type": "null" } ], "description": "Current session limits, or null when no limits are active" } }, "required": [ "sessionLimits" ], "additionalProperties": false, "description": "Session limits update details. Null clears the limits.", "title": "SessionLimitsChangedData" }, "SessionLimitsChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.session_limits_changed", "description": "Type discriminator. Always \"session.session_limits_changed\"." }, "data": { "$ref": "#/definitions/SessionLimitsChangedData", "description": "Session limits update details. Null clears the limits." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.session_limits_changed\". Session limits update details. Null clears the limits.", "title": "SessionLimitsChangedEvent" }, "SessionLimitsConfig": { "type": "object", "properties": { "maxAiCredits": { "type": "number", "exclusiveMinimum": 0, "description": "Maximum AI Credits allowed across the session's current accounting window." } }, "additionalProperties": false, "description": "Optional session limits.", "title": "SessionLimitsConfig" }, "SessionLimitsExhaustedCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved request; clients should dismiss any UI for this request." }, "response": { "$ref": "#/definitions/SessionLimitsExhaustedResponse", "description": "The user's selected session-limit action." } }, "required": [ "requestId", "response" ], "additionalProperties": false, "description": "Session limit exhaustion prompt completion notification.", "title": "SessionLimitsExhaustedCompletedData" }, "SessionLimitsExhaustedCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session_limits_exhausted.completed", "description": "Type discriminator. Always \"session_limits_exhausted.completed\"." }, "data": { "$ref": "#/definitions/SessionLimitsExhaustedCompletedData", "description": "Session limit exhaustion prompt completion notification." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session_limits_exhausted.completed\". Session limit exhaustion prompt completion notification.", "title": "SessionLimitsExhaustedCompletedEvent" }, "SessionLimitsExhaustedRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this request; used to respond via session.ui.handlePendingSessionLimitsExhausted()." }, "usedAiCredits": { "type": "number", "minimum": 0, "description": "AI Credits already consumed in the current accounting window." }, "maxAiCredits": { "type": "number", "exclusiveMinimum": 0, "description": "Configured max AI Credits for the current accounting window." } }, "required": [ "requestId", "usedAiCredits", "maxAiCredits" ], "additionalProperties": false, "description": "Session limit exhaustion notification requiring user action.", "title": "SessionLimitsExhaustedRequestedData" }, "SessionLimitsExhaustedRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session_limits_exhausted.requested", "description": "Type discriminator. Always \"session_limits_exhausted.requested\"." }, "data": { "$ref": "#/definitions/SessionLimitsExhaustedRequestedData", "description": "Session limit exhaustion notification requiring user action." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session_limits_exhausted.requested\". Session limit exhaustion notification requiring user action.", "title": "SessionLimitsExhaustedRequestedEvent" }, "SessionLimitsExhaustedResponse": { "type": "object", "properties": { "action": { "$ref": "#/definitions/SessionLimitsExhaustedResponseAction", "description": "Action selected by the user." }, "additionalAiCredits": { "type": "number", "exclusiveMinimum": 0, "description": "AI Credits to add to the current max when action is 'add'." }, "maxAiCredits": { "type": "number", "exclusiveMinimum": 0, "description": "New absolute max AI Credits when action is 'set'." } }, "required": [ "action" ], "additionalProperties": false, "description": "The user's selected action for an exhausted session limit.", "title": "SessionLimitsExhaustedResponse" }, "SessionLimitsExhaustedResponseAction": { "type": "string", "enum": [ "add", "set", "unset", "cancel" ], "description": "User action selected for an exhausted session limit.", "title": "SessionLimitsExhaustedResponseAction", "x-enumDescriptions": { "add": "Increase the current max by an exact AI Credits amount.", "set": "Set a new absolute max AI Credits value.", "unset": "Remove the current session limit.", "cancel": "Leave the limit unchanged and cancel the blocked model request." } }, "SessionMode": { "type": "string", "enum": [ "interactive", "plan", "autopilot" ], "description": "The session mode the agent is operating in", "title": "SessionMode", "x-enumDescriptions": { "interactive": "The agent is responding interactively to the user.", "plan": "The agent is preparing a plan before making changes.", "autopilot": "The agent is working autonomously toward task completion." } }, "ShutdownCodeChanges": { "type": "object", "properties": { "linesAdded": { "type": "integer", "minimum": 0, "description": "Total number of lines added during the session" }, "linesRemoved": { "type": "integer", "minimum": 0, "description": "Total number of lines removed during the session" }, "filesModified": { "type": "array", "items": { "type": "string" }, "description": "List of file paths that were modified during the session" } }, "required": [ "linesAdded", "linesRemoved", "filesModified" ], "additionalProperties": false, "description": "Aggregate code change metrics for the session", "title": "ShutdownCodeChanges" }, "ShutdownData": { "type": "object", "properties": { "shutdownType": { "$ref": "#/definitions/ShutdownType", "description": "Whether the session ended normally (\"routine\") or due to a crash/fatal error (\"error\")" }, "errorReason": { "type": "string", "description": "Error description when shutdownType is \"error\"" }, "totalPremiumRequests": { "type": "number", "minimum": 0, "description": "Total number of premium API requests used during the session", "visibility": "internal" }, "totalNanoAiu": { "type": "number", "minimum": 0, "description": "Session-wide accumulated nano-AI units cost", "stability": "experimental" }, "tokenDetails": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ShutdownTokenDetail", "description": "A session-wide shutdown token-type entry storing the accumulated token count." }, "description": "Session-wide per-token-type accumulated token counts" }, "totalApiDurationMs": { "type": "integer", "minimum": 0, "format": "duration", "description": "Cumulative time spent in API calls during the session, in milliseconds" }, "sessionStartTime": { "type": "integer", "minimum": 0, "description": "Unix timestamp (milliseconds) when the session started" }, "eventsFileSizeBytes": { "type": "integer", "minimum": 0, "description": "On-disk byte size of the session's persisted events.jsonl file at shutdown time; omitted when the file does not exist or cannot be stat'd" }, "codeChanges": { "$ref": "#/definitions/ShutdownCodeChanges", "description": "Aggregate code change metrics for the session" }, "modelMetrics": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ShutdownModelMetric", "description": "Per-model shutdown metrics with request counts, token usage, nano-AI units, and token details." }, "description": "Per-model usage breakdown, keyed by model identifier" }, "currentModel": { "type": "string", "description": "Model that was selected at the time of shutdown" }, "currentTokens": { "type": "integer", "minimum": 0, "description": "Total tokens in context window at shutdown" }, "systemTokens": { "type": "integer", "minimum": 0, "description": "System message token count at shutdown" }, "conversationTokens": { "type": "integer", "minimum": 0, "description": "Non-system message token count at shutdown" }, "toolDefinitionsTokens": { "type": "integer", "minimum": 0, "description": "Tool definitions token count at shutdown" } }, "required": [ "shutdownType", "totalApiDurationMs", "sessionStartTime", "codeChanges", "modelMetrics" ], "additionalProperties": false, "description": "Session termination metrics including usage statistics, code changes, and shutdown reason", "title": "ShutdownData" }, "ShutdownEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.shutdown", "description": "Type discriminator. Always \"session.shutdown\"." }, "data": { "$ref": "#/definitions/ShutdownData", "description": "Session termination metrics including usage statistics, code changes, and shutdown reason" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.shutdown\". Session termination metrics including usage statistics, code changes, and shutdown reason", "title": "ShutdownEvent" }, "ShutdownModelMetric": { "type": "object", "properties": { "requests": { "$ref": "#/definitions/ShutdownModelMetricRequests", "description": "Request count and cost metrics" }, "usage": { "$ref": "#/definitions/ShutdownModelMetricUsage", "description": "Token usage breakdown" }, "totalNanoAiu": { "type": "number", "minimum": 0, "description": "Accumulated nano-AI units cost for this model", "stability": "experimental" }, "tokenDetails": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ShutdownModelMetricTokenDetail", "description": "A token-type entry in a shutdown model metric, storing the accumulated token count." }, "description": "Token count details per type" } }, "required": [ "requests", "usage" ], "additionalProperties": false, "description": "Per-model shutdown metrics with request counts, token usage, nano-AI units, and token details.", "title": "ShutdownModelMetric" }, "ShutdownModelMetricRequests": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "description": "Total number of API requests made to this model", "stability": "experimental" }, "cost": { "type": "number", "description": "Cumulative cost multiplier for requests to this model", "stability": "experimental" } }, "additionalProperties": false, "description": "Request count and cost metrics", "title": "ShutdownModelMetricRequests" }, "ShutdownModelMetricTokenDetail": { "type": "object", "properties": { "tokenCount": { "type": "integer", "minimum": 0, "description": "Accumulated token count for this token type" } }, "required": [ "tokenCount" ], "additionalProperties": false, "description": "A token-type entry in a shutdown model metric, storing the accumulated token count.", "title": "ShutdownModelMetricTokenDetail" }, "ShutdownModelMetricUsage": { "type": "object", "properties": { "inputTokens": { "type": "integer", "minimum": 0, "description": "Total input tokens consumed across all requests to this model" }, "outputTokens": { "type": "integer", "minimum": 0, "description": "Total output tokens produced across all requests to this model" }, "cacheReadTokens": { "type": "integer", "minimum": 0, "description": "Total tokens read from prompt cache across all requests" }, "cacheWriteTokens": { "type": "integer", "minimum": 0, "description": "Total tokens written to prompt cache across all requests" }, "reasoningTokens": { "type": "integer", "minimum": 0, "description": "Total reasoning tokens produced across all requests to this model" } }, "required": [ "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "additionalProperties": false, "description": "Token usage breakdown", "title": "ShutdownModelMetricUsage" }, "ShutdownTokenDetail": { "type": "object", "properties": { "tokenCount": { "type": "integer", "minimum": 0, "description": "Accumulated token count for this token type" } }, "required": [ "tokenCount" ], "additionalProperties": false, "description": "A session-wide shutdown token-type entry storing the accumulated token count.", "title": "ShutdownTokenDetail" }, "ShutdownType": { "type": "string", "enum": [ "routine", "error" ], "description": "Whether the session ended normally (\"routine\") or due to a crash/fatal error (\"error\")", "title": "ShutdownType", "x-enumDescriptions": { "routine": "The session ended normally.", "error": "The session ended because of a crash or fatal error." } }, "SkillInvokedData": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the invoked skill" }, "model": { "type": "string", "description": "Model identifier active when the skill was invoked, when known" }, "path": { "type": "string", "description": "File path to the SKILL.md definition" }, "content": { "type": "string", "description": "Full content of the skill file, injected into the conversation for the model" }, "allowedTools": { "type": "array", "items": { "type": "string" }, "description": "Tool names that should be auto-approved when this skill is active" }, "source": { "type": "string", "description": "Source identifier for where the skill was discovered. Known values include: project (workspace skill), inherited (parent-directory skill), personal-copilot (~/.copilot/skills), personal-agents (~/.agents/skills), custom (configured directory), plugin (installed plugin), builtin (bundled runtime skill), and remote (org/enterprise skill)" }, "pluginName": { "type": "string", "description": "Name of the plugin this skill originated from, when applicable" }, "pluginVersion": { "type": "string", "description": "Version of the plugin this skill originated from, when applicable" }, "description": { "type": "string", "description": "Description of the skill from its SKILL.md frontmatter" }, "trigger": { "$ref": "#/definitions/SkillInvokedTrigger", "description": "What triggered the skill invocation: `user-invoked` (explicit user action, such as via a slash command or UI affordance), `agent-invoked` (agent requested the skill), or `context-load` (loaded as part of another context, such as preloading skills configured on a custom agent or subagent)" } }, "required": [ "name", "path", "content" ], "additionalProperties": false, "description": "Skill invocation details including content, allowed tools, and plugin metadata", "title": "SkillInvokedData" }, "SkillInvokedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "skill.invoked", "description": "Type discriminator. Always \"skill.invoked\"." }, "data": { "$ref": "#/definitions/SkillInvokedData", "description": "Skill invocation details including content, allowed tools, and plugin metadata" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"skill.invoked\". Skill invocation details including content, allowed tools, and plugin metadata", "title": "SkillInvokedEvent" }, "SkillInvokedTrigger": { "type": "string", "enum": [ "user-invoked", "agent-invoked", "context-load" ], "description": "What triggered the skill invocation: `user-invoked` (explicit user action, such as via a slash command or UI affordance), `agent-invoked` (agent requested the skill), or `context-load` (loaded as part of another context, such as preloading skills configured on a custom agent or subagent)", "title": "SkillInvokedTrigger", "x-enumDescriptions": { "user-invoked": "Skill invocation requested explicitly by the user, such as via a slash command or UI affordance.", "agent-invoked": "Skill invocation requested by the agent.", "context-load": "Skill content loaded as part of another context, such as a configured custom agent or subagent." } }, "SkillsLoadedData": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/definitions/SkillsLoadedSkill", "description": "A single resolved skill in `session.skills_loaded`, including source, invocability, enabled state, path, and argument hint." }, "description": "Array of resolved skill metadata" } }, "required": [ "skills" ], "additionalProperties": false, "description": "Payload of `session.skills_loaded` listing resolved skill metadata.", "title": "SkillsLoadedData" }, "SkillsLoadedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.skills_loaded", "description": "Type discriminator. Always \"session.skills_loaded\"." }, "data": { "$ref": "#/definitions/SkillsLoadedData", "description": "Payload of `session.skills_loaded` listing resolved skill metadata." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.skills_loaded\". Payload of `session.skills_loaded` listing resolved skill metadata.", "title": "SkillsLoadedEvent" }, "SkillsLoadedSkill": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique identifier for the skill" }, "commandName": { "type": "string", "description": "Canonical slash command name used to invoke the skill, without the leading '/'" }, "description": { "type": "string", "description": "Description of what the skill does" }, "source": { "$ref": "#/definitions/SkillSource", "description": "Source location type (e.g., project, personal-copilot, plugin, builtin)" }, "userInvocable": { "type": "boolean", "description": "Whether the skill can be invoked by the user as a slash command" }, "enabled": { "type": "boolean", "description": "Whether the skill is currently enabled" }, "path": { "type": "string", "description": "Absolute path to the skill file, if available" }, "argumentHint": { "type": "string", "description": "Optional freeform hint describing the skill's expected arguments, from the `argument-hint` frontmatter field" } }, "required": [ "name", "description", "source", "userInvocable", "enabled" ], "additionalProperties": false, "description": "A single resolved skill in `session.skills_loaded`, including source, invocability, enabled state, path, and argument hint.", "title": "SkillsLoadedSkill" }, "SkillSource": { "type": "string", "enum": [ "project", "inherited", "personal-copilot", "personal-agents", "plugin", "custom", "builtin" ], "description": "Source location type (e.g., project, personal-copilot, plugin, builtin)", "title": "SkillSource", "x-enumDescriptions": { "project": "Skill defined in the current project's skill directories.", "inherited": "Skill discovered from a parent directory in the current workspace tree.", "personal-copilot": "Skill defined in the user's Copilot skill directory.", "personal-agents": "Skill defined in the user's personal agents skill directory.", "plugin": "Skill provided by an installed plugin.", "custom": "Skill loaded from a configured custom skill directory.", "builtin": "Skill bundled with the runtime." } }, "SnapshotRewindData": { "type": "object", "properties": { "upToEventId": { "type": "string", "description": "Event ID that was rewound to; this event and all after it were removed" }, "eventsRemoved": { "type": "integer", "minimum": 0, "description": "Number of events that were removed by the rewind" } }, "required": [ "upToEventId", "eventsRemoved" ], "additionalProperties": false, "description": "Session rewind details including target event and count of removed events", "title": "SnapshotRewindData" }, "SnapshotRewindEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.snapshot_rewind", "description": "Type discriminator. Always \"session.snapshot_rewind\"." }, "data": { "$ref": "#/definitions/SnapshotRewindData", "description": "Session rewind details including target event and count of removed events" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.snapshot_rewind\". Session rewind details including target event and count of removed events", "title": "SnapshotRewindEvent" }, "StartData": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Unique identifier for the session" }, "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Schema version number for the session event format" }, "producer": { "type": "string", "description": "Identifier of the software producing the events (e.g., \"copilot-agent\")" }, "copilotVersion": { "type": "string", "description": "Version string of the Copilot application" }, "startTime": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the session was created" }, "selectedModel": { "type": "string", "description": "Model selected at session creation time, if any" }, "reasoningEffort": { "type": "string", "description": "Reasoning effort level used for model calls, if applicable (e.g. \"none\", \"low\", \"medium\", \"high\", \"xhigh\", \"max\")" }, "reasoningSummary": { "$ref": "#/definitions/ReasoningSummary", "description": "Reasoning summary mode used for model calls, if applicable (e.g. \"none\", \"concise\", \"detailed\")" }, "verbosity": { "$ref": "#/definitions/Verbosity", "description": "Output verbosity level used for model calls, if applicable (e.g. \"low\", \"medium\", \"high\")" }, "contextTier": { "anyOf": [ { "$ref": "#/definitions/ContextTier" }, { "type": "null" } ], "description": "Context tier selected at session creation time for models with tiered context pricing; null when no tier is selected (e.g., non-tiered model)" }, "sessionLimits": { "$ref": "#/definitions/SessionLimitsConfig", "description": "Session limits configured at session creation time, if any" }, "context": { "$ref": "#/definitions/WorkingDirectoryContext", "description": "Working directory and git context at session start" }, "githubMcpToolConfig": { "$ref": "#/definitions/GitHubMcpToolConfig", "description": "Per-session GitHub MCP override persisted for cold resume" }, "alreadyInUse": { "type": "boolean", "description": "Whether the session was already in use by another client at start time" }, "remoteSteerable": { "type": "boolean", "description": "Whether this session supports remote steering via GitHub" }, "detachedFromSpawningParentSessionId": { "type": "string", "description": "When set, identifies a parent session whose context this session continues — e.g., a detached headless rem-agent run launched on the parent's interactive shutdown. Telemetry from this session is reported under the parent's session_id." } }, "required": [ "sessionId", "version", "producer", "copilotVersion", "startTime" ], "additionalProperties": false, "description": "Session initialization metadata including context and configuration", "title": "StartData" }, "StartEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.start", "description": "Type discriminator. Always \"session.start\"." }, "data": { "$ref": "#/definitions/StartData", "description": "Session initialization metadata including context and configuration" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.start\". Session initialization metadata including context and configuration", "title": "StartEvent" }, "SubagentCompletedData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Tool call ID of the parent tool invocation that spawned this sub-agent" }, "agentName": { "type": "string", "description": "Internal name of the sub-agent" }, "agentDisplayName": { "type": "string", "description": "Human-readable display name of the sub-agent" }, "model": { "type": "string", "description": "Model used by the sub-agent" }, "totalToolCalls": { "type": "integer", "minimum": 0, "description": "Total number of tool calls made by the sub-agent" }, "totalTokens": { "type": "integer", "minimum": 0, "description": "Total tokens (input + output) consumed by the sub-agent" }, "durationMs": { "type": "integer", "minimum": 0, "format": "duration", "description": "Wall-clock duration of the sub-agent execution in milliseconds" }, "cancelled": { "type": "boolean", "description": "Whether the sub-agent was torn down by cancellation - its own abort, or an ancestor being killed - instead of finishing its work. Cancellation is not a failure, so the run still reports completion; this distinguishes a torn-down sub-agent from one that ran to the end." } }, "required": [ "toolCallId", "agentName", "agentDisplayName" ], "additionalProperties": false, "description": "Sub-agent completion details for successful execution", "title": "SubagentCompletedData" }, "SubagentCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "subagent.completed", "description": "Type discriminator. Always \"subagent.completed\"." }, "data": { "$ref": "#/definitions/SubagentCompletedData", "description": "Sub-agent completion details for successful execution" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"subagent.completed\". Sub-agent completion details for successful execution", "title": "SubagentCompletedEvent" }, "SubagentDeselectedData": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Empty payload; the event signals that the custom agent was deselected, returning to the default agent", "title": "SubagentDeselectedData" }, "SubagentDeselectedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "subagent.deselected", "description": "Type discriminator. Always \"subagent.deselected\"." }, "data": { "$ref": "#/definitions/SubagentDeselectedData", "description": "Empty payload; the event signals that the custom agent was deselected, returning to the default agent" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"subagent.deselected\". Empty payload; the event signals that the custom agent was deselected, returning to the default agent", "title": "SubagentDeselectedEvent" }, "SubagentFailedData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Tool call ID of the parent tool invocation that spawned this sub-agent" }, "agentName": { "type": "string", "description": "Internal name of the sub-agent" }, "agentDisplayName": { "type": "string", "description": "Human-readable display name of the sub-agent" }, "error": { "type": "string", "description": "Error message describing why the sub-agent failed" }, "model": { "type": "string", "description": "Model selected for the sub-agent, when known" }, "totalToolCalls": { "type": "integer", "minimum": 0, "description": "Total number of tool calls made before the sub-agent failed" }, "totalTokens": { "type": "integer", "minimum": 0, "description": "Total tokens (input + output) consumed before the sub-agent failed" }, "durationMs": { "type": "integer", "minimum": 0, "format": "duration", "description": "Wall-clock duration of the sub-agent execution in milliseconds" } }, "required": [ "toolCallId", "agentName", "agentDisplayName", "error" ], "additionalProperties": false, "description": "Sub-agent failure details including error message and agent information", "title": "SubagentFailedData" }, "SubagentFailedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "subagent.failed", "description": "Type discriminator. Always \"subagent.failed\"." }, "data": { "$ref": "#/definitions/SubagentFailedData", "description": "Sub-agent failure details including error message and agent information" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"subagent.failed\". Sub-agent failure details including error message and agent information", "title": "SubagentFailedEvent" }, "SubagentSelectedData": { "type": "object", "properties": { "agentName": { "type": "string", "description": "Internal name of the selected custom agent" }, "agentDisplayName": { "type": "string", "description": "Human-readable display name of the selected custom agent" }, "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "List of tool names available to this agent, or null for all tools" } }, "required": [ "agentName", "agentDisplayName", "tools" ], "additionalProperties": false, "description": "Custom agent selection details including name and available tools", "title": "SubagentSelectedData" }, "SubagentSelectedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "subagent.selected", "description": "Type discriminator. Always \"subagent.selected\"." }, "data": { "$ref": "#/definitions/SubagentSelectedData", "description": "Custom agent selection details including name and available tools" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"subagent.selected\". Custom agent selection details including name and available tools", "title": "SubagentSelectedEvent" }, "SubagentStartedData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Tool call ID of the parent tool invocation that spawned this sub-agent" }, "agentName": { "type": "string", "description": "Internal name of the sub-agent" }, "agentDisplayName": { "type": "string", "description": "Human-readable display name of the sub-agent" }, "agentDescription": { "type": "string", "description": "Description of what the sub-agent does" }, "model": { "type": "string", "description": "Model the sub-agent will run with, when known at start." } }, "required": [ "toolCallId", "agentName", "agentDisplayName", "agentDescription" ], "additionalProperties": false, "description": "Sub-agent startup details including parent tool call and agent information", "title": "SubagentStartedData" }, "SubagentStartedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "subagent.started", "description": "Type discriminator. Always \"subagent.started\"." }, "data": { "$ref": "#/definitions/SubagentStartedData", "description": "Sub-agent startup details including parent tool call and agent information" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"subagent.started\". Sub-agent startup details including parent tool call and agent information", "title": "SubagentStartedEvent" }, "SystemMessageData": { "type": "object", "properties": { "content": { "type": "string", "description": "The system or developer prompt text sent as model input" }, "interactionId": { "type": "string", "description": "Logical interaction identifier for the model run receiving this prompt" }, "role": { "$ref": "#/definitions/SystemMessageRole", "description": "Message role: \"system\" for system prompts, \"developer\" for developer-injected instructions" }, "name": { "type": "string", "description": "Optional name identifier for the message source" }, "metadata": { "$ref": "#/definitions/SystemMessageMetadata", "description": "Metadata about the prompt template and its construction" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "System/developer instruction content with role and optional template metadata", "title": "SystemMessageData" }, "SystemMessageEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "system.message", "description": "Type discriminator. Always \"system.message\"." }, "data": { "$ref": "#/definitions/SystemMessageData", "description": "System/developer instruction content with role and optional template metadata" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"system.message\". System/developer instruction content with role and optional template metadata", "title": "SystemMessageEvent" }, "SystemMessageMetadata": { "type": "object", "properties": { "promptVersion": { "type": "string", "description": "Version identifier of the prompt template used" }, "variables": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Template variables used when constructing the prompt" } }, "additionalProperties": false, "description": "Metadata about the prompt template and its construction", "title": "SystemMessageMetadata" }, "SystemMessageRole": { "type": "string", "enum": [ "system", "developer" ], "description": "Message role: \"system\" for system prompts, \"developer\" for developer-injected instructions", "title": "SystemMessageRole", "x-enumDescriptions": { "system": "System prompt message.", "developer": "Developer instruction message." } }, "SystemNotification": { "anyOf": [ { "$ref": "#/definitions/SystemNotificationAgentCompleted", "description": "System notification metadata for a background agent that completed or failed, including agent ID, type, status, description, and prompt." }, { "$ref": "#/definitions/SystemNotificationAgentIdle", "description": "System notification metadata for a background agent that became idle, including agent ID, type, and description." }, { "$ref": "#/definitions/SystemNotificationNewInboxMessage", "description": "System notification metadata for a new inbox message, including entry ID, sender details, and summary." }, { "$ref": "#/definitions/SystemNotificationShellCompleted", "description": "System notification metadata for a shell session that completed, including shell ID, optional exit code, and description." }, { "$ref": "#/definitions/SystemNotificationShellDetachedCompleted", "description": "System notification metadata for a detached shell session that completed, including shell ID and description." }, { "$ref": "#/definitions/SystemNotificationInstructionDiscovered", "description": "System notification metadata for an instruction file discovered during tool access, including source, trigger file, and tool." }, { "$ref": "#/definitions/SystemNotificationFactoryCompleted", "description": "System notification metadata for a factory execution attempt that reached a terminal state." }, { "$ref": "#/definitions/SystemNotificationUnclassified", "description": "System notification metadata from an external host that does not match a runtime-owned notification kind." } ], "description": "Structured metadata identifying what triggered this notification", "title": "SystemNotification" }, "SystemNotificationAgentCompleted": { "type": "object", "properties": { "type": { "type": "string", "const": "agent_completed", "description": "Type discriminator. Always \"agent_completed\"." }, "agentId": { "type": "string", "description": "Unique identifier of the background agent" }, "agentType": { "type": "string", "description": "Type of the agent (e.g., explore, task, general-purpose)" }, "status": { "$ref": "#/definitions/SystemNotificationAgentCompletedStatus", "description": "Whether the agent completed successfully or failed" }, "description": { "type": "string", "description": "Human-readable description of the agent task" }, "prompt": { "type": "string", "description": "The full prompt given to the background agent" } }, "required": [ "type", "agentId", "agentType", "status" ], "additionalProperties": false, "description": "System notification metadata for a background agent that completed or failed, including agent ID, type, status, description, and prompt.", "title": "SystemNotificationAgentCompleted" }, "SystemNotificationAgentCompletedStatus": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the agent completed successfully or failed", "title": "SystemNotificationAgentCompletedStatus", "x-enumDescriptions": { "completed": "The agent completed successfully.", "failed": "The agent failed." } }, "SystemNotificationAgentIdle": { "type": "object", "properties": { "type": { "type": "string", "const": "agent_idle", "description": "Type discriminator. Always \"agent_idle\"." }, "agentId": { "type": "string", "description": "Unique identifier of the background agent" }, "agentType": { "type": "string", "description": "Type of the agent (e.g., explore, task, general-purpose)" }, "description": { "type": "string", "description": "Human-readable description of the agent task" } }, "required": [ "type", "agentId", "agentType" ], "additionalProperties": false, "description": "System notification metadata for a background agent that became idle, including agent ID, type, and description.", "title": "SystemNotificationAgentIdle" }, "SystemNotificationData": { "type": "object", "properties": { "content": { "type": "string", "description": "The notification text, typically wrapped in XML tags" }, "kind": { "$ref": "#/definitions/SystemNotification", "description": "Structured metadata identifying what triggered this notification" } }, "required": [ "content", "kind" ], "additionalProperties": false, "description": "System-generated notification for runtime events like background task completion", "title": "SystemNotificationData" }, "SystemNotificationEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "system.notification", "description": "Type discriminator. Always \"system.notification\"." }, "data": { "$ref": "#/definitions/SystemNotificationData", "description": "System-generated notification for runtime events like background task completion" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"system.notification\". System-generated notification for runtime events like background task completion", "title": "SystemNotificationEvent" }, "SystemNotificationFactoryCompleted": { "type": "object", "properties": { "type": { "type": "string", "const": "factory_completed", "description": "Type discriminator. Always \"factory_completed\"." }, "runId": { "type": "string", "description": "Factory run identifier." }, "factoryName": { "type": "string", "description": "Persisted factory name." }, "status": { "$ref": "#/definitions/SystemNotificationFactoryCompletedStatus", "description": "Terminal status reached by this execution attempt." }, "consumedSubagents": { "type": "integer", "minimum": 0, "description": "Subagents consumed by the run across all attempts." }, "elapsedMs": { "type": "integer", "minimum": 0, "description": "Accumulated active execution time in milliseconds." }, "consumedNanoAiu": { "type": "integer", "minimum": 0, "description": "Consumed AI usage in nano-AIU." }, "attempt": { "type": "integer", "minimum": 1, "description": "Execution attempt that reached this terminal state." }, "resultPreview": { "type": "string", "maxLength": 256, "description": "Bounded prompt-safe preview of the completed result." }, "failure": { "description": "Machine-readable terminal failure details, when present.", "x-opaque-json": true }, "retryGuidance": { "type": "string", "description": "Actionable run_factory resume guidance for a resource-limit failure." } }, "required": [ "type", "runId", "factoryName", "status", "consumedSubagents", "elapsedMs", "consumedNanoAiu", "attempt" ], "additionalProperties": false, "description": "System notification metadata for a factory execution attempt that reached a terminal state.", "title": "SystemNotificationFactoryCompleted" }, "SystemNotificationFactoryCompletedStatus": { "type": "string", "enum": [ "completed", "halted", "cancelled", "error" ], "description": "Terminal status reached by a factory execution attempt.", "title": "SystemNotificationFactoryCompletedStatus", "x-enumDescriptions": { "completed": "The factory completed successfully.", "halted": "The factory was halted.", "cancelled": "The factory was cancelled.", "error": "The factory failed." } }, "SystemNotificationInstructionDiscovered": { "type": "object", "properties": { "type": { "type": "string", "const": "instruction_discovered", "description": "Type discriminator. Always \"instruction_discovered\"." }, "sourcePath": { "type": "string", "description": "Relative path to the discovered instruction file" }, "triggerFile": { "type": "string", "description": "Path of the file access that triggered discovery" }, "triggerTool": { "type": "string", "description": "Tool command that triggered discovery (currently always 'view')" }, "description": { "type": "string", "description": "Human-readable label for the timeline (e.g., 'AGENTS.md from packages/billing/')" } }, "required": [ "type", "sourcePath", "triggerFile", "triggerTool" ], "additionalProperties": false, "description": "System notification metadata for an instruction file discovered during tool access, including source, trigger file, and tool.", "title": "SystemNotificationInstructionDiscovered" }, "SystemNotificationNewInboxMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "new_inbox_message", "description": "Type discriminator. Always \"new_inbox_message\"." }, "entryId": { "type": "string", "description": "Unique identifier of the inbox entry" }, "senderName": { "type": "string", "description": "Human-readable name of the sender" }, "senderType": { "type": "string", "description": "Category of the sender (e.g., sidekick-agent, plugin, hook)" }, "summary": { "type": "string", "description": "Short summary shown before the agent decides whether to read the inbox" } }, "required": [ "type", "entryId", "senderName", "senderType", "summary" ], "additionalProperties": false, "description": "System notification metadata for a new inbox message, including entry ID, sender details, and summary.", "title": "SystemNotificationNewInboxMessage" }, "SystemNotificationShellCompleted": { "type": "object", "properties": { "type": { "type": "string", "const": "shell_completed", "description": "Type discriminator. Always \"shell_completed\"." }, "shellId": { "type": "string", "description": "Unique identifier of the shell session" }, "exitCode": { "type": "integer", "description": "Exit code of the shell command, if available" }, "description": { "type": "string", "description": "Human-readable description of the command" } }, "required": [ "type", "shellId" ], "additionalProperties": false, "description": "System notification metadata for a shell session that completed, including shell ID, optional exit code, and description.", "title": "SystemNotificationShellCompleted" }, "SystemNotificationShellDetachedCompleted": { "type": "object", "properties": { "type": { "type": "string", "const": "shell_detached_completed", "description": "Type discriminator. Always \"shell_detached_completed\"." }, "shellId": { "type": "string", "description": "Unique identifier of the detached shell session" }, "description": { "type": "string", "description": "Human-readable description of the command" } }, "required": [ "type", "shellId" ], "additionalProperties": false, "description": "System notification metadata for a detached shell session that completed, including shell ID and description.", "title": "SystemNotificationShellDetachedCompleted" }, "SystemNotificationUnclassified": { "type": "object", "properties": { "type": { "type": "string", "const": "unclassified", "description": "Type discriminator. Always \"unclassified\"." }, "metadata": { "description": "Opaque metadata supplied by the external host, when present.", "x-opaque-json": true } }, "required": [ "type" ], "additionalProperties": false, "description": "System notification metadata from an external host that does not match a runtime-owned notification kind.", "title": "SystemNotificationUnclassified" }, "TaskCompleteData": { "type": "object", "properties": { "summary": { "type": "string", "default": "", "description": "Summary of the completed task, provided by the agent" }, "success": { "type": "boolean", "description": "Whether the task was accepted as complete. False when validation failed or completion was rejected or blocked by the reviewer" }, "outcome": { "$ref": "#/definitions/TaskCompletionOutcome", "description": "Semantic completion decision. Absent on legacy events and invalid tool calls" }, "reason": { "type": "string", "description": "Label-safe runtime rationale for the completion decision (e.g. a cancellation or pause/resume downgrade), when one applies. Reviewer-authored rationale is intentionally omitted here because this event has no IFC label channel; the reviewer's findings remain available through its own labeled sub-agent events" }, "objectiveId": { "type": "integer", "description": "Active autopilot objective ID evaluated by the completion reviewer" } }, "additionalProperties": false, "description": "Task completion notification with summary from the agent", "title": "TaskCompleteData" }, "TaskCompleteEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.task_complete", "description": "Type discriminator. Always \"session.task_complete\"." }, "data": { "$ref": "#/definitions/TaskCompleteData", "description": "Task completion notification with summary from the agent" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.task_complete\". Task completion notification with summary from the agent", "title": "TaskCompleteEvent" }, "TaskCompletionOutcome": { "type": "string", "enum": [ "completed", "continue", "blocked" ], "description": "Semantic result of evaluating a task completion request", "title": "TaskCompletionOutcome", "x-enumDescriptions": { "completed": "The completion request was accepted and the objective is complete.", "continue": "The completion request was rejected because more work or validation remains.", "blocked": "Completion cannot proceed without intervention; the active objective is paused when one is identified." } }, "TitleChangedData": { "type": "object", "properties": { "title": { "type": "string", "description": "The new display title for the session" } }, "required": [ "title" ], "additionalProperties": false, "description": "Session title change payload containing the new display title", "title": "TitleChangedData" }, "TitleChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.title_changed", "description": "Type discriminator. Always \"session.title_changed\"." }, "data": { "$ref": "#/definitions/TitleChangedData", "description": "Session title change payload containing the new display title" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.title_changed\". Session title change payload containing the new display title", "title": "TitleChangedEvent" }, "TodosChangedData": { "type": "object", "properties": {}, "additionalProperties": false, "description": "Signal-only event: the agent's todos or todo_deps table was written to. No payload — clients should call session.plan.readSqlTodosWithDependencies() to fetch the current state. Events arrive in order; clients can debounce on arrival if needed.", "title": "TodosChangedData" }, "TodosChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.todos_changed", "description": "Type discriminator. Always \"session.todos_changed\"." }, "data": { "$ref": "#/definitions/TodosChangedData", "description": "Signal-only event: the agent's todos or todo_deps table was written to. No payload — clients should call session.plan.readSqlTodosWithDependencies() to fetch the current state. Events arrive in order; clients can debounce on arrival if needed." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.todos_changed\". Signal-only event: the agent's todos or todo_deps table was written to. No payload — clients should call session.plan.readSqlTodosWithDependencies() to fetch the current state. Events arrive in order; clients can debounce on arrival if needed.", "title": "TodosChangedEvent" }, "ToolExecutionCompleteContent": { "anyOf": [ { "$ref": "#/definitions/ToolExecutionCompleteContentText", "description": "Plain text content block" }, { "$ref": "#/definitions/ToolExecutionCompleteContentTerminal", "description": "Deprecated for shell command exit metadata. Use ToolExecutionCompleteContentShellExit instead." }, { "$ref": "#/definitions/ToolExecutionCompleteContentShellExit", "description": "Shell command exit metadata with optional output preview" }, { "$ref": "#/definitions/ToolExecutionCompleteContentImage", "description": "Image content block with base64-encoded data" }, { "$ref": "#/definitions/ToolExecutionCompleteContentAudio", "description": "Audio content block with base64-encoded data" }, { "$ref": "#/definitions/ToolExecutionCompleteContentResourceLink", "description": "Resource link content block referencing an external resource" }, { "$ref": "#/definitions/ToolExecutionCompleteContentResource", "description": "Embedded resource content block with inline text or binary data" } ], "description": "A content block within a tool result, which may be text, terminal output, image, audio, or a resource", "title": "ToolExecutionCompleteContent" }, "ToolExecutionCompleteContentAudio": { "type": "object", "properties": { "type": { "type": "string", "const": "audio", "description": "Content block type discriminator" }, "data": { "type": "string", "description": "Base64-encoded audio data", "contentEncoding": "base64" }, "mimeType": { "type": "string", "description": "MIME type of the audio (e.g., audio/wav, audio/mpeg)" } }, "required": [ "type", "data", "mimeType" ], "additionalProperties": false, "description": "Audio content block with base64-encoded data", "title": "ToolExecutionCompleteContentAudio" }, "ToolExecutionCompleteContentImage": { "type": "object", "properties": { "type": { "type": "string", "const": "image", "description": "Content block type discriminator" }, "data": { "type": "string", "description": "Base64-encoded image data", "contentEncoding": "base64" }, "mimeType": { "type": "string", "description": "MIME type of the image (e.g., image/png, image/jpeg)" } }, "required": [ "type", "data", "mimeType" ], "additionalProperties": false, "description": "Image content block with base64-encoded data", "title": "ToolExecutionCompleteContentImage" }, "ToolExecutionCompleteContentResource": { "type": "object", "properties": { "type": { "type": "string", "const": "resource", "description": "Content block type discriminator" }, "resource": { "$ref": "#/definitions/ToolExecutionCompleteContentResourceDetails", "description": "The embedded resource contents, either text or base64-encoded binary" } }, "required": [ "type", "resource" ], "additionalProperties": false, "description": "Embedded resource content block with inline text or binary data", "title": "ToolExecutionCompleteContentResource" }, "ToolExecutionCompleteContentResourceDetails": { "anyOf": [ { "$ref": "#/definitions/EmbeddedTextResourceContents", "description": "Embedded text resource contents identified by a URI, with an optional MIME type and a text payload." }, { "$ref": "#/definitions/EmbeddedBlobResourceContents", "description": "Embedded binary resource contents identified by a URI, with an optional MIME type and a base64-encoded blob." } ], "description": "The embedded resource contents, either text or base64-encoded binary", "title": "ToolExecutionCompleteContentResourceDetails" }, "ToolExecutionCompleteContentResourceLink": { "type": "object", "properties": { "icons": { "type": "array", "items": { "$ref": "#/definitions/ToolExecutionCompleteContentResourceLinkIcon", "description": "Icon image for a resource" }, "description": "Icons associated with this resource" }, "name": { "type": "string", "description": "Resource name identifier" }, "title": { "type": "string", "description": "Human-readable display title for the resource" }, "uri": { "type": "string", "description": "URI identifying the resource" }, "description": { "type": "string", "description": "Human-readable description of the resource" }, "mimeType": { "type": "string", "description": "MIME type of the resource content" }, "size": { "type": "integer", "minimum": 0, "description": "Size of the resource in bytes" }, "type": { "type": "string", "const": "resource_link", "description": "Content block type discriminator" } }, "required": [ "name", "uri", "type" ], "additionalProperties": false, "description": "Resource link content block referencing an external resource", "title": "ToolExecutionCompleteContentResourceLink" }, "ToolExecutionCompleteContentResourceLinkIcon": { "type": "object", "properties": { "src": { "type": "string", "description": "URL or path to the icon image" }, "mimeType": { "type": "string", "description": "MIME type of the icon image" }, "sizes": { "type": "array", "items": { "type": "string" }, "description": "Available icon sizes (e.g., ['16x16', '32x32'])" }, "theme": { "$ref": "#/definitions/ToolExecutionCompleteContentResourceLinkIconTheme", "description": "Theme variant this icon is intended for" } }, "required": [ "src" ], "additionalProperties": false, "description": "Icon image for a resource", "title": "ToolExecutionCompleteContentResourceLinkIcon" }, "ToolExecutionCompleteContentResourceLinkIconTheme": { "type": "string", "enum": [ "light", "dark" ], "description": "Theme variant this icon is intended for", "title": "ToolExecutionCompleteContentResourceLinkIconTheme", "x-enumDescriptions": { "light": "Icon intended for light themes.", "dark": "Icon intended for dark themes." } }, "ToolExecutionCompleteContentShellExit": { "type": "object", "properties": { "type": { "type": "string", "const": "shell_exit", "description": "Content block type discriminator" }, "shellId": { "type": "string", "description": "Shell id, as assigned by Copilot runtime" }, "exitCode": { "type": "integer", "description": "Exit code from the completed shell command" }, "cwd": { "type": "string", "description": "Working directory where the shell command was executed" }, "outputPreview": { "type": "string", "description": "Output associated with this shell command, if available. May be partial, truncated, or a preview; not guaranteed to be full output." }, "outputTruncated": { "type": "boolean", "description": "Whether outputPreview is known to be incomplete or truncated" } }, "required": [ "type", "shellId", "exitCode" ], "additionalProperties": false, "description": "Shell command exit metadata with optional output preview", "title": "ToolExecutionCompleteContentShellExit" }, "ToolExecutionCompleteContentTerminal": { "type": "object", "properties": { "type": { "type": "string", "const": "terminal", "description": "Content block type discriminator" }, "text": { "type": "string", "description": "Terminal/shell output text" }, "exitCode": { "type": "integer", "description": "Process exit code, if the command has completed" }, "cwd": { "type": "string", "description": "Working directory where the command was executed" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "Deprecated for shell command exit metadata. Use ToolExecutionCompleteContentShellExit instead.", "title": "ToolExecutionCompleteContentTerminal", "deprecated": true }, "ToolExecutionCompleteContentText": { "type": "object", "properties": { "type": { "type": "string", "const": "text", "description": "Content block type discriminator" }, "text": { "type": "string", "description": "The text content" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "Plain text content block", "title": "ToolExecutionCompleteContentText" }, "ToolExecutionCompleteData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Unique identifier for the completed tool call" }, "success": { "type": "boolean", "description": "Whether the tool execution completed successfully" }, "model": { "type": "string", "description": "Model identifier that generated this tool call" }, "mcpMeta": { "description": "FIDES IFC label projected from tool ingress metadata (MCP `CallToolResult._meta` or synthesized built-in ingress labels). Persisted as `{ ifc: ... }` so the label survives session resume, including model-visible failure results. Experimental.", "x-opaque-json": true, "stability": "experimental" }, "interactionId": { "type": "string", "description": "CAPI interaction ID for correlating this tool execution with upstream telemetry" }, "rte": { "type": "boolean" }, "isUserRequested": { "type": "boolean", "description": "Whether this tool call was explicitly requested by the user rather than the assistant" }, "result": { "$ref": "#/definitions/ToolExecutionCompleteResult", "description": "Tool execution result on success" }, "error": { "$ref": "#/definitions/ToolExecutionCompleteError", "description": "Error details when the tool execution failed" }, "toolTelemetry": { "type": "object", "additionalProperties": { "x-opaque-json": true }, "description": "Tool-specific telemetry data (e.g., CodeQL check counts, grep match counts)" }, "turnId": { "type": "string", "description": "Identifier for the agent loop turn this tool was invoked in, matching the corresponding assistant.turn_start event" }, "toolDescription": { "$ref": "#/definitions/ToolExecutionCompleteToolDescription", "description": "Tool definition metadata, present for MCP tools with MCP Apps support" }, "sandboxed": { "type": "boolean", "description": "Whether this tool execution ran inside a sandbox container" }, "parentToolCallId": { "type": "string", "description": "Tool call ID of the parent tool invocation when this event originates from a sub-agent", "deprecated": true } }, "required": [ "toolCallId", "success" ], "additionalProperties": false, "description": "Tool execution completion results including success status, detailed output, and error information", "title": "ToolExecutionCompleteData" }, "ToolExecutionCompleteError": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" } }, "required": [ "message" ], "additionalProperties": false, "description": "Error details when the tool execution failed", "title": "ToolExecutionCompleteError" }, "ToolExecutionCompleteEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "tool.execution_complete", "description": "Type discriminator. Always \"tool.execution_complete\"." }, "data": { "$ref": "#/definitions/ToolExecutionCompleteData", "description": "Tool execution completion results including success status, detailed output, and error information" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"tool.execution_complete\". Tool execution completion results including success status, detailed output, and error information", "title": "ToolExecutionCompleteEvent" }, "ToolExecutionCompleteResult": { "type": "object", "properties": { "content": { "type": "string", "description": "Concise tool result text sent to the LLM for chat completion, potentially truncated for token efficiency" }, "detailedContent": { "type": "string", "description": "Full detailed tool result for UI/timeline display, preserving complete content such as diffs. Falls back to content when absent." }, "contents": { "type": "array", "items": { "$ref": "#/definitions/ToolExecutionCompleteContent", "description": "A content block within a tool result, which may be text, terminal output, image, audio, or a resource" }, "description": "Structured content blocks (text, images, audio, resources) returned by the tool in their native format" }, "binaryResultsForLlm": { "type": "array", "items": { "$ref": "#/definitions/PersistedBinaryResult", "description": "A model-facing binary result as persisted: full inline data, a size-omitted marker, or a deduplicated asset reference" }, "description": "Model-facing binary results (base64 inline or size-omitted markers) sent to the LLM for this tool call", "stability": "experimental" }, "uiResource": { "$ref": "#/definitions/ToolExecutionCompleteUIResource", "description": "MCP Apps UI resource content for rendering in a sandboxed iframe" }, "structuredContent": { "description": "Structured content (arbitrary JSON) returned verbatim by the MCP tool", "x-opaque-json": true }, "citableSources": { "type": "array", "items": { "$ref": "#/definitions/CitableSource", "description": "A source supplied by a tool that should be made available to the model as citable content." }, "description": "Provider-neutral source material this tool makes available to the model as citable content. Persisted so it survives session resume. Experimental.", "stability": "experimental" }, "mcpMeta": { "description": "FIDES IFC label projected from tool ingress metadata (MCP `CallToolResult._meta` or synthesized built-in ingress labels) — persisted as `{ ifc: ... }` (only the `ifc` key, not the whole `_meta`). Persisted so the FIDES IFC label survives session resume: the engine rehydrates accumulated taint by replaying these on load. Populated for ingress sources when FIDES IFC is on. Experimental.", "x-opaque-json": true, "stability": "experimental" } }, "required": [ "content" ], "additionalProperties": false, "description": "Tool execution result on success", "title": "ToolExecutionCompleteResult" }, "ToolExecutionCompleteToolDescription": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name" }, "description": { "type": "string", "description": "Tool description" }, "_meta": { "$ref": "#/definitions/ToolExecutionCompleteToolDescriptionMeta", "description": "MCP Apps metadata for UI resource association" } }, "required": [ "name" ], "additionalProperties": false, "description": "Tool definition metadata, present for MCP tools with MCP Apps support", "title": "ToolExecutionCompleteToolDescription" }, "ToolExecutionCompleteToolDescriptionMeta": { "type": "object", "properties": { "ui": { "$ref": "#/definitions/ToolExecutionCompleteToolDescriptionMetaUI", "description": "MCP Apps tool `_meta.ui` resource URI and visibility captured on `tool.execution_complete`." } }, "additionalProperties": false, "description": "MCP Apps metadata for UI resource association", "title": "ToolExecutionCompleteToolDescriptionMeta" }, "ToolExecutionCompleteToolDescriptionMetaUI": { "type": "object", "properties": { "resourceUri": { "type": "string", "description": "URI of the UI resource" }, "visibility": { "type": "array", "items": { "$ref": "#/definitions/ToolExecutionCompleteToolDescriptionMetaUIVisibility" }, "description": "Who can access this tool" } }, "additionalProperties": false, "description": "MCP Apps tool `_meta.ui` resource URI and visibility captured on `tool.execution_complete`.", "title": "ToolExecutionCompleteToolDescriptionMetaUI" }, "ToolExecutionCompleteToolDescriptionMetaUIVisibility": { "type": "string", "enum": [ "model", "app" ], "description": "Allowed values for the `ToolExecutionCompleteToolDescriptionMetaUIVisibility` enumeration.", "title": "ToolExecutionCompleteToolDescriptionMetaUIVisibility", "x-enumDescriptions": { "model": "Tool is callable by the model (LLM tool surface)", "app": "Tool is callable by the MCP App view (iframe) via session.mcp.apps.callTool" } }, "ToolExecutionCompleteUIResource": { "type": "object", "properties": { "uri": { "type": "string", "description": "The ui:// URI of the resource" }, "mimeType": { "type": "string", "description": "MIME type of the content" }, "text": { "type": "string", "description": "HTML content as a string" }, "blob": { "type": "string", "description": "Base64-encoded HTML content" }, "_meta": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMeta", "description": "Resource-level UI metadata (CSP, permissions, visual preferences)" } }, "required": [ "uri", "mimeType" ], "additionalProperties": false, "description": "MCP Apps UI resource content for rendering in a sandboxed iframe", "title": "ToolExecutionCompleteUIResource" }, "ToolExecutionCompleteUIResourceMeta": { "type": "object", "properties": { "ui": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUI", "description": "MCP Apps UI resource metadata for a completed tool result, including CSP, permissions, domain, and border preference." } }, "additionalProperties": false, "description": "Resource-level UI metadata (CSP, permissions, visual preferences)", "title": "ToolExecutionCompleteUIResourceMeta" }, "ToolExecutionCompleteUIResourceMetaUI": { "type": "object", "properties": { "csp": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUICsp", "description": "CSP domain allowlists for an MCP Apps UI resource, including connect, resource, frame, and base URI domains." }, "permissions": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissions", "description": "Browser permission metadata for an MCP Apps UI resource, including camera, microphone, geolocation, and clipboard-write." }, "domain": { "type": "string" }, "prefersBorder": { "type": "boolean" } }, "additionalProperties": false, "description": "MCP Apps UI resource metadata for a completed tool result, including CSP, permissions, domain, and border preference.", "title": "ToolExecutionCompleteUIResourceMetaUI" }, "ToolExecutionCompleteUIResourceMetaUICsp": { "type": "object", "properties": { "connectDomains": { "type": "array", "items": { "type": "string" } }, "resourceDomains": { "type": "array", "items": { "type": "string" } }, "frameDomains": { "type": "array", "items": { "type": "string" } }, "baseUriDomains": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "CSP domain allowlists for an MCP Apps UI resource, including connect, resource, frame, and base URI domains.", "title": "ToolExecutionCompleteUIResourceMetaUICsp" }, "ToolExecutionCompleteUIResourceMetaUIPermissions": { "type": "object", "properties": { "camera": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsCamera", "description": "Marker object for camera permission on an MCP Apps UI resource." }, "microphone": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone", "description": "Marker object for microphone permission on an MCP Apps UI resource." }, "geolocation": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation", "description": "Marker object for geolocation permission on an MCP Apps UI resource." }, "clipboardWrite": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite", "description": "Marker object for clipboard-write permission on an MCP Apps UI resource." } }, "additionalProperties": false, "description": "Browser permission metadata for an MCP Apps UI resource, including camera, microphone, geolocation, and clipboard-write.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissions" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsCamera": { "type": "object", "properties": {}, "description": "Marker object for camera permission on an MCP Apps UI resource.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissionsCamera" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite": { "type": "object", "properties": {}, "description": "Marker object for clipboard-write permission on an MCP Apps UI resource.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation": { "type": "object", "properties": {}, "description": "Marker object for geolocation permission on an MCP Apps UI resource.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone": { "type": "object", "properties": {}, "description": "Marker object for microphone permission on an MCP Apps UI resource.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone" }, "ToolExecutionPartialData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Tool call ID this partial result belongs to" }, "partialOutput": { "type": "string", "description": "Incremental output chunk from the running tool" } }, "required": [ "toolCallId", "partialOutput" ], "additionalProperties": false, "description": "Streaming tool execution output for incremental result display", "title": "ToolExecutionPartialData" }, "ToolExecutionPartialResultEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "tool.execution_partial_result", "description": "Type discriminator. Always \"tool.execution_partial_result\"." }, "data": { "$ref": "#/definitions/ToolExecutionPartialData", "description": "Streaming tool execution output for incremental result display" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"tool.execution_partial_result\". Streaming tool execution output for incremental result display", "title": "ToolExecutionPartialResultEvent" }, "ToolExecutionProgressData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Tool call ID this progress notification belongs to" }, "progressMessage": { "type": "string", "description": "Human-readable progress status message (e.g., from an MCP server)" } }, "required": [ "toolCallId", "progressMessage" ], "additionalProperties": false, "description": "Tool execution progress notification with status message", "title": "ToolExecutionProgressData" }, "ToolExecutionProgressEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "tool.execution_progress", "description": "Type discriminator. Always \"tool.execution_progress\"." }, "data": { "$ref": "#/definitions/ToolExecutionProgressData", "description": "Tool execution progress notification with status message" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"tool.execution_progress\". Tool execution progress notification with status message", "title": "ToolExecutionProgressEvent" }, "ToolExecutionStartData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Unique identifier for this tool call" }, "toolName": { "type": "string", "description": "Name of the tool being executed" }, "arguments": { "description": "Arguments passed to the tool", "x-opaque-json": true }, "shellToolInfo": { "$ref": "#/definitions/ToolExecutionStartShellToolInfo", "description": "Shell-tool path hints derived from the command at start time for shell tools (bash/powershell/local_shell). Produced by the same shell-aware extractor as PermissionRequestShell.possiblePaths, so it is present even when the command is auto-approved and no permission request fires. Absent for non-shell tools." }, "model": { "type": "string", "description": "Model identifier that generated this tool call" }, "rte": { "type": "boolean" }, "mcpServerName": { "type": "string", "description": "Name of the MCP server hosting this tool, when the tool is an MCP tool" }, "mcpToolName": { "type": "string", "description": "Original tool name on the MCP server, when the tool is an MCP tool" }, "turnId": { "type": "string", "description": "Identifier for the agent loop turn this tool was invoked in, matching the corresponding assistant.turn_start event" }, "displayVerbatim": { "type": "boolean", "description": "When true, the tool output should be displayed expanded (verbatim) in the CLI timeline" }, "toolDescription": { "$ref": "#/definitions/ToolExecutionStartToolDescription", "description": "Tool definition metadata, present for MCP tools with MCP Apps support" }, "parentToolCallId": { "type": "string", "description": "Tool call ID of the parent tool invocation when this event originates from a sub-agent", "deprecated": true } }, "required": [ "toolCallId", "toolName" ], "additionalProperties": false, "description": "Tool execution startup details including MCP server information when applicable", "title": "ToolExecutionStartData" }, "ToolExecutionStartEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "tool.execution_start", "description": "Type discriminator. Always \"tool.execution_start\"." }, "data": { "$ref": "#/definitions/ToolExecutionStartData", "description": "Tool execution startup details including MCP server information when applicable" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"tool.execution_start\". Tool execution startup details including MCP server information when applicable", "title": "ToolExecutionStartEvent" }, "ToolExecutionStartShellToolInfo": { "type": "object", "properties": { "possiblePaths": { "type": "array", "items": { "type": "string" }, "description": "File paths the command may read or write, derived from the command at start time. Produced by the same shell-aware extractor as PermissionRequestShell.possiblePaths, so it is present even when the command is auto-approved and no permission request fires." }, "hasWriteFileRedirection": { "type": "boolean", "description": "Whether the command includes a file write redirection (e.g., > or >>)." }, "displayCommand": { "type": "string", "description": "The command with a redundant leading `cd` into the working directory removed, present only when there was one to remove. Computed with the same routine the shell driver applies before spawning, so a surface that renders this shows the text that actually runs. Consumers that display it should keep the original tool arguments available on demand.", "stability": "experimental" } }, "required": [ "possiblePaths", "hasWriteFileRedirection" ], "additionalProperties": false, "description": "Shell-aware path hints for a shell tool's command, captured at start time so consumers can snapshot a file's pre-image before the tool runs.", "title": "ToolExecutionStartShellToolInfo" }, "ToolExecutionStartToolDescription": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name" }, "description": { "type": "string", "description": "Tool description" }, "_meta": { "$ref": "#/definitions/ToolExecutionStartToolDescriptionMeta", "description": "MCP Apps metadata for UI resource association" } }, "required": [ "name" ], "additionalProperties": false, "description": "Tool definition metadata, present for MCP tools with MCP Apps support", "title": "ToolExecutionStartToolDescription" }, "ToolExecutionStartToolDescriptionMeta": { "type": "object", "properties": { "ui": { "$ref": "#/definitions/ToolExecutionStartToolDescriptionMetaUI", "description": "MCP Apps tool `_meta.ui` resource URI and visibility captured on `tool.execution_start`." } }, "additionalProperties": false, "description": "MCP Apps metadata for UI resource association", "title": "ToolExecutionStartToolDescriptionMeta" }, "ToolExecutionStartToolDescriptionMetaUI": { "type": "object", "properties": { "resourceUri": { "type": "string", "description": "URI of the UI resource" }, "visibility": { "type": "array", "items": { "$ref": "#/definitions/ToolExecutionStartToolDescriptionMetaUIVisibility" }, "description": "Who can access this tool" } }, "additionalProperties": false, "description": "MCP Apps tool `_meta.ui` resource URI and visibility captured on `tool.execution_start`.", "title": "ToolExecutionStartToolDescriptionMetaUI" }, "ToolExecutionStartToolDescriptionMetaUIVisibility": { "type": "string", "enum": [ "model", "app" ], "description": "Allowed values for the `ToolExecutionStartToolDescriptionMetaUIVisibility` enumeration.", "title": "ToolExecutionStartToolDescriptionMetaUIVisibility", "x-enumDescriptions": { "model": "Tool is callable by the model (LLM tool surface)", "app": "Tool is callable by the MCP App view (iframe) via session.mcp.apps.callTool" } }, "ToolSearchActivatedData": { "type": "object", "properties": { "strategy": { "type": "string", "description": "Tool-search strategy that activated the definitions." }, "toolNames": { "type": "array", "items": { "type": "string" }, "description": "Names of tool definitions activated by this search invocation." } }, "required": [ "strategy", "toolNames" ], "additionalProperties": false, "description": "Persisted generic client-side tool activations restored when a session resumes.", "title": "ToolSearchActivatedData" }, "ToolSearchActivatedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "tool_search.activated", "description": "Type discriminator. Always \"tool_search.activated\"." }, "data": { "$ref": "#/definitions/ToolSearchActivatedData", "description": "Persisted generic client-side tool activations restored when a session resumes." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"tool_search.activated\". Persisted generic client-side tool activations restored when a session resumes.", "title": "ToolSearchActivatedEvent" }, "ToolsUpdatedData": { "type": "object", "properties": { "model": { "type": "string", "description": "Identifier of the model the resolved tools apply to." } }, "required": [ "model" ], "additionalProperties": false, "description": "Payload of `session.tools_updated` identifying the model whose resolved tools were updated.", "title": "ToolsUpdatedData" }, "ToolsUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.tools_updated", "description": "Type discriminator. Always \"session.tools_updated\"." }, "data": { "$ref": "#/definitions/ToolsUpdatedData", "description": "Payload of `session.tools_updated` identifying the model whose resolved tools were updated." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.tools_updated\". Payload of `session.tools_updated` identifying the model whose resolved tools were updated.", "title": "ToolsUpdatedEvent" }, "ToolUserRequestedData": { "type": "object", "properties": { "toolCallId": { "type": "string", "description": "Unique identifier for this tool call" }, "toolName": { "type": "string", "description": "Name of the tool the user wants to invoke" }, "arguments": { "description": "Arguments for the tool invocation", "x-opaque-json": true } }, "required": [ "toolCallId", "toolName" ], "additionalProperties": false, "description": "User-initiated tool invocation request with tool name and arguments", "title": "ToolUserRequestedData" }, "ToolUserRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "tool.user_requested", "description": "Type discriminator. Always \"tool.user_requested\"." }, "data": { "$ref": "#/definitions/ToolUserRequestedData", "description": "User-initiated tool invocation request with tool name and arguments" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"tool.user_requested\". User-initiated tool invocation request with tool name and arguments", "title": "ToolUserRequestedEvent" }, "TruncationData": { "type": "object", "properties": { "tokenLimit": { "type": "integer", "minimum": 0, "description": "Maximum token count for the model's context window" }, "preTruncationTokensInMessages": { "type": "integer", "minimum": 0, "description": "Total tokens in conversation messages before truncation" }, "preTruncationMessagesLength": { "type": "integer", "minimum": 0, "description": "Number of conversation messages before truncation" }, "postTruncationTokensInMessages": { "type": "integer", "minimum": 0, "description": "Total tokens in conversation messages after truncation" }, "postTruncationMessagesLength": { "type": "integer", "minimum": 0, "description": "Number of conversation messages after truncation" }, "tokensRemovedDuringTruncation": { "type": "integer", "minimum": 0, "description": "Number of tokens removed by truncation" }, "messagesRemovedDuringTruncation": { "type": "integer", "minimum": 0, "description": "Number of messages removed by truncation" }, "performedBy": { "type": "string", "description": "Identifier of the component that performed truncation (e.g., \"BasicTruncator\")" } }, "required": [ "tokenLimit", "preTruncationTokensInMessages", "preTruncationMessagesLength", "postTruncationTokensInMessages", "postTruncationMessagesLength", "tokensRemovedDuringTruncation", "messagesRemovedDuringTruncation", "performedBy" ], "additionalProperties": false, "description": "Conversation truncation statistics including token counts and removed content metrics", "title": "TruncationData" }, "TruncationEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.truncation", "description": "Type discriminator. Always \"session.truncation\"." }, "data": { "$ref": "#/definitions/TruncationData", "description": "Conversation truncation statistics including token counts and removed content metrics" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.truncation\". Conversation truncation statistics including token counts and removed content metrics", "title": "TruncationEvent" }, "UsageCheckpointData": { "type": "object", "properties": { "totalNanoAiu": { "type": "number", "minimum": 0, "description": "Session-wide accumulated nano-AI units cost at checkpoint time" }, "totalPremiumRequests": { "type": "number", "minimum": 0, "description": "Total number of premium API requests used at checkpoint time", "visibility": "internal" }, "modelCacheState": { "type": "array", "items": { "$ref": "#/definitions/UsageCheckpointModelCacheState", "description": "Internal prompt-cache expiration state for one model", "visibility": "internal" }, "description": "Internal per-model prompt-cache state used to restore expiration tracking on resume", "visibility": "internal" } }, "required": [ "totalNanoAiu" ], "additionalProperties": false, "description": "Durable session usage checkpoint for reconstructing aggregate accounting on resume", "title": "UsageCheckpointData" }, "UsageCheckpointEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.usage_checkpoint", "description": "Type discriminator. Always \"session.usage_checkpoint\"." }, "data": { "$ref": "#/definitions/UsageCheckpointData", "description": "Durable session usage checkpoint for reconstructing aggregate accounting on resume" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.usage_checkpoint\". Durable session usage checkpoint for reconstructing aggregate accounting on resume", "title": "UsageCheckpointEvent" }, "UsageCheckpointModelCacheState": { "type": "object", "properties": { "modelId": { "type": "string", "description": "Model identifier associated with this cache state" }, "cacheExpiresAt": { "type": "string", "format": "date-time", "description": "Latest known prompt-cache expiration" }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "description": "Retained cache lifetime in seconds, used to refresh expiration after a cache read", "visibility": "internal" } }, "required": [ "modelId", "cacheExpiresAt", "cacheTtlSeconds" ], "additionalProperties": false, "description": "Internal prompt-cache expiration state for one model", "title": "UsageCheckpointModelCacheState", "visibility": "internal" }, "UsageInfoData": { "type": "object", "properties": { "tokenLimit": { "type": "integer", "minimum": 0, "description": "Maximum token count for the model's context window" }, "currentTokens": { "type": "integer", "minimum": 0, "description": "Current number of tokens in the context window" }, "messagesLength": { "type": "integer", "minimum": 0, "description": "Current number of messages in the conversation" }, "systemTokens": { "type": "integer", "minimum": 0, "description": "Token count from system message(s)" }, "conversationTokens": { "type": "integer", "minimum": 0, "description": "Token count from non-system messages (user, assistant, tool)" }, "toolDefinitionsTokens": { "type": "integer", "minimum": 0, "description": "Token count from tool definitions" }, "isInitial": { "type": "boolean", "description": "Whether this is the first usage_info event emitted in this session" } }, "required": [ "tokenLimit", "currentTokens", "messagesLength" ], "additionalProperties": false, "description": "Current context window usage statistics including token and message counts", "title": "UsageInfoData" }, "UsageInfoEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.usage_info", "description": "Type discriminator. Always \"session.usage_info\"." }, "data": { "$ref": "#/definitions/UsageInfoData", "description": "Current context window usage statistics including token and message counts" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.usage_info\". Current context window usage statistics including token and message counts", "title": "UsageInfoEvent" }, "UserInputCompletedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Request ID of the resolved user input request; clients should dismiss any UI for this request" }, "answer": { "type": "string", "description": "The user's answer to the input request" }, "wasFreeform": { "type": "boolean", "description": "Whether the answer was typed as free-form text rather than selected from choices" } }, "required": [ "requestId" ], "additionalProperties": false, "description": "User input request completion with the user's response", "title": "UserInputCompletedData" }, "UserInputCompletedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "user_input.completed", "description": "Type discriminator. Always \"user_input.completed\"." }, "data": { "$ref": "#/definitions/UserInputCompletedData", "description": "User input request completion with the user's response" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"user_input.completed\". User input request completion with the user's response", "title": "UserInputCompletedEvent" }, "UserInputRequestedData": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for this input request; used to respond via session.respondToUserInput()" }, "question": { "type": "string", "description": "The question or prompt to present to the user" }, "choices": { "type": "array", "items": { "type": "string" }, "description": "Predefined choices for the user to select from, if applicable" }, "allowFreeform": { "type": "boolean", "description": "Whether the user can provide a free-form text response in addition to predefined choices" }, "toolCallId": { "type": "string", "description": "The LLM-assigned tool call ID that triggered this request; used by remote UIs to correlate responses" } }, "required": [ "requestId", "question" ], "additionalProperties": false, "description": "User input request notification with question and optional predefined choices", "title": "UserInputRequestedData" }, "UserInputRequestedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "const": true, "description": "Always true for events that are transient and not persisted to the session event log on disk." }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "user_input.requested", "description": "Type discriminator. Always \"user_input.requested\"." }, "data": { "$ref": "#/definitions/UserInputRequestedData", "description": "User input request notification with question and optional predefined choices" } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"user_input.requested\". User input request notification with question and optional predefined choices", "title": "UserInputRequestedEvent" }, "UserMessageAgentMode": { "type": "string", "enum": [ "interactive", "plan", "autopilot", "shell" ], "description": "The agent mode that was active when this message was sent", "title": "UserMessageAgentMode", "x-enumDescriptions": { "interactive": "The agent is responding interactively to the user.", "plan": "The agent is preparing a plan before making changes.", "autopilot": "The agent is working autonomously toward task completion.", "shell": "The agent is in shell-focused UI mode." } }, "UserMessageData": { "type": "object", "properties": { "content": { "type": "string", "description": "The user's message text as displayed in the timeline" }, "transformedContent": { "type": "string", "description": "Transformed version of the message sent to the model, with XML wrapping, timestamps, and other augmentations for prompt caching" }, "attachments": { "type": "array", "items": { "$ref": "#/definitions/Attachment", "description": "A user message attachment — a file, directory, code selection, blob, GitHub reference, GitHub-anchored pointer, or extension-supplied context payload" }, "description": "Files, selections, or GitHub references attached to the message" }, "supportedNativeDocumentMimeTypes": { "type": "array", "items": { "type": "string" }, "description": "Normalized document MIME types that were sent natively instead of through tagged_files XML" }, "nativeDocumentPathFallbackPaths": { "type": "array", "items": { "type": "string" }, "description": "Path-backed native document attachments that stayed on the tagged_files path flow because native upload could not read them or would exceed the request size limit" }, "source": { "type": "string", "description": "Origin of this message, used for timeline filtering and attribution (e.g., `skill-pdf` for hidden skill injection or `agent-` for an inter-agent prompt)" }, "delivery": { "$ref": "#/definitions/UserMessageDelivery", "description": "How this message was delivered to the agentic loop relative to loop state (idle-start vs. steering/queued while busy). The timing axis; combine with `source` (origin) for the full picture. Used for telemetry attribution." }, "agentMode": { "$ref": "#/definitions/UserMessageAgentMode", "description": "The agent mode that was active when this message was sent" }, "isAutopilotContinuation": { "type": "boolean", "description": "True when this user message was auto-injected by autopilot's continuation loop rather than typed by the user; used to distinguish autopilot-driven turns in telemetry." }, "interactionId": { "type": "string", "description": "CAPI interaction ID for correlating this user message with its turn" }, "parentAgentTaskId": { "type": "string", "description": "Parent agent task ID for background telemetry correlated to this user turn" } }, "required": [ "content" ], "additionalProperties": false, "description": "Payload of `user.message` with displayed and model-transformed content, attachments, source/delivery metadata, mode, and telemetry IDs.", "title": "UserMessageData" }, "UserMessageDelivery": { "type": "string", "enum": [ "idle", "steering", "queued" ], "description": "How this user message was delivered to the agentic loop, relative to whether the loop was already running. This is the timing axis only; the message's origin (human vs. system/command/schedule/skill/etc.) is carried separately by `source`. A system-injected message has a delivery too — e.g. a background-task notification waking an idle agent is `idle`, the same mechanism as a human starting a fresh turn.", "title": "UserMessageDelivery", "x-enumDescriptions": { "idle": "Delivered while the loop was idle; starts its own run immediately (a human's fresh turn, or a system notification waking an idle agent).", "steering": "Injected into the current in-flight run while the agent was busy (immediate mode).", "queued": "Enqueued while the agent was busy; processed as its own run afterward." } }, "UserMessageEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "user.message", "description": "Type discriminator. Always \"user.message\"." }, "data": { "$ref": "#/definitions/UserMessageData", "description": "Payload of `user.message` with displayed and model-transformed content, attachments, source/delivery metadata, mode, and telemetry IDs." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"user.message\". Payload of `user.message` with displayed and model-transformed content, attachments, source/delivery metadata, mode, and telemetry IDs.", "title": "UserMessageEvent" }, "UserToolSessionApproval": { "anyOf": [ { "$ref": "#/definitions/UserToolSessionApprovalCommands", "description": "Session-scoped tool-approval rule for specific shell command identifiers." }, { "$ref": "#/definitions/UserToolSessionApprovalRead", "description": "Session-scoped tool-approval rule for read-only filesystem operations." }, { "$ref": "#/definitions/UserToolSessionApprovalWrite", "description": "Session-scoped tool-approval rule for filesystem write operations." }, { "$ref": "#/definitions/UserToolSessionApprovalMcp", "description": "Session-scoped tool-approval rule for an MCP server tool, or all tools on the server when `toolName` is null." }, { "$ref": "#/definitions/UserToolSessionApprovalMemory", "description": "Session-scoped tool-approval rule for writes to long-term memory." }, { "$ref": "#/definitions/UserToolSessionApprovalCustomTool", "description": "Session-scoped tool-approval rule for a custom tool, keyed by tool name." }, { "$ref": "#/definitions/UserToolSessionApprovalExtensionManagement", "description": "Session-scoped tool-approval rule for extension-management operations, optionally narrowed by operation." }, { "$ref": "#/definitions/UserToolSessionApprovalFactory", "description": "Session-scoped factory approval, optionally narrowed by approval key." }, { "$ref": "#/definitions/UserToolSessionApprovalExtensionPermissionAccess", "description": "Session-scoped tool-approval rule for an extension's permission-gated capability access, keyed by extension name." } ], "description": "The approval to add as a session-scoped rule", "title": "UserToolSessionApproval" }, "UserToolSessionApprovalCommands": { "type": "object", "properties": { "kind": { "type": "string", "const": "commands", "description": "Command approval kind" }, "commandIdentifiers": { "type": "array", "items": { "type": "string" }, "description": "Command identifiers approved by the user" } }, "required": [ "kind", "commandIdentifiers" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for specific shell command identifiers.", "title": "UserToolSessionApprovalCommands" }, "UserToolSessionApprovalCustomTool": { "type": "object", "properties": { "kind": { "type": "string", "const": "custom-tool", "description": "Custom tool approval kind" }, "toolName": { "type": "string", "description": "Custom tool name" } }, "required": [ "kind", "toolName" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for a custom tool, keyed by tool name.", "title": "UserToolSessionApprovalCustomTool" }, "UserToolSessionApprovalExtensionManagement": { "type": "object", "properties": { "kind": { "type": "string", "const": "extension-management", "description": "Extension management approval kind" }, "operation": { "type": "string", "description": "Optional operation identifier" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for extension-management operations, optionally narrowed by operation.", "title": "UserToolSessionApprovalExtensionManagement" }, "UserToolSessionApprovalExtensionPermissionAccess": { "type": "object", "properties": { "kind": { "type": "string", "const": "extension-permission-access", "description": "Extension permission access approval kind" }, "extensionName": { "type": "string", "description": "Extension name" } }, "required": [ "kind", "extensionName" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for an extension's permission-gated capability access, keyed by extension name.", "title": "UserToolSessionApprovalExtensionPermissionAccess" }, "UserToolSessionApprovalFactory": { "type": "object", "properties": { "kind": { "type": "string", "const": "factory", "description": "Factory approval kind" }, "approvalKey": { "type": "string", "description": "Optional factory operation name or canonical approval key" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Session-scoped factory approval, optionally narrowed by approval key.", "title": "UserToolSessionApprovalFactory" }, "UserToolSessionApprovalMcp": { "type": "object", "properties": { "kind": { "type": "string", "const": "mcp", "description": "MCP tool approval kind" }, "serverName": { "type": "string", "description": "MCP server name" }, "toolName": { "type": [ "string", "null" ], "description": "Optional MCP tool name, or null for all tools on the server" } }, "required": [ "kind", "serverName", "toolName" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for an MCP server tool, or all tools on the server when `toolName` is null.", "title": "UserToolSessionApprovalMcp" }, "UserToolSessionApprovalMemory": { "type": "object", "properties": { "kind": { "type": "string", "const": "memory", "description": "Memory approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for writes to long-term memory.", "title": "UserToolSessionApprovalMemory" }, "UserToolSessionApprovalRead": { "type": "object", "properties": { "kind": { "type": "string", "const": "read", "description": "Read approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for read-only filesystem operations.", "title": "UserToolSessionApprovalRead" }, "UserToolSessionApprovalWrite": { "type": "object", "properties": { "kind": { "type": "string", "const": "write", "description": "Write approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Session-scoped tool-approval rule for filesystem write operations.", "title": "UserToolSessionApprovalWrite" }, "Verbosity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Output verbosity level used for supported model calls (e.g. \"low\", \"medium\", \"high\")", "title": "Verbosity", "x-enumDescriptions": { "low": "A terse response was requested.", "medium": "A medium amount of response detail was requested.", "high": "A more detailed response was requested." } }, "WarningData": { "type": "object", "properties": { "warningType": { "type": "string", "description": "Category of warning (e.g., \"subscription\", \"policy\", \"mcp\")" }, "message": { "type": "string", "description": "Human-readable warning message for display in the timeline" }, "url": { "type": "string", "description": "Optional URL associated with this warning that the user can open in a browser" } }, "required": [ "warningType", "message" ], "additionalProperties": false, "description": "Warning message for timeline display with categorization", "title": "WarningData" }, "WarningEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.warning", "description": "Type discriminator. Always \"session.warning\"." }, "data": { "$ref": "#/definitions/WarningData", "description": "Warning message for timeline display with categorization" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.warning\". Warning message for timeline display with categorization", "title": "WarningEvent" }, "WorkingDirectoryContext": { "type": "object", "properties": { "cwd": { "type": "string", "description": "Current working directory path" }, "gitRoot": { "type": "string", "description": "Root directory of the git repository, resolved via git rev-parse" }, "repository": { "type": "string", "description": "Repository identifier derived from the git remote URL (\"owner/name\" for GitHub, \"org/project/repo\" for Azure DevOps)" }, "hostType": { "$ref": "#/definitions/WorkingDirectoryContextHostType", "description": "Hosting platform type of the repository (github or ado)" }, "repositoryHost": { "type": "string", "description": "Raw host string from the git remote URL (e.g. \"github.com\", \"mycompany.ghe.com\", \"dev.azure.com\")" }, "branch": { "type": "string", "description": "Current git branch name" }, "headCommit": { "type": "string", "description": "Head commit of current git branch at session start time" }, "baseCommit": { "type": "string", "description": "Base commit of current git branch at session start time" }, "pendingGitContext": { "type": "boolean", "description": "Set on the immediate preliminary event of a working-directory change, before the git context is resolved. A settled follow-up event (enriched with git context, or cwd-only for a non-repository) is always emitted afterward, so observers may defer to it. Absent on standalone/final events (e.g. relay context changes)." } }, "required": [ "cwd" ], "additionalProperties": false, "description": "Working directory and git context at session start", "title": "WorkingDirectoryContext" }, "WorkingDirectoryContextHostType": { "type": "string", "enum": [ "github", "ado" ], "description": "Hosting platform type of the repository (github or ado)", "title": "WorkingDirectoryContextHostType", "x-enumDescriptions": { "github": "Repository is hosted on GitHub.", "ado": "Repository is hosted on Azure DevOps." } }, "WorkspaceFileChangedData": { "type": "object", "properties": { "path": { "type": "string", "description": "Relative path within the session workspace files directory" }, "operation": { "$ref": "#/definitions/WorkspaceFileChangedOperation", "description": "Whether the file was newly created or updated" } }, "required": [ "path", "operation" ], "additionalProperties": false, "description": "Workspace file change details including path and operation type", "title": "WorkspaceFileChangedData" }, "WorkspaceFileChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique event identifier (UUID v4), generated when the event is emitted" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the event was created" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event." }, "ephemeral": { "type": "boolean", "description": "When true, the event is transient and not persisted to the session event log on disk" }, "agentId": { "type": "string", "description": "Sub-agent instance identifier. Absent for events from the root/main agent and session-level events." }, "type": { "type": "string", "const": "session.workspace_file_changed", "description": "Type discriminator. Always \"session.workspace_file_changed\"." }, "data": { "$ref": "#/definitions/WorkspaceFileChangedData", "description": "Workspace file change details including path and operation type" } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.workspace_file_changed\". Workspace file change details including path and operation type", "title": "WorkspaceFileChangedEvent" }, "WorkspaceFileChangedOperation": { "type": "string", "enum": [ "create", "update" ], "description": "Whether the file was newly created or updated", "title": "WorkspaceFileChangedOperation", "x-enumDescriptions": { "create": "The workspace file was created.", "update": "The workspace file was updated." } } }, "$schema": "http://json-schema.org/draft-07/schema#", "description": "JSON Schema for session events emitted by the Copilot CLI runtime." }