config

type AccessType int

type AgentConfig struct {

	// Profile says how much the loop should compensate for the model.
	//
	// "weak" keeps every mechanism that exists to catch a model getting
	// confused: backtracking away from a bad tool call, the duplicate-call
	// kill switch, the confirm handshake before an edit is applied, scraping
	// tool calls out of prose, fuzzy matching and indentation repair, asking
	// the model to explain itself after an anomaly, and retrying an empty
	// answer. Each of those was written for a model that needed it.
	//
	// "strong", the default, skips all of it. On a model that does not make
	// those mistakes, each mechanism is a tax: a retry that discards good
	// work, a handshake that costs two round trips per edit, a fuzzy match
	// that silently edits the wrong lines.
	//
	// This is the default for models without their own `profile:` — see
	// ModelEntry.Profile and Config.ProfileFor.
	Profile string `yaml:"profile"`

	MaxIterations int `yaml:"max_tool_iterations"`

	AgentFile string `yaml:"agent_file"`

	ProjectInstructions ProjectInstructionsConfig `yaml:"project_instructions"`
}

type AuditConfig struct {
	Enabled       bool   `yaml:"enabled"`
	LogDir        string `yaml:"log_dir"`
	RedactSecrets bool   `yaml:"redact_secrets"`
	RetentionDays int    `yaml:"retention_days"`
}

type BacktrackConfig struct {
	Enabled           bool `yaml:"enabled"`             // Enable backtrack mode (default: true)
	MaxRetries        int  `yaml:"max_retries"`         // Max retries at same history point (default: 5)
	InjectUserMessage bool `yaml:"inject_user_message"` // On limit reached: backtrack + inject user message instead of error-in-history
}

type BatchToolConfig struct {
	Enabled bool `yaml:"enabled"`
}

type Config struct {
	LLM struct {
		BaseURL   string `yaml:"base_url"`
		APIKey    string `yaml:"api_key"`
		APIKeyEnv string `yaml:"api_key_env"`
		Model     string `yaml:"model"`
		// APIBackend picks the wire protocol: "chat_completions" (default),
		// "responses", or "messages" (Claude's API). Some hosted models are
		// served only on one protocol and return an error on the others.
		APIBackend string `yaml:"api_backend"`
		// Headers are extra "Key=Value" request headers sent with every call
		// (supports ${VAR}). Needed by endpoints that demand a routing or
		// session header of their own.
		Headers []string `yaml:"headers"`
		// ReasoningEffort asks a reasoning model for more or less thinking.
		// Values are the provider's (commonly minimal, low, medium, high,
		// xhigh). The "responses" backend sends it as reasoning.effort; the
		// chat-completions backend sends it wherever EffortField points.
		ReasoningEffort string `yaml:"reasoning_effort"`
		// EffortField names which field of a chat-completions request carries
		// the effort: "chat_template_kwargs" (the default: a model whose chat
		// template reads it, which is how the local servers work) or
		// "reasoning_effort" (OpenAI's own top-level field, which hosted
		// gateways such as opencode.ai read). An endpoint that wants one
		// ignores the other without saying so, so a wrong value here means the
		// effort picked with :eN quietly does nothing. The "responses" backend
		// ignores this.
		EffortField string `yaml:"effort_field"`
		// ReasoningSummary asks a reasoning model for readable text describing
		// its thinking. Only the "responses" backend sends it; values are the
		// provider's (auto, concise, detailed), and "off" suppresses it.
		// Empty follows merge_thinking, because thinking that is never
		// requested cannot be merged.
		ReasoningSummary string `yaml:"reasoning_summary"`
		// RequestTimeout bounds one HTTP request to the model, in seconds.
		// A request that exceeds it is retried, so this times the retry count
		// is how long a turn can stall on an endpoint that never answers.
		// Default 600.
		RequestTimeout int     `yaml:"request_timeout"`
		Temperature    float32 `yaml:"temperature"`
		MaxTokens      int     `yaml:"max_output_tokens"`
		Context        int     `yaml:"context"`        // Max context size for display (0 = don't show)
		MergeThinking  bool    `yaml:"merge_thinking"` // Merge reasoning_content into content (default: false, discard thinking)
		Verbose        int     `yaml:"verbose"`        // 0 = off, >0 = show tool output up to N lines
		// GenerationStats asks the endpoint for per-request cost and native
		// token counts after each answer. It is an OpenRouter endpoint
		// (/generation) and returns 404 everywhere else, so it is off by
		// default: leaving it on doubles the HTTP requests per iteration.
		GenerationStats bool   `yaml:"generation_stats"`
		BenchmarkCmd    string `yaml:"benchmark_cmd"` // External command for benchmarks (use {prompt} placeholder)
	} `yaml:"llm"`

	Workspace struct {
		Root                  string   `yaml:"root"`
		Lock                  bool     `yaml:"lock"`             // Refuse to start when another agent is working in this directory (default: false)
		PathSafetyMode        string   `yaml:"path_safety_mode"` // "allow", "block", "warn", "ask_once", "ask_always"
		AllowOutsideWorkspace bool     `yaml:"allow_outside_workspace"`
		AllowedPaths          []string `yaml:"allowed_paths"`
		AllowedReadPaths      []string `yaml:"allowed_read_paths"`
		DeniedPaths           []string `yaml:"denied_paths"`
		// DeniedWritePaths may be read and never written, inside the
		// workspace or an allowed path as well as outside.
		DeniedWritePaths []string `yaml:"denied_write_paths"`
		// ReadOnlyRoot makes the workspace readable only: a file in it is
		// written only where allowed_paths also names it.
		ReadOnlyRoot bool `yaml:"read_only_root"`
	} `yaml:"workspace"`

	Agent AgentConfig `yaml:"agent"`

	Backtrack BacktrackConfig `yaml:"backtrack"`

	Tools ToolsConfig `yaml:"tools"`

	Prompts PromptsConfig `yaml:"prompts"`

	Safety SafetyConfig `yaml:"safety"`

	Diagnostics DiagnosticsConfig `yaml:"diagnostics"`

	Thinkbench ThinkbenchConfig `yaml:"thinkbench"`

	MCP MCPConfig `yaml:"mcp"`

	// ToolGroups defines sets of tools whose schemas and documentation reach the
	// model only when it asks for them. See ToolGroupConfig.
	ToolGroups []ToolGroupConfig `yaml:"tool_groups"`

	UI UIConfig `yaml:"ui"`

	// Updates controls the release check in kvit-coder-ui: at most one
	// GitHub query per interval, a one-line notice when a newer release
	// exists, and the :update command that installs it. The headless agent
	// never checks.
	Updates UpdatesConfig `yaml:"updates"`

	// Models is the optional multi-model catalog (docs/model-selection.md).
	// Order is stable: :m1 is the first entry, :m2 the second. When absent,
	// ModelList synthesizes a one-entry catalog from the llm: block, so old
	// configs behave exactly as before.
	Models []ModelEntry `yaml:"models"`
	// DefaultModel selects the catalog row a fresh session starts on: a
	// 1-based index, id, display name or wire model id (see ResolveModel).
	// Empty means the row matching llm.model, else the first row.
	DefaultModel string `yaml:"default_model"`
	// DefaultEffortValue is the effort fallback after an entry's own
	// `default: true` row and llm.reasoning_effort.
	DefaultEffortValue string `yaml:"default_effort"`
	// contains filtered or unexported fields
}

type DiagnosticsConfig struct {
	// InterrogateOnAnomaly enables interrogation. Default off.
	InterrogateOnAnomaly bool `yaml:"interrogate_on_anomaly"`
	// InterrogateTriggers selects which anomaly triggers fire interrogation. Empty = all.
	// Valid values: duplicate_call, pending_blocked, alternating_loop, fatal, backtrack.
	InterrogateTriggers []string `yaml:"interrogate_triggers"`
	// InterrogateIdenticalThreshold is the consecutive-identical-call count that triggers
	// interrogation. Default 2.
	InterrogateIdenticalThreshold int `yaml:"interrogate_identical_threshold"`
	// InterrogateMaxPerTask hard-caps interrogations per task to avoid interrogation loops.
	// Default 3.
	InterrogateMaxPerTask int `yaml:"interrogate_max_per_task"`
	// InterrogateLogDir is where JSONL episode logs are written. Default
	// "benchmarks/.kvit-coder-benchmark/interrogations".
	InterrogateLogDir string `yaml:"interrogate_log_dir"`
	// InterrogateThenInject is reserved for the later recovery variant; no-op in v1.
	InterrogateThenInject bool `yaml:"interrogate_then_inject"`
}

type EditToolConfig struct {
	Enabled               bool    `yaml:"enabled"`
	Mode                  string  `yaml:"mode"` // "lines" (default), "searchreplace", or "patch"
	MaxFileSizeKB         int     `yaml:"max_file_size_kb"`
	PreviewMode           bool    `yaml:"preview_mode"`            // enables edit.confirm/edit.cancel
	ReadBeforeEditMsgs    int     `yaml:"read_before_edit_msgs"`   // require read within N messages before edit (0 = disabled)
	PendingConfirmRetries int     `yaml:"pending_confirm_retries"` // max retries when LLM ignores confirm/cancel (0 = disabled, default 5)
	FuzzyThreshold        float64 `yaml:"fuzzy_threshold"`         // searchreplace mode: gates ONLY the fuzzy level (0 = fuzzy off). Whitespace-normalization levels still run unless ExactMatchOnly is set.

	// ExactMatchOnly forces searchreplace matching to byte-exact (Level 0) only:
	// no rstrip, no leading/trailing whitespace normalization, no fuzzy fallback.
	// A non-exact search returns a clean no-match instead of being silently
	// re-anchored to a normalized (line-start) position. Default off = today's
	// cascade behavior for all existing configs.
	ExactMatchOnly bool `yaml:"exact_match_only"`

	// ExplicitDelete enables the DeleteLines tool and flips lines-mode empty new_text
	// semantics: with this on, an Edit replace with new_text="" blanks the addressed
	// line(s) (keeps them) instead of deleting, and deletes go through DeleteLines.
	// Default off = today's behavior exactly ("" deletes, no DeleteLines tool).
	ExplicitDelete bool `yaml:"explicit_delete"`
}

type EffortOption struct {
	Value   string `yaml:"value"`
	Label   string `yaml:"label,omitempty"`
	Default bool   `yaml:"default,omitempty"`
}

type GitSafetyConfig struct {
	BlockPush             bool `yaml:"block_push"`
	BlockHardReset        bool `yaml:"block_hard_reset"`
	BlockCheckoutDiscard  bool `yaml:"block_checkout_discard"`
	BlockStashDrop        bool `yaml:"block_stash_drop"`
	BlockCleanForce       bool `yaml:"block_clean_force"`
	WarnBranchForceDelete bool `yaml:"warn_branch_force_delete"`
}

type GlobToolConfig struct {
	Enabled    bool `yaml:"enabled"`
	MaxResults int  `yaml:"max_results"` // Paths returned per call (default: 100); above truncates with a flag
}

type ImagesConfig struct {
	Enabled      bool `yaml:"enabled"`
	MaxSizeMB    int  `yaml:"max_size_mb"`
	MaxDimension int  `yaml:"max_dimension"`
}

type InterpreterConfig struct {
	BlockOneLiners bool     `yaml:"block_one_liners"`
	Allowed        []string `yaml:"allowed"`
}

type LoadOptions struct {
	// SkipSavedModels leaves out the rows in ~/.kvit-coder/models.yaml. The
	// benchmark modes set it, so a run does not depend on the models someone
	// set up on the machine it runs on.
	SkipSavedModels bool

	// SkipSavedTools leaves out ~/.kvit-coder/tools.yaml, for the same
	// reason: web search turned on in kvit-coder-ui would change the tools a
	// benchmark run offers its model.
	SkipSavedTools bool
}

type MCPConfig struct {
	// Enabled is the group toggle. When false (default) no servers are dialed.
	Enabled bool `yaml:"enabled"`
	// StartupTimeout is the per-server connect + tools/list deadline, in seconds
	// (default 20). A server that exceeds it is logged and skipped, never fatal.
	StartupTimeout int `yaml:"startup_timeout"`
	// CallTimeout is the default per-tool-call deadline, in seconds (default 120),
	// overridable per server. MCP calls are exempt from the agent loop's blanket
	// 15s tool timeout and use this deadline instead.
	CallTimeout int `yaml:"call_timeout"`
	// Confirm is the default trust policy for MCP tool calls, overridable per
	// server: "block" | "ask_once" | "ask_always" | "trust" (default "ask_once").
	Confirm string `yaml:"confirm"`
	// SanitizeSchemas flattens/strips JSON Schema constructs ($ref, oneOf, allOf,
	// ...) that some grammar-constrained tool-calling templates reject. Opt-in so
	// faithful schemas are the default.
	SanitizeSchemas bool `yaml:"sanitize_schemas"`
	// Servers lists the configured MCP servers.
	Servers []MCPServerConfig `yaml:"servers"`
}

type MCPServerConfig struct {
	// Name namespaces the server's tools (mcp.<name>.<tool>); must be unique.
	Name string `yaml:"name"`
	// Enabled opts this server in. Zero value false = skipped (opt-in).
	Enabled bool `yaml:"enabled"`
	// Transport selects the wire protocol: "stdio" (default) or "http".
	Transport string `yaml:"transport"`

	// stdio transport
	Command string   `yaml:"command"` // executable to spawn
	Args    []string `yaml:"args"`    // arguments
	Env     []string `yaml:"env"`     // extra "KEY=VALUE" entries appended to inherited env
	// Cwd is the working directory for the stdio subprocess. Empty defaults to
	// the workspace root, so a server that keys off its own working directory
	// (e.g. a codebase indexer) targets the project kvit-coder operates on rather
	// than wherever kvit-coder happened to be launched. A relative path is
	// resolved against the workspace root.
	Cwd string `yaml:"cwd"`

	// http transport
	URL     string   `yaml:"url"`     // streamable-HTTP endpoint
	Headers []string `yaml:"headers"` // extra "Key=Value" request headers (supports ${VAR})

	// CallTimeout optionally overrides MCPConfig.CallTimeout for this server, in seconds.
	CallTimeout int `yaml:"call_timeout"`
	// Confirm optionally overrides MCPConfig.Confirm for this server.
	Confirm string `yaml:"confirm"`
	// Tools optionally filters which of the server's tools are exposed.
	Tools MCPToolFilter `yaml:"tools"`
}

type MCPToolFilter struct {
	Allow []string `yaml:"allow"`
	Deny  []string `yaml:"deny"`
}

type ModelEntry struct {
	ID         string         `yaml:"id"`
	Name       string         `yaml:"name,omitempty"`
	Model      string         `yaml:"model"`
	BaseURL    string         `yaml:"base_url,omitempty"`
	APIBackend string         `yaml:"api_backend,omitempty"`
	APIKey     string         `yaml:"api_key,omitempty"`
	APIKeyEnv  string         `yaml:"api_key_env,omitempty"`
	Context    int            `yaml:"context,omitempty"`
	Efforts    []EffortOption `yaml:"efforts,omitempty"`

	// EffortField names which field of a chat-completions request carries
	// the reasoning effort for this endpoint: "chat_template_kwargs" (the
	// default, for a model whose chat template reads it) or
	// "reasoning_effort" (OpenAI's own top-level field, which hosted
	// gateways read). Empty keeps the `llm:` block's setting. An endpoint
	// that wants one spelling ignores the other silently, so a wrong value
	// means the effort picked with :eN does nothing at all. The "responses"
	// backend ignores this.
	EffortField string `yaml:"effort_field,omitempty"`

	// Profile overrides agent.profile for this entry: "strong" (the default)
	// or "weak". Empty inherits the global agent.profile. A weak entry keeps
	// the compensation machinery (backtracking, the duplicate-call kill
	// switch, the edit confirm handshake, fuzzy matching, anomaly
	// interrogation, prose scraping, empty-answer retries, interpreter
	// one-liner rules); a strong one skips it.
	Profile string `yaml:"profile,omitempty"`

	// Summarizer marks the entry used to generate session titles: a short
	// 3-6 word summary of the first prompt, stored in meta.json. At most
	// one entry may set it; when none does (or the call fails) the title
	// falls back to the first words of the prompt. It never affects model
	// switching — see SummarizerEntry.
	Summarizer bool `yaml:"summarizer,omitempty"`

	// Headers are extra "Key=Value" request headers for this entry only, in
	// the form of llm.headers and with the same ${VAR} expansion. They are
	// sent on top of llm.headers, and one with the same name replaces the
	// llm.headers value. A gateway that wants headers of its own, such as
	// OpenCode's User-Agent and x-opencode-session, can then be described by
	// its rows alone, without changing what every other model sends.
	Headers []string `yaml:"headers,omitempty"`
}

type PDFReadConfig struct {
	// MaxPages caps how many pages one call extracts. Output size usually binds
	// first, since a dense page is 4-5KB against a 24KB cap.
	MaxPages int `yaml:"max_pages"`

	// CacheDir is where the PDF reader keeps its translated code between runs.
	// Empty means ~/.kvit-coder/wasm-cache. Losing it costs about 1.8 seconds
	// on the next turn that reads a PDF, and it is rebuilt automatically.
	CacheDir string `yaml:"cache_dir"`
}

type PermissionResult int

type ProcsToolsConfig struct {
	Enabled bool `yaml:"enabled"`
	// KillOnExit stops everything this session started when the turn is
	// interrupted. On by default: an interrupt that leaves a dev server
	// running is a surprise. Turn it off to keep long-lived services alive
	// across interrupts.
	KillOnExit *bool `yaml:"kill_on_exit"`
}

type ProjectInstructionsConfig struct {
	// Enabled defaults to true when unset, so an existing CLAUDE.md is picked up.
	Enabled *bool `yaml:"enabled"`
	// Path is resolved relative to the directory kvit-coder was launched from.
	// Defaults to "CLAUDE.md".
	Path string `yaml:"path"`
}

type PromptsConfig struct {
	// UseTemplates enables template-based prompt generation (default: false)
	UseTemplates bool `yaml:"use_templates"`
	// TemplatesDir overrides embedded templates with filesystem directory
	TemplatesDir string `yaml:"templates_dir"`
	// HotReload enables template reloading on each request (dev mode)
	HotReload bool `yaml:"hot_reload"`
}

type QuestionToolConfig struct {
	Enabled bool `yaml:"enabled"`
	// Timeout is how long a run with no terminal waits for an answer to appear
	// in the session inbox, in seconds. Zero, the default, falls back at once,
	// so a benchmark or scripted run never hangs on a question. A supervised
	// headless run sets it to a few minutes.
	Timeout int `yaml:"timeout"`
}

type ReadToolConfig struct {
	Enabled         bool          `yaml:"enabled"`
	MaxFileSizeKB   int           `yaml:"max_file_size_kb"`
	MaxReadSizeKB   int           `yaml:"max_read_size_kb"`
	MaxPartialLines int           `yaml:"max_partial_lines"`
	ShowLineNumbers *bool         `yaml:"show_line_numbers"` // nil = default true, for backward compat
	PDF             PDFReadConfig `yaml:"pdf"`
}

type ReportMode string

type ReportToolConfig struct {
	Enabled bool `yaml:"enabled"`
	// Mode is which turns must end with one: off, mutating (the default),
	// tools, or always.
	Mode ReportMode `yaml:"mode"`
	// MaxRepairAttempts bounds how many rejected reports one turn may submit.
	// Zero selects DefaultReportRepairAttempts.
	MaxRepairAttempts int `yaml:"max_repair_attempts"`
	// MaxBlocks bounds the block list. Zero selects the package default of 20.
	MaxBlocks int `yaml:"max_blocks"`
}

type RmSafetyConfig struct {
	AllowInTemp         bool `yaml:"allow_in_temp"`
	AllowInWorkspaceCwd bool `yaml:"allow_in_workspace_cwd"`
	BlockWorkspaceRoot  bool `yaml:"block_workspace_root"`
}

type SafetyConfig struct {
	StrictMode   bool              `yaml:"strict_mode"`   // Fail-closed on parse errors
	ParanoidMode bool              `yaml:"paranoid_mode"` // Aggressive restrictions
	Audit        AuditConfig       `yaml:"audit"`
	Git          GitSafetyConfig   `yaml:"git"`
	Rm           RmSafetyConfig    `yaml:"rm"`
	Interpreters InterpreterConfig `yaml:"interpreters"`
}

type SafetyConfirmation struct {
	ToolName  string    `yaml:"-"`
	Path      string    `yaml:"-"`
	Timestamp time.Time `yaml:"-"`
}

type SearchToolConfig struct {
	Enabled           bool `yaml:"enabled"`
	MaxSnippetResults int  `yaml:"max_snippet_results"` // Show full snippets up to this many (default: 20)
	MaxCompactResults int  `yaml:"max_compact_results"` // Show file:line:char up to this many (default: 100)

}

type ShellToolConfig struct {
	Enabled            bool     `yaml:"enabled"`
	AllowedCommands    []string `yaml:"allowed_commands"`    // allowlist (empty = allow all)
	DisallowedCommands []string `yaml:"disallowed_commands"` // blocklist (checked after allowlist)

	// InjectEnv, when non-empty, replaces the child process environment for shell
	// commands with os.Environ() plus these "KEY=VALUE" entries. Used by the
	// thinkbench harness to point python3/pip at the uv environment without naming
	// an outside path in the command string. Empty = inherit parent env (default).
	InjectEnv []string `yaml:"-"`
	// ExecPrefix, when non-empty, is prepended (as an argv) before "sh -c <command>"
	// when running shell commands. Used by the thinkbench harness to wrap agent
	// commands in an OS sandbox (e.g. bwrap). Empty = run "sh -c" directly (default).
	ExecPrefix []string `yaml:"-"`
	// AllowInterpreters, when true, lifts the default block on interpreter
	// one-liners (python -c, node -e, perl -e, ...). Set by the thinkbench harness,
	// whose tasks are interpreter-driven and sandboxed, and opt-in via benchmark
	// configs (e.g. SWE-bench, which runs in a Docker container and needs python -c
	// to introspect the codebase). Default false (blocked) for normal use.
	AllowInterpreters bool `yaml:"allow_interpreters"`

	// AllowWithoutAsking answers yes to every command that would otherwise
	// stop and ask, except the few that destroy something unrecoverably
	// (dd, mkfs and its family). --yolo sets it. What is refused outright
	// stays refused: this answers questions, and a denial was never one.
	//
	// It matters most with no terminal, where an unanswered question is a
	// refusal rather than a pause: without this, a headless --yolo run fails
	// on the first curl it needs.
	AllowWithoutAsking bool `yaml:"allow_without_asking"`

	// DefaultTimeout is how long a shell command may run when the call does
	// not ask for a timeout, in seconds. Default 120.
	DefaultTimeout int `yaml:"default_timeout"`
	// MaxTimeout caps what a call may ask for, in seconds. Default 600.
	MaxTimeout int `yaml:"max_timeout"`
}

type SubagentToolConfig struct {
	Enabled            bool `yaml:"enabled"`
	MaxChildIterations int  `yaml:"max_child_iterations"`
	TimeoutS           int  `yaml:"timeout_s"`
	ResultMaxChars     int  `yaml:"result_max_chars"`
	MaxConcurrent      int  `yaml:"max_concurrent"`
}

type TerminalTitleConfig struct {
	// Enabled set to false stops the title being written. Unset means on;
	// it is only ever written to a terminal, so there is nothing for a
	// piped run to break.
	Enabled *bool `yaml:"enabled"`
	// Running is the icon shown while a turn is running, Asking the one
	// shown while a prompt is waiting for an answer (a Question, a path or
	// MCP confirmation, the pause prompt), and Waiting the one shown while
	// nothing is running and the composer is open. Unset takes the
	// ui.DefaultTitle*Icon defaults.
	Running *string `yaml:"running"`
	Waiting *string `yaml:"waiting"`
	Asking  *string `yaml:"asking"`
}

type ThinkbenchConfig struct {
	// SuiteDir overrides the auto-discovered suite directory
	// (default: benchmarks/thinkbench/suite, discovered from the repo root).
	SuiteDir string `yaml:"suite_dir"`
	// TimeoutPerRun is the per-task agent-loop timeout in seconds (default: 600).
	TimeoutPerRun int `yaml:"timeout_per_run"`
	// UVPython pins the python version for the uv env (default: "3.11").
	UVPython string `yaml:"uv_python"`
	// Sandbox selects the OS sandbox for agent run_command:
	// "auto" (default; bwrap→firejail→none), "bwrap", "firejail", "none", or
	// "require" (auto, but hard-fail if no sandbox tool is available).
	Sandbox string `yaml:"sandbox"`
	// Types restricts which task types run (default: all graded types, excluding observed).
	Types []string `yaml:"types"`
	// Trials is the default trials-per-task (overridden by -n on the command line).
	Trials int `yaml:"trials"`
	// PipPackages are installed into the shared uv env at preflight so agents can
	// use common test deps without reaching outside the sandbox to find them.
	// nil (unset) defaults to ["pytest"]; an explicit empty list installs nothing.
	PipPackages []string `yaml:"pip_packages"`
	// IncludeObserved runs the ungraded ambiguous-spec tasks too (persist-only).
	IncludeObserved bool `yaml:"include_observed"`
}

type ToolGroupConfig struct {
	// Name is the tool the model sees, e.g. "Web.browsing". Must be unique
	// across groups and must not collide with a built-in tool.
	Name string `yaml:"name"`

	// Enabled opts the group in. Zero value false = skipped (opt-in).
	Enabled bool `yaml:"enabled"`

	// Description is what the model reads when deciding whether to open the
	// group, and the only thing a group costs while it is unopened. Write it
	// as when to reach for the group rather than as a list of what is in it.
	Description string `yaml:"description"`

	// Category places the group's documentation in the system prompt:
	// "filesystem", "shell", "web", "plan" or "mcp".
	// Defaults to "mcp".
	Category string `yaml:"category"`

	// Instructions is prose returned with the reference, for the things the
	// member schemas cannot say. InstructionsFile is read into it at load
	// time when set; a relative path resolves against the config file's
	// directory, so a missing file fails at startup rather than at the call.
	Instructions     string `yaml:"instructions"`
	InstructionsFile string `yaml:"instructions_file"`

	// MCPServers names entries of mcp.servers whose tools become this group's
	// members. Those servers are not dialed at startup and their tools are not
	// advertised to the model directly.
	MCPServers []string `yaml:"mcp_servers"`

	// Tools names built-in tools to move into this group. They are registered
	// as members instead of as tools of their own, so they stop appearing in
	// every request.
	Tools []string `yaml:"tools"`
}

type ToolsConfig struct {
	Read     ReadToolConfig     `yaml:"read"`
	Images   ImagesConfig       `yaml:"images"`
	Edit     EditToolConfig     `yaml:"edit"`
	Search   SearchToolConfig   `yaml:"search"`
	Glob     GlobToolConfig     `yaml:"glob"`
	Shell    ShellToolConfig    `yaml:"shell"`
	Question QuestionToolConfig `yaml:"question"`
	Report   ReportToolConfig   `yaml:"report"`
	Procs    ProcsToolsConfig   `yaml:"procs"`
	Batch    BatchToolConfig    `yaml:"batch"`
	Web      WebToolsConfig     `yaml:"web"`
	Subagent SubagentToolConfig `yaml:"subagent"`

	// Safety confirmations (runtime only, not persisted)
	SafetyConfirmations map[string]SafetyConfirmation `yaml:"-"`
}

type UIConfig struct {
	// Markdown selects when the final answer is styled as markdown:
	// "auto" (the default), "always", or "never". Auto styles only on a
	// terminal; piped output and --json stay raw markdown. Empty and
	// unknown values are auto.
	Markdown string `yaml:"markdown"`

	// TerminalTitle controls the window title the interactive front end
	// keeps up to date while it runs.
	TerminalTitle TerminalTitleConfig `yaml:"terminal_title"`
}

type UpdatesConfig struct {
	// Enabled gates the automatic check. Nil (unset) means on, so existing
	// configs check daily; false turns the background query off while
	// :update --check still works on demand. KVIT_NO_UPDATE_CHECK=1 does
	// the same without a config edit.
	Enabled *bool `yaml:"enabled"`
	// IntervalHours is the minimum time between automatic checks (default
	// 24). Zero or negative means the default.
	IntervalHours int `yaml:"interval_hours"`
}

type WebFetchToolConfig struct {
	Enabled   bool   `yaml:"enabled"`
	Timeout   int    `yaml:"timeout"`
	MaxBytes  int64  `yaml:"max_bytes"`
	UserAgent string `yaml:"user_agent"`
}

type WebSearchToolConfig struct {
	Enabled     bool `yaml:"enabled"`
	Count       int  `yaml:"count"`
	MaxAttempts int  `yaml:"max_attempts"`
	Timeout     int  `yaml:"timeout"`
}

type WebToolsConfig struct {
	APIKeyEnv string `yaml:"api_key_env"`
	BaseURL   string `yaml:"base_url"`
	UsageLog  string `yaml:"usage_log"`

	Search WebSearchToolConfig `yaml:"search"`
	Fetch  WebFetchToolConfig  `yaml:"fetch"`
}