options.go

package config

import (
	"log/slog"
	"time"

	"github.com/ethpandaops/claude-agent-sdk-go/internal/elicitation"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/hook"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/mcp"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/message"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/permission"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/prompt"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/sandbox"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/turncomplete"
	"github.com/ethpandaops/claude-agent-sdk-go/internal/userinput"
)

// Effort controls thinking depth.
type Effort string

const (
	// EffortLow uses minimal thinking.
	EffortLow Effort = "low"
	// EffortMedium uses moderate thinking.
	EffortMedium Effort = "medium"
	// EffortHigh uses deep thinking.
	EffortHigh Effort = "high"
	// EffortMax uses maximum thinking depth.
	EffortMax Effort = "max"
)

// ThinkingConfig controls extended thinking behavior.
// Implementations: ThinkingConfigAdaptive, ThinkingConfigEnabled, ThinkingConfigDisabled.
type ThinkingConfig interface {
	thinkingConfig() // marker method
}

// ThinkingConfigAdaptive enables adaptive thinking mode.
type ThinkingConfigAdaptive struct{}

func (ThinkingConfigAdaptive) thinkingConfig() {}

// ThinkingConfigEnabled enables thinking with a specific token budget.
type ThinkingConfigEnabled struct {
	BudgetTokens int
}

func (ThinkingConfigEnabled) thinkingConfig() {}

// ThinkingConfigDisabled disables extended thinking.
type ThinkingConfigDisabled struct{}

func (ThinkingConfigDisabled) thinkingConfig() {}

// InterruptToolResultPolicy controls whether Client.Interrupt synthesizes
// missing tool_result blocks before sending the interrupt control request.
type InterruptToolResultPolicy string

const (
	// InterruptToolResultPolicyNone sends a plain interrupt and leaves any
	// pending tool_use reconciliation to the host or the resumed session.
	InterruptToolResultPolicyNone InterruptToolResultPolicy = "none"
	// InterruptToolResultPolicySynthesizeErrorToolResults synthesizes error
	// tool_result blocks for unresolved tool_use IDs before interrupting.
	InterruptToolResultPolicySynthesizeErrorToolResults InterruptToolResultPolicy = "synthesize_error_tool_results"
)

// SessionCostTracker is the narrow tracker interface used by the SDK runtime.
type SessionCostTracker interface {
	Observe(message.Message)
	ObserveResult(*message.ResultMessage)
	LoadSessionCost(sessionID, claudeHome string) error
	SaveSessionCost(sessionID, claudeHome string) error
	CostSummary() turncomplete.CostSummary
}

// SessionFastModeTracker is the narrow tracker interface used by the SDK runtime.
type SessionFastModeTracker interface {
	Observe(message.Message)
}

// Options configures the behavior of the Claude agent.
type Options struct {
	// Logger is the slog logger for debug output.
	// If nil, logging is disabled (silent operation).
	Logger *slog.Logger

	// SystemPrompt is the system message to send to Claude.
	// Use this for a simple string system prompt.
	SystemPrompt string

	// SystemPromptPreset specifies a preset system prompt configuration.
	// If set, this takes precedence over SystemPrompt and SystemPromptFile.
	SystemPromptPreset *SystemPromptPreset

	// SystemPromptFile is the path to a file containing the system prompt.
	// Precedence: SystemPromptPreset > SystemPromptFile > SystemPrompt.
	SystemPromptFile string

	// Model specifies which Claude model to use (e.g., "claude-sonnet-4-6")
	Model string

	// PermissionMode controls how permissions are handled.
	// Valid values: "acceptEdits", "bypassPermissions", "default", "dontAsk", "plan".
	PermissionMode string

	// MaxTurns limits the maximum number of conversation turns
	MaxTurns int

	// Cwd sets the working directory for the CLI process
	Cwd string

	// ClaudeHome overrides the Claude home directory (default: ~/.claude).
	ClaudeHome string

	// CliPath is the explicit path to the claude CLI binary
	// If empty, the CLI will be searched in PATH
	CliPath string

	// Env provides additional environment variables for the CLI process
	Env map[string]string

	// Hooks configures event hooks for tool interception
	Hooks map[hook.Event][]*hook.Matcher

	// Thinking controls extended thinking behavior.
	Thinking ThinkingConfig

	// Effort controls thinking depth.
	// If nil, no effort flag is passed to the CLI.
	Effort *Effort

	// FastMode explicitly opts the SDK into fast mode for headless sessions.
	// If nil, the SDK does not override fast mode settings.
	FastMode *bool

	// UnattendedRetry opts the CLI into its long-lived unattended retry mode.
	// If nil, the SDK does not override the CLI default.
	UnattendedRetry *bool

	// MaxToolUseConcurrency overrides the CLI tool-use concurrency limit.
	// If nil, the CLI default is used.
	MaxToolUseConcurrency *int

	// AutoCompactPercentageOverride overrides the CLI auto-compaction percentage threshold.
	// If nil, the CLI default is used.
	AutoCompactPercentageOverride *int

	// BlockingLimitOverride overrides the CLI blocking-limit token threshold.
	// If nil, the CLI default is used.
	BlockingLimitOverride *int

	// DisableCompact disables compaction requests in the CLI.
	// If nil, the CLI default is used.
	DisableCompact *bool

	// DisableAutoCompact disables automatic compaction in the CLI.
	// If nil, the CLI default is used.
	DisableAutoCompact *bool

	// CostTracker observes terminal results and can persist session cost state.
	// If nil, result-cost persistence is disabled.
	CostTracker SessionCostTracker

	// FastModeTracker observes init/result/rate-limit/retry messages and derives
	// host-facing fast-mode transitions.
	FastModeTracker SessionFastModeTracker

	// IncludePartialMessages enables streaming of partial message updates.
	IncludePartialMessages bool

	// MaxBudgetUSD sets a cost limit for the session in USD.
	// If nil, no budget limit is imposed.
	MaxBudgetUSD *float64

	// TaskBudget sets the total task budget (token count) for the session.
	// If nil, no task budget limit is imposed.
	TaskBudget *int

	// MCPServers configures external MCP servers to connect to.
	// Map key is the server name, value is the server configuration.
	// Use this for programmatic configuration.
	MCPServers map[string]mcp.ServerConfig

	// MCPConfig is a path to an MCP config file or a raw JSON string.
	// If set, this takes precedence over MCPServers.
	// Use this for file-based configuration or pre-formatted JSON.
	MCPConfig string

	// CanUseTool is called before each tool use for permission checking.
	// If nil, all tool uses are allowed.
	CanUseTool permission.Callback

	// InterruptToolResultPolicy controls whether Client.Interrupt mutates
	// conversation state by synthesizing unresolved tool_result blocks.
	InterruptToolResultPolicy InterruptToolResultPolicy

	// PermissionPersistencePath stores SDK-managed permission rules on disk and
	// reapplies them across future sessions before CanUseTool is invoked.
	PermissionPersistencePath string

	// OnUserInput handles AskUserQuestion tool prompts.
	// If nil, AskUserQuestion is handled by normal tool permission flow.
	OnUserInput userinput.Callback

	// OnPrompt handles generic prompt request/response dialogs from the CLI.
	OnPrompt prompt.Callback

	// OnElicitation handles MCP elicitation control requests.
	// If nil, elicitation requests are rejected unless a hook handles them.
	OnElicitation elicitation.Callback

	// OnElicitationComplete handles completion notifications for previous elicitation requests.
	OnElicitationComplete elicitation.CompleteCallback

	// OnTurnComplete handles one high-level callback after each terminal result.
	OnTurnComplete turncomplete.Callback

	// SandboxSettings configures CLI sandbox behavior.
	// If nil, sandbox is not enabled.
	SandboxSettings *sandbox.Settings

	// ===== NEW FIELDS FOR 1:1 PARITY =====

	// Tools specifies which tools are available. Accepts one of:
	// - ToolsList: Array of tool names (e.g., ToolsList{"Read", "Glob", "Grep"})
	// - *ToolsPreset: Preset configuration (e.g., &ToolsPreset{Type: "preset", Preset: "claude_code"})
	// If nil, all default tools are available.
	// Can be combined with AllowedTools/DisallowedTools for fine-grained control.
	Tools ToolsConfig

	// AllowedTools is a list of pre-approved tools that can be used without prompting.
	// These tools will skip permission confirmation dialogs.
	AllowedTools []string

	// DisallowedTools is a list of tools that are explicitly blocked.
	DisallowedTools []string

	// FallbackModel specifies a model to use if the primary model fails.
	FallbackModel string

	// Betas is a list of beta features to enable.
	Betas []Beta

	// PermissionPromptToolName specifies the tool name to use for permission prompts.
	PermissionPromptToolName string

	// Settings is the path to a settings file to load.
	Settings string

	// AddDirs is a list of additional directories to make accessible.
	AddDirs []string

	// ExtraArgs provides arbitrary CLI flags to pass to the CLI.
	// If the value is nil, the flag is passed without a value (boolean flag).
	ExtraArgs map[string]*string

	// MaxBufferSize sets the maximum bytes for CLI stdout buffering.
	// If nil, uses default buffering.
	MaxBufferSize *int

	// Stderr is a callback function for handling stderr output.
	Stderr func(string)

	// User is a user identifier for tracking purposes.
	User string

	// ContinueConversation indicates whether to continue an existing conversation.
	ContinueConversation bool

	// Resume is a session ID to resume from.
	Resume string

	// SessionID specifies an explicit session ID for this session.
	SessionID string

	// ForkSession indicates whether to fork the resumed session to a new ID.
	ForkSession bool

	// Agents defines custom agent configurations.
	// Map key is the agent name.
	Agents map[string]*AgentDefinition

	// SettingSources specifies which setting sources to use.
	SettingSources []SettingSource

	// Plugins is a list of plugin configurations to load.
	Plugins []*PluginConfig

	// OutputFormat specifies a JSON schema for structured output.
	// Accepts either the wrapped format {"type": "json_schema", "schema": {...}}
	// or a raw JSON schema {"type": "object", "properties": {...}} which is
	// auto-detected and used directly.
	OutputFormat map[string]any

	// EnableFileCheckpointing enables file change tracking and rewinding.
	EnableFileCheckpointing bool

	// InitializeTimeout is the timeout for the initialize control request.
	// If nil, defaults to 60 seconds. Can also be set via CLAUDE_CODE_STREAM_CLOSE_TIMEOUT env var.
	InitializeTimeout *time.Duration

	// PromptSuggestions enables prompt_suggestion messages after each turn.
	PromptSuggestions bool

	// AgentProgressSummaries enables background post-turn summary messages.
	AgentProgressSummaries bool

	// Transport allows injecting a custom transport implementation.
	// If nil, the default CLITransport is created automatically.
	// This field is not serialized to JSON.
	Transport Transport `json:"-"`
}