package copilot

import (

"bytes"

"context"

"encoding/json"

"errors"

"time"

"github.com/github/copilot-sdk/go/rpc"

)

// connectionState is the internal client connection state.

type connectionState string

const (

stateDisconnected connectionState = "disconnected"

stateConnecting connectionState = "connecting"

stateConnected connectionState = "connected"

stateError connectionState = "error"

)

// RuntimeConnection describes how a [Client] connects to the Copilot runtime.

//

// Construct one with a [StdioConnection], [TCPConnection], [URIConnection], or

// [InProcessConnection] literal and pass it via [ClientOptions.Connection]. When

// [ClientOptions.Connection] is nil, COPILOT_SDK_DEFAULT_CONNECTION may select

// "inprocess" or "stdio"; when unset, the default is an empty [StdioConnection].

type RuntimeConnection interface {

runtimeConnection()

}

// childProcessConnection is implemented by the connection types that spawn a

// runtime child process ([StdioConnection] and [TCPConnection]). It exposes the

// per-connection environment so the client can resolve and validate it uniformly

// regardless of the specific child-process transport.

type childProcessConnection interface {

RuntimeConnection

connEnv() []string

}

// StdioConnection spawns a runtime child process and communicates over its

// stdin/stdout pipes. This is the default when no connection is configured.

type StdioConnection struct {

// Path is the runtime executable. When empty, the bundled runtime is used.

Path string

// Args are extra command-line arguments inserted before SDK-managed args.

Args []string

// Env are the environment variables for the runtime process, each of the

// form "KEY=VALUE". When set, these take precedence over

// [ClientOptions.Env]; setting both is rejected. When nil, the client-level

// env (or the current process environment) is used.

Env []string

}

func (StdioConnection) runtimeConnection() {}

func (c StdioConnection) connEnv() []string { return c.Env }

// TCPConnection spawns a runtime child process that listens on a TCP socket

// and connects to it.

type TCPConnection struct {

// Port is the TCP port the runtime listens on. 0 (the default) lets the

// runtime pick a free port; the chosen port is then available via

// [Client.RuntimePort] after [Client.Start] returns.

Port int

// ConnectionToken is an optional shared secret sent in the `connect`

// handshake. When empty, a UUID is generated automatically so the

// loopback listener is safe by default.

ConnectionToken string

// Path is the runtime executable. When empty, the bundled runtime is used.

Path string

// Args are extra command-line arguments inserted before SDK-managed args.

Args []string

// Env are the environment variables for the runtime process, each of the

// form "KEY=VALUE". When set, these take precedence over

// [ClientOptions.Env]; setting both is rejected. When nil, the client-level

// env (or the current process environment) is used.

Env []string

}

func (TCPConnection) runtimeConnection() {}

func (c TCPConnection) connEnv() []string { return c.Env }

// URIConnection connects to an already-running runtime at the given URL.

// The SDK does not spawn a process in this mode.

type URIConnection struct {

// URL of the runtime. Accepts "port", "host:port", or a full URL such

// as "http://host:port".

URL string

// ConnectionToken authenticates the connection; must match what the

// remote runtime expects.

ConnectionToken string

}

func (URIConnection) runtimeConnection() {}

// InProcessConnection hosts the Copilot runtime in-process by loading its native

// runtime library (a Rust cdylib) and driving JSON-RPC over the library's C ABI,

// instead of spawning a runtime child process.

//

// Because the runtime is loaded into the calling process, per-client

// environment, working directory, and telemetry cannot be represented and are

// rejected by [NewClient] (see [ClientOptions]). Set those via the host process

// environment instead, or use a child-process transport ([StdioConnection] /

// [TCPConnection]).

//

// Experimental: the in-process transport is experimental and its API and

// behavior may change in a future release. Build the application with the

// copilot_inprocess build tag to enable this transport.

type InProcessConnection struct {

// RunOnUiThread schedules the supplied native action exactly once on the UI

// thread (the process main thread on macOS), returning only after it completes.

// The action can block while native UI is open. No authentication data crosses

// this callback. Other in-process clients may share this process-wide capability.

//

// Required for OneAuth interactive authentication on macOS. This general-purpose

// scheduler may also be used for other runtime-owned native UI operations.

// Temporary OneAuth workaround; this API may be removed if no longer needed.

// See https://github.com/github/copilot-agent-runtime/issues/27032.

// Experimental.

RunOnUiThread func(action func() error) error

}

func (InProcessConnection) runtimeConnection() {}

// ClientOptions configures the [Client].

type ClientOptions struct {

// Connection describes how to connect to the Copilot runtime. When nil,

// COPILOT_SDK_DEFAULT_CONNECTION may select "inprocess" or "stdio";

// when unset, defaults to an empty [StdioConnection].

Connection RuntimeConnection

// WorkingDirectory is the working directory for the runtime process.

// If empty, inherits the current process's working directory.

WorkingDirectory string

// BaseDirectory is the base directory for Copilot data (session state,

// config, etc.). Sets the COPILOT_HOME environment variable on the

// spawned runtime. When empty, the runtime defaults to ~/.copilot.

// This does not affect where the Go SDK extracts the embedded CLI

// binary; use embeddedcli.Config.Dir to control that install/cache

// location.

// Ignored when connecting to an existing runtime via [URIConnection].

BaseDirectory string

// BuiltinPluginDirectories contains absolute paths to trusted plugin

// directories bundled by the host. When non-empty, Start replaces the

// runtime's complete trusted built-in plugin directory set before sessions

// can be created.

BuiltinPluginDirectories []string

// ExtensionLaunchProvider resolves launch profiles for extension entrypoints

// discovered by the runtime. When non-nil, Start registers the provider

// before any sessions can be created.

ExtensionLaunchProvider ExtensionLaunchProvider

// InstallationConfirmationHandler receives connection-global human reviews

// for experimental `installations.confirm` callbacks. It does not enable

// installation capabilities or perform any runtime registration RPC.

InstallationConfirmationHandler InstallationConfirmationHandler

// LogLevel for the runtime. When empty (the default), the runtime

// uses its own default level; the SDK does not pass --log-level.

// Recognized values: "none", "error", "warning", "info", "debug", "all".

LogLevel string

// Env are the environment variables for the runtime process (default:

// inherits from current process). Each entry is of the form "KEY=VALUE".

// If Env contains duplicate keys, only the last value for each key is used.

//

// For child-process transports ([StdioConnection] / [TCPConnection]) the

// per-connection Env, when set, takes precedence over this field; setting

// both is rejected. Env is not supported with [InProcessConnection] (the

// runtime shares this process's single environment block) and is rejected

// by [NewClient].

Env []string

// GitHubToken is the GitHub token to use for authentication.

// When provided, the token is passed to the runtime via environment

// variable. This takes priority over other authentication methods.

GitHubToken string

// UseLoggedInUser controls whether to use the logged-in user for

// authentication. When true, the runtime attempts to use stored OAuth

// tokens or gh CLI auth. When false, only explicit tokens (GitHubToken

// or environment variables) are used.

// Default: true (but defaults to false when GitHubToken is provided).

UseLoggedInUser *bool

// OnListModels is a custom handler for listing available models.

// When provided, [Client.ListModels] calls this handler instead of

// querying the runtime. Useful in BYOK mode to return models available

// from your custom provider.

OnListModels func(ctx context.Context) ([]ModelInfo, error)

// SessionFS configures a custom session filesystem provider.

// When provided, the client registers as the session filesystem provider

// on connection, routing session-scoped file I/O through per-session

// handlers.

SessionFS *SessionFSConfig

// RequestHandler registers a connection-level LLM inference callback. When

// non-nil, the client registers as the inference provider on connect, and

// the runtime routes its model-layer HTTP and WebSocket traffic through

// this handler instead of issuing the calls itself. Works for both CAPI

// and BYOK sessions.

RequestHandler *CopilotRequestHandler

// OnGitHubTelemetry registers a connection-level callback (experimental)

// that receives GitHub telemetry events the runtime forwards for sessions

// opened by this client. When non-nil, every session created or resumed by

// this client opts into telemetry forwarding (enableGitHubTelemetryForwarding).

OnGitHubTelemetry func(notification *rpc.GitHubTelemetryNotification)

// Telemetry configures OpenTelemetry integration for the runtime.

// When non-nil, COPILOT_OTEL_ENABLED=true is set and any populated

// fields are mapped to the corresponding environment variables.

Telemetry *TelemetryConfig

// SessionIdleTimeoutSeconds configures the server-wide session idle

// timeout in seconds. Sessions without activity for this duration are

// automatically cleaned up. Set to 0 or leave unset to disable.

// Ignored when connecting to an existing runtime via [URIConnection].

SessionIdleTimeoutSeconds int

// ClientInfo declares the integrating application's identity, forwarded to the

// runtime on the `server.connect` handshake. Declaring it lets the

// telemetry the runtime emits on this connection be attributed to a

// consistent surface (the application and its Copilot integration) instead of

// the runtime's own build. All fields are optional; leave it nil to keep the

// runtime's default attribution.

ClientInfo *ClientInfo

// Entra configures the host's Entra application for its sessions.

// Required for built-in Entra sign-in and token renewal; other authentication methods remain available.

Entra *rpc.EntraAuthConfig

// Mode controls the default tool surface and feature flags presented to

// sessions created by this client. The zero value ([ModeCopilotCli])

// matches legacy CLI defaults. Set to [ModeEmpty] to opt in to

// multi-tenant safe defaults — see [ClientMode] for details.

//

// When Mode is [ModeEmpty], NewClient requires either BaseDirectory,

// SessionFS, or a [URIConnection] so the runtime has persistent storage

// for session state.

Mode ClientMode

}

// ExtensionLaunchProvider resolves launch profiles for extension entrypoints

// discovered by the runtime.

//

// Experimental: this API may change or be removed.

type ExtensionLaunchProvider = rpc.ExtensionLaunchProviderHandler

// ExtensionLaunchProviderResolveRequest describes a discovered extension

// entrypoint that may need a host-provided launch profile.

type ExtensionLaunchProviderResolveRequest = rpc.ExtensionLaunchProviderResolveRequest

// ExtensionLaunchProviderResolveResult contains the optional host-provided

// launch profile for an extension entrypoint.

type ExtensionLaunchProviderResolveResult = rpc.ExtensionLaunchProviderResolveResult

// ExtensionLaunchProfile describes how the runtime should launch an extension.

type ExtensionLaunchProfile = rpc.ExtensionLaunchProfile

// ClientInfo identifies the integrating application on the `server.connect` handshake.

//

// Declaring it lets the telemetry the runtime emits on the connection be

// attributed to a single, consistent surface instead of the runtime's own

// build. All fields are optional; an empty field is omitted from the handshake.

type ClientInfo struct {

// ApplicationName is the name of the application using the SDK.

ApplicationName string

// ApplicationVersion is the version of the application using the SDK.

ApplicationVersion string

// IntegrationName optionally identifies a specific integration within the

// application, such as an extension or plugin.

IntegrationName string

// IntegrationVersion is the optional version of the named integration.

IntegrationVersion string

}

// toWire maps the public [ClientInfo] onto the generated connect wire shape,

// omitting empty fields. It returns nil when no identity was supplied so the

// caller drops the clientInfo field and keeps the runtime's default attribution.

func (ci *ClientInfo) toWire() *rpc.ConnectClientInfo {

if ci == nil {

return nil

}

wire := &rpc.ConnectClientInfo{}

populated := false

if ci.ApplicationName != "" {

wire.EditorName = &ci.ApplicationName

populated = true

}

if ci.ApplicationVersion != "" {

wire.EditorVersion = &ci.ApplicationVersion

populated = true

}

if ci.IntegrationName != "" {

wire.ExtensionName = &ci.IntegrationName

populated = true

}

if ci.IntegrationVersion != "" {

wire.ExtensionVersion = &ci.IntegrationVersion

populated = true

}

if !populated {

return nil

}

return wire

}

// CloudSessionRepository is GitHub repository metadata associated with a cloud session.

type CloudSessionRepository struct {

Owner string `json:"owner"`

Name string `json:"name"`

Branch string `json:"branch,omitempty"`

}

// CloudSessionOptions configures creation of a remote session in the cloud.

type CloudSessionOptions struct {

Repository *CloudSessionRepository `json:"repository,omitempty"`

}

// TelemetryConfig configures OpenTelemetry integration for the Copilot CLI process.

type TelemetryConfig struct {

// OTLPEndpoint is the OTLP HTTP endpoint URL for trace/metric export.

// Sets OTEL_EXPORTER_OTLP_ENDPOINT.

OTLPEndpoint string

// OTLPProtocol is the OTLP HTTP protocol for all signals.

// Sets OTEL_EXPORTER_OTLP_PROTOCOL.

OTLPProtocol string

// FilePath is the file path for JSON-lines trace output.

// Sets COPILOT_OTEL_FILE_EXPORTER_PATH.

FilePath string

// ExporterType is the exporter backend type: "otlp-http" or "file".

// Sets COPILOT_OTEL_EXPORTER_TYPE.

ExporterType string

// SourceName is the instrumentation scope name.

// Sets COPILOT_OTEL_SOURCE_NAME.

SourceName string

// CaptureContent controls whether to capture message content (prompts, responses).

// Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT.

CaptureContent *bool

}

// Bool returns a pointer to the given bool value.

// Use for option fields such as AutoStart, AutoRestart, or LogOptions.Ephemeral:

//

// AutoStart: Bool(false)

// Ephemeral: Bool(true)

func Bool(v bool) *bool {

return &v

}

// String returns a pointer to the given string value.

// Use for setting optional string parameters in RPC calls.

func String(v string) *string {

return &v

}

// Float64 returns a pointer to the given float64 value.

// Use for setting thresholds: BackgroundCompactionThreshold: Float64(0.80)

func Float64(v float64) *float64 {

return &v

}

// Int returns a pointer to the given int value.

// Use for setting optional int parameters: MinLength: Int(1)

func Int(v int) *int {

return &v

}

// Known system message section identifiers for the "customize" mode.

const (

// SectionPreamble is the agent identity preamble and mode statement.

SectionPreamble = "preamble"

// SectionIdentity is the section group covering the identity preamble and its

// sibling sub-sections (tone, tool efficiency, etc.).

SectionIdentity = "identity"

// SectionTone covers response style, conciseness rules, and output formatting preferences.

SectionTone = "tone"

// SectionToolEfficiency covers tool usage patterns, parallel calling, and batching guidelines.

SectionToolEfficiency = "tool_efficiency"

// SectionEnvironmentContext covers CWD, OS, git root, directory listing, and available tools.

SectionEnvironmentContext = "environment_context"

// SectionCodeChangeRules covers coding rules, linting/testing, ecosystem tools, and style.

SectionCodeChangeRules = "code_change_rules"

// SectionGuidelines covers tips, behavioral best practices, and behavioral guidelines.

SectionGuidelines = "guidelines"

// SectionSafety covers environment limitations, prohibited actions, and security policies.

SectionSafety = "safety"

// SectionToolInstructions covers per-tool usage instructions.

SectionToolInstructions = "tool_instructions"

// SectionCustomInstructions covers repository and organization custom instructions.

SectionCustomInstructions = "custom_instructions"

// SectionRuntimeInstructions targets runtime-provided system-prompt context and

// instructions, such as system notifications, memories, workspace context, and

// content-exclusion policy. Mode-specific instructions can travel in transition

// messages instead.

SectionRuntimeInstructions = "runtime_instructions"

// SectionLastInstructions covers end-of-prompt instructions: parallel tool calling,

// persistence, task completion, and configured subagent-model guidance when the

// task tool is available.

SectionLastInstructions = "last_instructions"

)

// SectionOverrideAction represents the action to perform on a system message section.

type SectionOverrideAction string

const (

// SectionActionReplace replaces section content entirely.

SectionActionReplace SectionOverrideAction = "replace"

// SectionActionRemove removes the section.

SectionActionRemove SectionOverrideAction = "remove"

// SectionActionAppend appends to existing section content.

SectionActionAppend SectionOverrideAction = "append"

// SectionActionPrepend prepends to existing section content.

SectionActionPrepend SectionOverrideAction = "prepend"

// SectionActionPreserve is a no-op marker that opts an individually-addressable

// section out of a group-level "remove" (e.g. keep "tone" when removing the

// "identity" group).

SectionActionPreserve SectionOverrideAction = "preserve"

)

// SectionTransformFn is a callback that receives the current content of a system message section

// and returns the transformed content. Used with the "transform" action to read-then-write

// modify sections at runtime.

type SectionTransformFn func(currentContent string) (string, error)

// SectionOverride defines an override operation for a single system message section.

type SectionOverride struct {

// Action is the operation to perform: "replace", "remove", "append", "prepend", or "transform".

Action SectionOverrideAction `json:"action,omitempty"`

// Content for the override. Optional for all actions. Ignored for "remove".

Content string `json:"content,omitempty"`

// Transform is a callback invoked when Action is "transform".

// The runtime calls this with the current section content and uses the returned string.

// Excluded from JSON serialization; the SDK registers it as an RPC callback internally.

Transform SectionTransformFn `json:"-"`

}

// SystemMessageAppendConfig is append mode: use CLI foundation with optional appended content.

type SystemMessageAppendConfig struct {

// Mode is optional, defaults to "append"

Mode string `json:"mode,omitempty"`

// Content provides additional instructions appended after SDK-managed sections

Content string `json:"content,omitempty"`

}

// SystemMessageReplaceConfig is replace mode: use caller-provided system message entirely.

// Removes all SDK guardrails including security restrictions.

type SystemMessageReplaceConfig struct {

// Mode must be "replace"

Mode string `json:"mode"`

// Content is the complete system message (required)

Content string `json:"content"`

}

// SystemMessageConfig represents system message configuration for session creation.

// - Append mode (default): SDK foundation + optional custom content

// - Replace mode: Full control, caller provides entire system message

// - Customize mode: Section-level overrides with graceful fallback

//

// In Go, use one struct and set fields appropriate for the desired mode.

type SystemMessageConfig struct {

Mode string `json:"mode,omitempty"`

Content string `json:"content,omitempty"`

Sections map[string]SectionOverride `json:"sections,omitempty"`

}

// PermissionHandlerFunc executes a permission request.

// The handler should return a [rpc.PermissionDecision]. Returning an error

// causes the SDK to respond with [rpc.PermissionDecisionUserNotAvailable].

//

// Use the variant types directly:

//

// &rpc.PermissionDecisionApproveOnce{}

// &rpc.PermissionDecisionReject{Feedback: &feedback}

// &rpc.PermissionDecisionUserNotAvailable{}

// &rpc.PermissionDecisionNoResult{} // decline to respond; another client may answer

type PermissionHandlerFunc func(request PermissionRequest, invocation PermissionInvocation) (rpc.PermissionDecision, error)

// PermissionInvocation provides context about a permission request.

//

// This type retains its original two-field shape for source compatibility with

// existing positional composite literals.

type PermissionInvocation struct {

SessionID string

ManagedSettingsEnabled bool

}

// PermissionHandlerWithPromptFunc executes a permission request with the

// optional derived user-facing prompt supplied by newer runtimes.

type PermissionHandlerWithPromptFunc func(request PermissionRequest, invocation PermissionHandlerInvocation) (rpc.PermissionDecision, error)

// PermissionHandlerInvocation provides the complete context for a permission

// request, including the optional derived prompt.

type PermissionHandlerInvocation struct {

PermissionInvocation

// PromptRequest is the derived user-facing prompt supplied by newer runtimes.

// Only commands, read, write, url, and workflow prompts can clear a raw

// managed-approval requirement after Assisted approval. Missing and other

// prompt kinds must remain conservative.

PromptRequest rpc.PermissionPromptRequest

}

// PermissionDecisionContext describes how and where a permission decision was

// reached. Attach it to a decision with [NewAttributedPermissionResult] so the runtime

// can attribute auto-approval telemetry to the responding surface. It is

// informational only and never changes permission behavior.

//

// Experimental: PermissionDecisionContext is part of an experimental API and

// may change or be removed.

type PermissionDecisionContext = rpc.PermissionDecisionContext

// PermissionResponseCapability describes whether the responding client could

// ask a user for a permission decision.

type PermissionResponseCapability = rpc.PermissionResponseCapability

const (

PermissionResponseCapabilityHeadless = rpc.PermissionResponseCapabilityHeadless

PermissionResponseCapabilityInteractive = rpc.PermissionResponseCapabilityInteractive

PermissionResponseCapabilityNone = rpc.PermissionResponseCapabilityNone

)

// PermissionDecisionOutcome describes the disposition of a permission request

// as observed by the responding client.

type PermissionDecisionOutcome = rpc.PermissionDecisionOutcome

const (

PermissionDecisionOutcomeAutoApproved = rpc.PermissionDecisionOutcomeAutoApproved

PermissionDecisionOutcomeAutopilotDenied = rpc.PermissionDecisionOutcomeAutopilotDenied

PermissionDecisionOutcomePromptedUser = rpc.PermissionDecisionOutcomePromptedUser

)

// PermissionDecisionSource identifies the controlled reason or actor

// responsible for a permission response.

type PermissionDecisionSource = rpc.PermissionDecisionSource

const (

PermissionDecisionSourceAssistedApproval = rpc.PermissionDecisionSourceAssistedApproval

PermissionDecisionSourceHostPolicy = rpc.PermissionDecisionSourceHostPolicy

PermissionDecisionSourceHumanResponse = rpc.PermissionDecisionSourceHumanResponse

PermissionDecisionSourceUnattendedFallback = rpc.PermissionDecisionSourceUnattendedFallback

)

// PermissionDecisionSurface identifies the client surface that submitted a

// permission response.

type PermissionDecisionSurface = rpc.PermissionDecisionSurface

const (

PermissionDecisionSurfaceAcp = rpc.PermissionDecisionSurfaceAcp

PermissionDecisionSurfaceCopilotApp = rpc.PermissionDecisionSurfaceCopilotApp

PermissionDecisionSurfacePromptMode = rpc.PermissionDecisionSurfacePromptMode

PermissionDecisionSurfaceSDK = rpc.PermissionDecisionSurfaceSDK

PermissionDecisionSurfaceTui = rpc.PermissionDecisionSurfaceTui

)

// MCPAuthWwwAuthenticateParams contains parsed parameters from an MCP server's WWW-Authenticate response.

type MCPAuthWwwAuthenticateParams struct {

ResourceMetadataURL *string `json:"resourceMetadataUrl,omitempty"`

Scope *string `json:"scope,omitempty"`

Error *string `json:"error,omitempty"`

}

// MCPAuthStaticClientConfig is static OAuth client configuration supplied by an MCP server.

type MCPAuthStaticClientConfig struct {

ClientID string `json:"clientId"`

ClientSecret *string `json:"clientSecret,omitempty"`

GrantType *string `json:"grantType,omitempty"`

PublicClient *bool `json:"publicClient,omitempty"`

Scope *string `json:"scope,omitempty"`

}

// MCPAuthRequest describes an MCP OAuth request that the SDK host can satisfy with a token.

type MCPAuthRequest struct {

RequestID string `json:"requestId"`

ServerName string `json:"serverName"`

ServerURL string `json:"serverUrl"`

Reason MCPOauthRequestReason `json:"reason"`

WwwAuthenticateParams *MCPAuthWwwAuthenticateParams `json:"wwwAuthenticateParams,omitempty"`

ResourceMetadata *string `json:"resourceMetadata,omitempty"`

StaticClientConfig *MCPAuthStaticClientConfig `json:"staticClientConfig,omitempty"`

}

// MCPAuthToken is host-provided OAuth token data for a pending MCP OAuth request.

type MCPAuthToken struct {

AccessToken string `json:"accessToken"`

TokenType *string `json:"tokenType,omitempty"`

ExpiresIn *int64 `json:"expiresIn,omitempty"`

}

// MCPAuthResult is the result returned by an MCP auth request handler.

type MCPAuthResult struct {

Kind string

Token *MCPAuthToken

}

const (

// MCPAuthResultKindToken indicates that the host provided token data.

MCPAuthResultKindToken = "token"

// MCPAuthResultKindCancelled indicates that the host declined the request.

MCPAuthResultKindCancelled = "cancelled"

// MCPAuthResultKindRuntimeRefresh hands an advertised Refresh back to its original runtime operation.

MCPAuthResultKindRuntimeRefresh = "runtimeRefresh"

)

// MCPAuthResultToken returns a token result for an MCP OAuth request.

func MCPAuthResultToken(token *MCPAuthToken) *MCPAuthResult {

return &MCPAuthResult{Kind: MCPAuthResultKindToken, Token: token}

}

// MCPAuthResultCancelled returns a cancelled result for an MCP OAuth request.

func MCPAuthResultCancelled() *MCPAuthResult {

return &MCPAuthResult{Kind: MCPAuthResultKindCancelled}

}

// MCPAuthResultRuntimeRefresh requests noninteractive renewal for an advertised Refresh.

// Response acceptance is not token installation or reconnect completion.

func MCPAuthResultRuntimeRefresh() *MCPAuthResult {

return &MCPAuthResult{Kind: MCPAuthResultKindRuntimeRefresh}

}

// MCPAuthInvocation provides context about an MCP auth handler invocation.

type MCPAuthInvocation struct {

SessionID string

}

// MCPAuthHandler handles MCP OAuth requests from the runtime.

type MCPAuthHandler func(request MCPAuthRequest, invocation MCPAuthInvocation) (*MCPAuthResult, error)

// MCPAuthRuntimeRefreshHandler opts into runtime-owned refresh without changing

// legacy request or invocation literals. runtimeRefreshSupported is false when

// omitted. Return MCPAuthResultRuntimeRefresh only for an advertised Refresh.

// Other requests retain the host's existing token or cancellation policy.

type MCPAuthRuntimeRefreshHandler func(request MCPAuthRequest, invocation MCPAuthInvocation, runtimeRefreshSupported bool) (*MCPAuthResult, error)

// UserInputRequest represents a request for user input from the agent

type UserInputRequest struct {

Question string

Choices []string

AllowFreeform *bool

}

// UserInputResponse represents the user's response to an input request

type UserInputResponse struct {

Answer string

WasFreeform bool

}

// UserInputHandler handles user input requests from the agent

// The handler should return a UserInputResponse. Returning an error fails the request.

type UserInputHandler func(request UserInputRequest, invocation UserInputInvocation) (UserInputResponse, error)

// UserInputInvocation provides context about a user input request

type UserInputInvocation struct {

SessionID string

}

// ExitPlanModeRequest represents a request to exit plan mode and continue with a selected action.

type ExitPlanModeRequest struct {

Summary string `json:"summary"`

PlanContent string `json:"planContent,omitempty"`

Actions []string `json:"actions"`

RecommendedAction string `json:"recommendedAction"`

}

// ExitPlanModeResult is the response to an exit-plan-mode request.

type ExitPlanModeResult struct {

Approved bool `json:"approved"`

SelectedAction string `json:"selectedAction,omitempty"`

Feedback string `json:"feedback,omitempty"`

}

// ExitPlanModeInvocation provides context about an exit-plan-mode request.

type ExitPlanModeInvocation struct {

SessionID string

}

// ExitPlanModeRequestHandler handles exit-plan-mode requests from the agent.

type ExitPlanModeRequestHandler func(request ExitPlanModeRequest, invocation ExitPlanModeInvocation) (ExitPlanModeResult, error)

// AutoModeSwitchRequest represents a request to switch to auto mode after an eligible rate limit.

type AutoModeSwitchRequest struct {

ErrorCode *string `json:"errorCode,omitempty"`

RetryAfterSeconds *float64 `json:"retryAfterSeconds,omitempty"`

}

// AutoModeSwitchInvocation provides context about an auto-mode-switch request.

type AutoModeSwitchInvocation struct {

SessionID string

}

// AutoModeSwitchRequestHandler handles auto-mode-switch requests from the agent.

type AutoModeSwitchRequestHandler func(request AutoModeSwitchRequest, invocation AutoModeSwitchInvocation) (AutoModeSwitchResponse, error)

// PreToolUseHookInput is the input for a pre-tool-use hook

type PreToolUseHookInput struct {

AgentID string `json:"agentId,omitempty"`

AgentType string `json:"agentType,omitempty"`

ParentAgentID string `json:"parentAgentId,omitempty"`

SessionID string `json:"sessionId"`

Timestamp time.Time `json:"-"`

WorkingDirectory string `json:"cwd"`

ToolName string `json:"toolName"`

ToolArgs any `json:"toolArgs"`

}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.

func (h PreToolUseHookInput) MarshalJSON() ([]byte, error) {

type alias PreToolUseHookInput

return json.Marshal(&struct {

Timestamp int64 `json:"timestamp"`

alias

}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})

}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.

func (h *PreToolUseHookInput) UnmarshalJSON(data []byte) error {

type alias PreToolUseHookInput

aux := &struct {

Timestamp int64 `json:"timestamp"`

*alias

}{alias: (*alias)(h)}

if err := json.Unmarshal(data, aux); err != nil {

return err

}

h.Timestamp = time.UnixMilli(aux.Timestamp)

return nil

}

// PreToolUseHookOutput is the output for a pre-tool-use hook

type PreToolUseHookOutput struct {

PermissionDecision string `json:"permissionDecision,omitempty"` // "allow", "deny", "ask"

PermissionDecisionReason string `json:"permissionDecisionReason,omitempty"`

ModifiedArgs any `json:"modifiedArgs,omitempty"`

AdditionalContext string `json:"additionalContext,omitempty"`

SuppressOutput bool `json:"suppressOutput,omitempty"`

}

// PreToolUseHandler handles pre-tool-use hook invocations

type PreToolUseHandler func(input PreToolUseHookInput, invocation HookInvocation) (*PreToolUseHookOutput, error)

// PostToolUseHookInput is the input for a post-tool-use hook

type PostToolUseHookInput struct {

AgentID string `json:"agentId,omitempty"`

AgentType string `json:"agentType,omitempty"`

ParentAgentID string `json:"parentAgentId,omitempty"`

SessionID string `json:"sessionId"`

Timestamp time.Time `json:"-"`

WorkingDirectory string `json:"cwd"`

ToolName string `json:"toolName"`

ToolArgs any `json:"toolArgs"`

ToolResult any `json:"toolResult"`

}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.

func (h PostToolUseHookInput) MarshalJSON() ([]byte, error) {

type alias PostToolUseHookInput

return json.Marshal(&struct {

Timestamp int64 `json:"timestamp"`

alias

}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})

}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.

func (h *PostToolUseHookInput) UnmarshalJSON(data []byte) error {

type alias PostToolUseHookInput

aux := &struct {

Timestamp int64 `json:"timestamp"`

*alias

}{alias: (*alias)(h)}

if err := json.Unmarshal(data, aux); err != nil {

return err

}

h.Timestamp = time.UnixMilli(aux.Timestamp)

return nil

}

// PostToolUseHookOutput is the output for a post-tool-use hook

type PostToolUseHookOutput struct {

ModifiedResult any `json:"modifiedResult,omitempty"`

AdditionalContext string `json:"additionalContext,omitempty"`

SuppressOutput bool `json:"suppressOutput,omitempty"`

}

// PostToolUseHandler handles post-tool-use hook invocations

type PostToolUseHandler func(input PostToolUseHookInput, invocation HookInvocation) (*PostToolUseHookOutput, error)

// PostToolUseFailureHookInput is the input for a post-tool-use-failure hook.

//

// Fires after a tool execution whose result was "failure". The CLI extracts

// the failure message from the tool result and passes it as the Error field

// (rather than passing the full result object).

type PostToolUseFailureHookInput struct {

AgentID string `json:"agentId,omitempty"`

AgentType string `json:"agentType,omitempty"`

ParentAgentID string `json:"parentAgentId,omitempty"`

SessionID string `json:"sessionId"`

Timestamp time.Time `json:"-"`

WorkingDirectory string `json:"cwd"`

ToolName string `json:"toolName"`

ToolArgs any `json:"toolArgs"`

// Error is the failure message from the tool's result.

Error string `json:"error"`

}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.

func (h PostToolUseFailureHookInput) MarshalJSON() ([]byte, error) {

type alias PostToolUseFailureHookInput

return json.Marshal(&struct {

Timestamp int64 `json:"timestamp"`

alias

}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})

}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.

func (h *PostToolUseFailureHookInput) UnmarshalJSON(data []byte) error {

type alias PostToolUseFailureHookInput

aux := &struct {

Timestamp int64 `json:"timestamp"`

*alias

}{alias: (*alias)(h)}

if err := json.Unmarshal(data, aux); err != nil {

return err

}

h.Timestamp = time.UnixMilli(aux.Timestamp)

return nil

}

// PostToolUseFailureHookOutput is the output for a post-tool-use-failure hook.

//

// Only AdditionalContext is consumed by the host CLI — it is appended as

// hidden guidance to the model alongside the failed tool result.

type PostToolUseFailureHookOutput struct {

AdditionalContext string `json:"additionalContext,omitempty"`

}

// PostToolUseFailureHandler handles post-tool-use-failure hook invocations.

type PostToolUseFailureHandler func(input PostToolUseFailureHookInput, invocation HookInvocation) (*PostToolUseFailureHookOutput, error)

// UserPromptSubmittedHookInput is the input for a user-prompt-submitted hook

type UserPromptSubmittedHookInput struct {

AgentID string `json:"agentId,omitempty"`

AgentType string `json:"agentType,omitempty"`

ParentAgentID string `json:"parentAgentId,omitempty"`

SessionID string `json:"sessionId"`

Timestamp time.Time `json:"-"`

WorkingDirectory string `json:"cwd"`

Prompt string `json:"prompt"`

}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.

func (h UserPromptSubmittedHookInput) MarshalJSON() ([]byte, error) {

type alias UserPromptSubmittedHookInput

return json.Marshal(&struct {

Timestamp int64 `json:"timestamp"`

alias

}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})

}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.

func (h *UserPromptSubmittedHookInput) UnmarshalJSON(data []byte) error {

type alias UserPromptSubmittedHookInput

aux := &struct {

Timestamp int64 `json:"timestamp"`

*alias

}{alias: (*alias)(h)}

if err := json.Unmarshal(data, aux); err != nil {

return err

}

h.Timestamp = time.UnixMilli(aux.Timestamp)

return nil

}

// UserPromptSubmittedHookOutput is the output for a user-prompt-submitted hook.

//

// A Decision of "block" refuses the prompt: no model turn runs, no user message

// is recorded, and the session emits an ephemeral session.warning

// (warningType "policy_blocked") carrying Reason. The runtime blocks only when

// a reason is present, and an empty Reason is omitted from the output, so a

// block needs a non-empty Reason.

type UserPromptSubmittedHookOutput struct {

ModifiedPrompt string `json:"modifiedPrompt,omitempty"`

AdditionalContext string `json:"additionalContext,omitempty"`

SuppressOutput bool `json:"suppressOutput,omitempty"`

Decision string `json:"decision,omitempty"`

Reason string `json:"reason,omitempty"`

}

// UserPromptSubmittedHandler handles user-prompt-submitted hook invocations

type UserPromptSubmittedHandler func(input UserPromptSubmittedHookInput, invocation HookInvocation) (*UserPromptSubmittedHookOutput, error)

// UserPromptTransformedHookInput is the input for a user-prompt-transformed hook.

type UserPromptTransformedHookInput struct {

AgentID string `json:"agentId,omitempty"`

AgentType string `json:"agentType,omitempty"`

ParentAgentID string `json:"parentAgentId,omitempty"`

SessionID string `json:"sessionId"`

Timestamp time.Time `json:"-"`

WorkingDirectory string `json:"cwd"`

Prompt string `json:"prompt"`

TransformedPrompt string `json:"transformedPrompt"`

}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.

func (h UserPromptTransformedHookInput) MarshalJSON() ([]byte, error) {

type alias UserPromptTransformedHookInput

return json.Marshal(&struct {

Timestamp int64 `json:"timestamp"`

alias

}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})

}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.

func (h *UserPromptTransformedHookInput) UnmarshalJSON(data []byte) error {

type alias UserPromptTransformedHookInput

aux := &struct {

Timestamp int64 `json:"timestamp"`

*alias

}{alias: (*alias)(h)}

if err := json.Unmarshal(data, aux); err != nil {

return err

}

h.Timestamp = time.UnixMilli(aux.Timestamp)

return nil

}

// UserPromptTransformedHookOutput is the output for a user-prompt-transformed hook.

type UserPromptTransformedHookOutput struct {

ModifiedTransformedPrompt *string `json:"modifiedTransformedPrompt,omitempty"`

}

// UserPromptTransformedHandler handles user-prompt-transformed hook invocations.

type UserPromptTransformedHandler func(input UserPromptTransformedHookInput, invocation HookInvocation) (*UserPromptTransformedHookOutput, error)

// SessionStartHookInput is the input for a session-start hook

type SessionStartHookInput struct {

AgentID string `json:"agentId,omitempty"`

AgentType string `json:"agentType,omitempty"`

ParentAgentID string `json:"parentAgentId,omitempty"`

SessionID string `json:"sessionId"`

Timestamp time.Time `json:"-"`

WorkingDirectory string `json:"cwd"`

Source string `json:"source"` // "startup", "resume", "new"

InitialPrompt string `json:"initialPrompt,omitempty"`

}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.

func (h SessionStartHookInput) MarshalJSON() ([]byte, error) {

type alias SessionStartHookInput

return json.Marshal(&struct {

Timestamp int64 `json:"timestamp"`

alias

}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})

}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.

func (h *SessionStartHookInput) UnmarshalJSON(data []byte) error {

type alias SessionStartHookInput

aux := &struct {

Timestamp int64 `json:"timestamp"`

*alias

}{alias: (*alias)(h)}

if err := json.Unmarshal(data, aux); err != nil {

return err

}

h.Timestamp = time.UnixMilli(aux.Timestamp)

return nil

}

// SessionStartHookOutput is the output for a session-start hook

type SessionStartHookOutput struct {

AdditionalContext string `json:"additionalContext,omitempty"`

ModifiedConfig map[string]any `json:"modifiedConfig,omitempty"`

}

// SessionStartHandler handles session-start hook invocations

type SessionStartHandler func(input SessionStartHookInput, invocation HookInvocation) (*SessionStartHookOutput, error)

// SessionEndHookInput is the input for a session-end hook

type SessionEndHookInput struct {

AgentID string `json:"agentId,omitempty"`

AgentType string `json:"agentType,omitempty"`

ParentAgentID string `json:"parentAgentId,omitempty"`

SessionID string `json:"sessionId"`

Timestamp time.Time `json:"-"`

WorkingDirectory string `json:"cwd"`

Reason string `json:"reason"` // "complete", "error", "abort", "timeout", "user_exit"

FinalMessage string `json:"finalMessage,omitempty"`

Error string `json:"error,omitempty"`

}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.

func (h SessionEndHookInput) MarshalJSON() ([]byte, error) {

type alias SessionEndHookInput

return json.Marshal(&struct {

Timestamp int64 `json:"timestamp"`

alias

}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})

}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds

// and Error from the CLI's error object (see hookErrorText).

func (h *SessionEndHookInput) UnmarshalJSON(data []byte) error {

type alias SessionEndHookInput

aux := &struct {

Timestamp int64 `json:"timestamp"`