{ "$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" ], "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." } }, "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)" }, "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" }, "serviceRequestId": { "type": "string", "description": "Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation" }, "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" } }, "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" }, "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" }, "AssistantTurnEndData": { "type": "object", "properties": { "turnId": { "type": "string", "description": "Identifier of the turn that has ended, matching the corresponding assistant.turn_start event" } }, "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" }, "AssistantTurnStartData": { "type": "object", "properties": { "turnId": { "type": "string", "description": "Identifier for this turn within the agentic loop, typically a stringified turn number" }, "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" }, "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": "integer", "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" }, "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" }, "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", "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\")" }, "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": "Schema for the `AssistantUsageQuotaSnapshot` type.", "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" }, "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": "Schema for the `BackgroundTasksChangedData` type.", "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": "Schema for the `BackgroundTasksChangedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.background_tasks_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": "Schema for the `CanvasClosedData` type.", "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": "Schema for the `CanvasClosedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.closed\".", "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" }, "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": "Schema for the `CanvasOpenedData` type.", "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": "Schema for the `CanvasOpenedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.opened\".", "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." }, "inputSchema": { "description": "JSON Schema for canvas open input", "x-opaque-json": true }, "actions": { "type": "array", "items": { "$ref": "#/definitions/CanvasRegistryChangedCanvasAction" }, "description": "Actions the agent or host may invoke" } }, "required": [ "extensionId", "canvasId", "displayName", "description" ], "additionalProperties": false, "description": "Schema for the `CanvasRegistryChangedCanvas` type.", "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": "Schema for the `CanvasRegistryChangedCanvasAction` type.", "title": "CanvasRegistryChangedCanvasAction", "stability": "experimental" }, "CanvasRegistryChangedData": { "type": "object", "properties": { "canvases": { "type": "array", "items": { "$ref": "#/definitions/CanvasRegistryChangedCanvas" }, "description": "Canvas declarations currently available" } }, "required": [ "canvases" ], "additionalProperties": false, "description": "Schema for the `CanvasRegistryChangedData` type.", "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": "Schema for the `CanvasRegistryChangedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.canvas.registry_changed\".", "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": "Schema for the `CommandsChangedCommand` type.", "title": "CommandsChangedCommand" }, "CommandsChangedData": { "type": "object", "properties": { "commands": { "type": "array", "items": { "$ref": "#/definitions/CommandsChangedCommand" }, "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)." } }, "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": { "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" } }, "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" }, "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" }, "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": "Schema for the `CustomAgentsUpdatedAgent` type.", "title": "CustomAgentsUpdatedAgent" }, "CustomAgentsUpdatedData": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/definitions/CustomAgentsUpdatedAgent" }, "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": "Schema for the `CustomAgentsUpdatedData` type.", "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": "Schema for the `CustomAgentsUpdatedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.custom_agents_updated\".", "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": "Schema for the `ElicitationCompletedContent` type.", "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": "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": "Schema for the `EmbeddedBlobResourceContents` type.", "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": "Schema for the `EmbeddedTextResourceContents` type.", "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": "Schema for the `ExtensionsAttachmentsPushedData` type.", "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": "Schema for the `ExtensionsAttachmentsPushedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.extensions.attachments_pushed\".", "title": "ExtensionsAttachmentsPushedEvent" }, "ExtensionsLoadedData": { "type": "object", "properties": { "extensions": { "type": "array", "items": { "$ref": "#/definitions/ExtensionsLoadedExtension" }, "description": "Array of discovered extensions and their status" } }, "required": [ "extensions" ], "additionalProperties": false, "description": "Schema for the `ExtensionsLoadedData` type.", "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": "Schema for the `ExtensionsLoadedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.extensions_loaded\".", "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": "Schema for the `ExtensionsLoadedExtension` type.", "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" }, "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." } }, "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" }, "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": "Schema for the `McpAppToolCallCompleteToolMetaUI` type." } }, "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": "Schema for the `McpAppToolCallCompleteToolMetaUI` type.", "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." } }, "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." } }, "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" }, "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" }, "McpServersLoadedData": { "type": "object", "properties": { "servers": { "type": "array", "items": { "$ref": "#/definitions/McpServersLoadedServer" }, "description": "Array of MCP server status summaries" } }, "required": [ "servers" ], "additionalProperties": false, "description": "Schema for the `McpServersLoadedData` type.", "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": "Schema for the `McpServersLoadedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.mcp_servers_loaded\".", "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, 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": "Schema for the `McpServersLoadedServer` type.", "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", "not_configured" ], "description": "Connection status: connected, failed, needs-auth, pending, disabled, 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.", "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, or not_configured" }, "error": { "type": "string", "description": "Error message if the server entered a failed state" } }, "required": [ "serverName", "status" ], "additionalProperties": false, "description": "Schema for the `McpServerStatusChangedData` type.", "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": "Schema for the `McpServerStatusChangedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.mcp_server_status_changed\".", "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." } }, "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" }, "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" }, "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", "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" }, "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." } }, "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" }, "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. Currently `\"rate_limit_auto_switch\"` for changes triggered by the auto-mode-switch rate-limit recovery path. 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" }, "PermissionApproved": { "type": "object", "properties": { "kind": { "type": "string", "const": "approved", "description": "The permission request was approved" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Schema for the `PermissionApproved` type.", "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": "Schema for the `PermissionApprovedForLocation` type.", "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": "Schema for the `PermissionApprovedForSession` type.", "title": "PermissionApprovedForSession" }, "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": "Schema for the `PermissionCancelled` type.", "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": "Schema for the `PermissionDeniedByContentExclusionPolicy` type.", "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": "Schema for the `PermissionDeniedByPermissionRequestHook` type.", "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": "Rules that denied the request" } }, "required": [ "kind", "rules" ], "additionalProperties": false, "description": "Schema for the `PermissionDeniedByRules` type.", "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": "Schema for the `PermissionDeniedInteractivelyByUser` type.", "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": "Schema for the `PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser` type.", "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/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" } }, "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 } }, "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" } }, "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" } }, "required": [ "kind", "extensionName", "capabilities" ], "additionalProperties": false, "description": "Extension permission access prompt", "title": "PermissionPromptRequestExtensionPermissionAccess" }, "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" } }, "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 } }, "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)" } }, "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" } }, "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" } }, "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" } }, "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" } }, "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/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" }, "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" }, "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" }, "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" }, "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": "Parsed command identifiers found in the command text" }, "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": "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": "Schema for the `PermissionRequestShellCommand` type.", "title": "PermissionRequestShellCommand" }, "PermissionRequestShellPossibleUrl": { "type": "object", "properties": { "url": { "type": "string", "description": "URL that may be accessed by the command" } }, "required": [ "url" ], "additionalProperties": false, "description": "Schema for the `PermissionRequestShellPossibleUrl` type.", "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" }, "intention": { "type": "string", "description": "Human-readable description of why the URL is being accessed" }, "url": { "type": "string", "description": "URL to be fetched" } }, "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" }, "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" } }, "required": [ "kind", "intention", "fileName", "diff", "canOfferSessionApproval" ], "additionalProperties": false, "description": "File write permission request", "title": "PermissionRequestWrite" }, "PermissionResult": { "anyOf": [ { "$ref": "#/definitions/PermissionApproved" }, { "$ref": "#/definitions/PermissionApprovedForSession" }, { "$ref": "#/definitions/PermissionApprovedForLocation" }, { "$ref": "#/definitions/PermissionCancelled" }, { "$ref": "#/definitions/PermissionDeniedByRules" }, { "$ref": "#/definitions/PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser" }, { "$ref": "#/definitions/PermissionDeniedInteractivelyByUser" }, { "$ref": "#/definitions/PermissionDeniedByContentExclusionPolicy" }, { "$ref": "#/definitions/PermissionDeniedByPermissionRequestHook" } ], "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": "Schema for the `PermissionRule` type.", "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" } }, "required": [ "previousAllowAllPermissions", "allowAllPermissions" ], "additionalProperties": false, "description": "Permissions change details carrying the aggregate allow-all boolean 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 boolean transition." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.permissions_changed\". Permissions change details carrying the aggregate allow-all boolean 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\")" }, "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 attached to a session that the runtime already had running in-memory (for example, an extension joining a session another client was actively driving). False (or omitted) for cold resumes — the runtime had to reconstitute the session from its persisted event log." }, "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 (the default), any such tool calls and permission requests are immediately marked as interrupted on resume." } }, "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)" } }, "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" }, "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 boolean 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/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/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\"." }, { "$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/AssistantIntentEvent", "description": "Session event \"assistant.intent\". Agent intent description for current activity or plan" }, { "$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/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/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/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/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\"." }, { "$ref": "#/definitions/BackgroundTasksChangedEvent", "description": "Session event \"session.background_tasks_changed\"." }, { "$ref": "#/definitions/SkillsLoadedEvent", "description": "Session event \"session.skills_loaded\"." }, { "$ref": "#/definitions/CustomAgentsUpdatedEvent", "description": "Session event \"session.custom_agents_updated\"." }, { "$ref": "#/definitions/McpServersLoadedEvent", "description": "Session event \"session.mcp_servers_loaded\"." }, { "$ref": "#/definitions/McpServerStatusChangedEvent", "description": "Session event \"session.mcp_server_status_changed\"." }, { "$ref": "#/definitions/ExtensionsLoadedEvent", "description": "Session event \"session.extensions_loaded\"." }, { "$ref": "#/definitions/CanvasOpenedEvent", "description": "Session event \"session.canvas.opened\"." }, { "$ref": "#/definitions/CanvasRegistryChangedEvent", "description": "Session event \"session.canvas.registry_changed\"." }, { "$ref": "#/definitions/CanvasClosedEvent", "description": "Session event \"session.canvas.closed\"." }, { "$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\"." }, { "$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": "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 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": "Token count details per type" } }, "required": [ "requests", "usage" ], "additionalProperties": false, "description": "Schema for the `ShutdownModelMetric` type.", "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": "Schema for the `ShutdownModelMetricTokenDetail` type.", "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": "Schema for the `ShutdownTokenDetail` type.", "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" }, "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": "Array of resolved skill metadata" } }, "required": [ "skills" ], "additionalProperties": false, "description": "Schema for the `SkillsLoadedData` type.", "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": "Schema for the `SkillsLoadedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.skills_loaded\".", "title": "SkillsLoadedEvent" }, "SkillsLoadedSkill": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique identifier for the skill" }, "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": "Schema for the `SkillsLoadedSkill` type.", "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\")" }, "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" }, "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" } }, "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" }, "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" }, { "$ref": "#/definitions/SystemNotificationAgentIdle" }, { "$ref": "#/definitions/SystemNotificationNewInboxMessage" }, { "$ref": "#/definitions/SystemNotificationShellCompleted" }, { "$ref": "#/definitions/SystemNotificationShellDetachedCompleted" }, { "$ref": "#/definitions/SystemNotificationInstructionDiscovered" } ], "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": "Schema for the `SystemNotificationAgentCompleted` type.", "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": "Schema for the `SystemNotificationAgentIdle` type.", "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" }, "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": "Schema for the `SystemNotificationInstructionDiscovered` type.", "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": "Schema for the `SystemNotificationNewInboxMessage` type.", "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": "Schema for the `SystemNotificationShellCompleted` type.", "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": "Schema for the `SystemNotificationShellDetachedCompleted` type.", "title": "SystemNotificationShellDetachedCompleted" }, "TaskCompleteData": { "type": "object", "properties": { "summary": { "type": "string", "default": "", "description": "Summary of the completed task, provided by the agent" }, "success": { "type": "boolean", "description": "Whether the tool call succeeded. False when validation failed (e.g., invalid arguments)" } }, "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" }, "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" }, { "$ref": "#/definitions/EmbeddedBlobResourceContents" } ], "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" }, "interactionId": { "type": "string", "description": "CAPI interaction ID for correlating this tool execution with upstream telemetry" }, "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" } }, "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": "Schema for the `ToolExecutionCompleteToolDescriptionMetaUI` type." } }, "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": "Schema for the `ToolExecutionCompleteToolDescriptionMetaUI` type.", "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": "Schema for the `ToolExecutionCompleteUIResourceMetaUI` type." } }, "additionalProperties": false, "description": "Resource-level UI metadata (CSP, permissions, visual preferences)", "title": "ToolExecutionCompleteUIResourceMeta" }, "ToolExecutionCompleteUIResourceMetaUI": { "type": "object", "properties": { "csp": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUICsp", "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUICsp` type." }, "permissions": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissions", "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissions` type." }, "domain": { "type": "string" }, "prefersBorder": { "type": "boolean" } }, "additionalProperties": false, "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUI` type.", "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": "Schema for the `ToolExecutionCompleteUIResourceMetaUICsp` type.", "title": "ToolExecutionCompleteUIResourceMetaUICsp" }, "ToolExecutionCompleteUIResourceMetaUIPermissions": { "type": "object", "properties": { "camera": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsCamera", "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsCamera` type." }, "microphone": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone", "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone` type." }, "geolocation": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation", "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation` type." }, "clipboardWrite": { "$ref": "#/definitions/ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite", "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite` type." } }, "additionalProperties": false, "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissions` type.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissions" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsCamera": { "type": "object", "properties": {}, "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsCamera` type.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissionsCamera" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite": { "type": "object", "properties": {}, "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite` type.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation": { "type": "object", "properties": {}, "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation` type.", "title": "ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation" }, "ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone": { "type": "object", "properties": {}, "description": "Schema for the `ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone` type.", "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" }, "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 >>)." } }, "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": "Schema for the `ToolExecutionStartToolDescriptionMetaUI` type." } }, "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": "Schema for the `ToolExecutionStartToolDescriptionMetaUI` type.", "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" } }, "ToolsUpdatedData": { "type": "object", "properties": { "model": { "type": "string", "description": "Identifier of the model the resolved tools apply to." } }, "required": [ "model" ], "additionalProperties": false, "description": "Schema for the `ToolsUpdatedData` type.", "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": "Schema for the `ToolsUpdatedData` type." } }, "required": [ "id", "timestamp", "parentId", "ephemeral", "type", "data" ], "additionalProperties": false, "description": "Session event \"session.tools_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" } }, "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" }, "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 (e.g., \"skill-pdf\" for skill-injected messages that should be hidden from the user)" }, "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": "Schema for the `UserMessageData` type.", "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": "Schema for the `UserMessageData` type." } }, "required": [ "id", "timestamp", "parentId", "type", "data" ], "additionalProperties": false, "description": "Session event \"user.message\".", "title": "UserMessageEvent" }, "UserToolSessionApproval": { "anyOf": [ { "$ref": "#/definitions/UserToolSessionApprovalCommands" }, { "$ref": "#/definitions/UserToolSessionApprovalRead" }, { "$ref": "#/definitions/UserToolSessionApprovalWrite" }, { "$ref": "#/definitions/UserToolSessionApprovalMcp" }, { "$ref": "#/definitions/UserToolSessionApprovalMemory" }, { "$ref": "#/definitions/UserToolSessionApprovalCustomTool" }, { "$ref": "#/definitions/UserToolSessionApprovalExtensionManagement" }, { "$ref": "#/definitions/UserToolSessionApprovalExtensionPermissionAccess" } ], "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": "Schema for the `UserToolSessionApprovalCommands` type.", "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": "Schema for the `UserToolSessionApprovalCustomTool` type.", "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": "Schema for the `UserToolSessionApprovalExtensionManagement` type.", "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": "Schema for the `UserToolSessionApprovalExtensionPermissionAccess` type.", "title": "UserToolSessionApprovalExtensionPermissionAccess" }, "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": "Schema for the `UserToolSessionApprovalMcp` type.", "title": "UserToolSessionApprovalMcp" }, "UserToolSessionApprovalMemory": { "type": "object", "properties": { "kind": { "type": "string", "const": "memory", "description": "Memory approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Schema for the `UserToolSessionApprovalMemory` type.", "title": "UserToolSessionApprovalMemory" }, "UserToolSessionApprovalRead": { "type": "object", "properties": { "kind": { "type": "string", "const": "read", "description": "Read approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Schema for the `UserToolSessionApprovalRead` type.", "title": "UserToolSessionApprovalRead" }, "UserToolSessionApprovalWrite": { "type": "object", "properties": { "kind": { "type": "string", "const": "write", "description": "Write approval kind" } }, "required": [ "kind" ], "additionalProperties": false, "description": "Schema for the `UserToolSessionApprovalWrite` type.", "title": "UserToolSessionApprovalWrite" }, "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" } }, "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." }