config

type Agent struct {
	// Metadata contains agent configuration details.
	Metadata AgentMetadata
	// Prompt is the agent's prompt template.
	Prompt prompts.Prompt
}

type AgentMetadata struct {
	// Name is the unique identifier for the agent.
	Name string `validate:"required"`
	// Description explains the agent's purpose.
	Description string
	// Model specifies which AI model to use.
	Model Model `validate:"required"`
	// Tools defines tool availability for this agent.
	Tools Tools
	// Hooks controls which hooks are active for this agent.
	Hooks HookFilter
	// System is the name of the system prompt to use.
	System string
	// Mode is the operational mode for this agent.
	Mode string
	// Hide excludes this agent from UI listing and cycling.
	Hide *bool
	// Default marks this agent as the default when --agent is not specified.
	// Only one loaded agent may have Default: true (error if multiple).
	Default *bool `yaml:"default"`
	// Subagent marks this agent as available for the Task tool (subagent delegation).
	Subagent *bool `yaml:"subagent"`
	// AgentsMd controls which AGENTS.md files are injected into this agent's prompt.
	// Values: "" or "all" (default), "global", "local", "none".
	AgentsMd AgentsMdFilter `yaml:"agentsmd" validate:"omitempty,oneof=all global local none"`
	// Thinking controls how thinking blocks from prior turns are handled.
	Thinking thinking.Strategy
	// Files lists paths to load into the system prompt at BuildAgent() time.
	// Paths are expanded as Go templates before reading (e.g., {{ .Config.Source }}/file.md).
	// Relative paths are resolved against the config home directory.
	Files []string
	// SourceHome is the config home directory this agent was loaded from.
	// Set during Load() by matching the agent file's path against the homes list.
	SourceHome string `yaml:"-"`
	// Features holds per-agent feature overrides. Non-zero values are merged
	// on top of global feature defaults at agent resolution time.
	Features Features
	// Inherit lists parent agent names for config inheritance.
	Inherit []string `yaml:"inherit"`
	// Fallback lists agent names to try when this agent's provider fails.
	// Ordered: first entry is tried first. Evaluated only on the primary agent —
	// fallback agents' own fallback lists are ignored.
	Fallback []string `yaml:"fallback"`
	// ResponseFormat constrains LLM responses to a specific format (nil = unconstrained text).
	ResponseFormat *responseformat.ResponseFormat `yaml:"response_format"`
}

type AgentsMd struct {
	// Prompt is the content of the AGENTS.md file.
	Prompt prompts.Prompt
	// Type identifies whether this is a global or local configuration.
	Type Type
}

type AgentsMdFilter string

type AgentsMds map[file.File]AgentsMd

type ApprovalRules struct {
	Project Approvals
	Global  Approvals
}

type Approvals struct {
	ToolAuto []string `yaml:"tool_auto"`
}

type BashTruncation struct {
	// MaxOutputBytes caps the number of bytes captured from stdout/stderr during execution.
	// Prevents OOM from unbounded output (e.g., binary dumps, base64).
	// nil = apply default (1MB), 0 = disabled (no byte cap), N = cap at N bytes.
	MaxOutputBytes *int `yaml:"max_output_bytes"`
	// MaxLines is the line count threshold above which output is truncated.
	// nil = disabled (no truncation), 0 = exit-code only, N = truncate after N lines.
	MaxLines *int `yaml:"max_lines"`
	// HeadLines is the number of lines kept from the beginning.
	HeadLines *int `yaml:"head_lines"`
	// TailLines is the number of lines kept from the end.
	TailLines *int `yaml:"tail_lines"`
}

type CLIOverrides struct {
	MaxSteps    *int // --max-steps (nil = not set, use config default)
	TokenBudget *int // --token-budget (nil = not set, use config default)
}

type Capability string

type Collection[T Namer] map[file.File]T

type Compaction struct {
	// Threshold is the context window fill percentage that triggers automatic compaction.
	Threshold float64 `yaml:"threshold"`
	// MaxTokens is an absolute token count that triggers compaction when exceeded.
	// Takes priority over Threshold — when set, percentage mode is not used.
	MaxTokens int `yaml:"max_tokens"`
	// TrimThreshold is the fill percentage at which duplicate synthetic messages are removed.
	TrimThreshold float64 `yaml:"trim_threshold"`
	// TrimMaxTokens is an absolute token count that triggers synthetic trimming when exceeded.
	// Takes priority over TrimThreshold — when set, percentage mode is not used.
	TrimMaxTokens int `yaml:"trim_max_tokens"`
	// KeepLastMessages is the number of recent messages preserved during compaction.
	KeepLastMessages int `yaml:"keep_last_messages"`
	// Agent is the name of the agent to use for compaction (empty = current provider).
	Agent string `yaml:"agent"`
	// Prompt overrides the compaction agent: use the current agent's model with this
	// named system prompt (from prompts/) instead of delegating to a dedicated agent.
	// When set, Agent is ignored. This is the "self-compact" signal.
	Prompt string `yaml:"prompt"`
	// ToolResultMaxLen is the max character length for tool results in the compaction transcript.
	ToolResultMaxLen int `yaml:"tool_result_max_length"`
	// TruncationRetries is the sequence of progressively lower tool result lengths tried
	// when compaction fails. The initial attempt uses ToolResultMaxLen; these are the retries.
	TruncationRetries []int `yaml:"truncation_retries"`
	// Chunks is the number of chunks to split the compactable history into.
	// 1 = single-pass (current behavior). >1 = sequential chunked compaction
	// where each chunk's summary feeds into the next.
	Chunks int `yaml:"chunks"`
	// Prune controls tool result pruning to keep context lean.
	Prune Prune `yaml:"prune"`
}

type Config struct {
	Providers StringCollection[Provider]
	// Systems contains all loaded system prompts.
	Systems Collection[System]
	// Modes contains all loaded operational modes.
	Modes Collection[Mode]
	// Agents contains all loaded agent configurations.
	Agents Collection[Agent]
	// AgentsMd contains all loaded AGENTS.md workspace instructions.
	AgentsMd AgentsMds
	// MCPs contains all loaded MCP server configurations.
	MCPs StringCollection[mcp.Server]
	// Features holds feature-level configuration (compaction, title, thinking).
	Features Features
	// Commands contains all loaded custom slash commands.
	Commands Collection[CustomCommand]
	// Skills contains all loaded LLM-invocable skill definitions.
	Skills Collection[Skill]
	// ToolDefs holds unified tool definitions loaded from .aura/config/tools/**/*.yaml.
	// Entries are text-only overrides for tool descriptions, usage, examples, and metadata (disabled, condition, parallel).
	ToolDefs ToolDefs
	// Hooks holds user-configurable shell hooks loaded from .aura/config/hooks/**/*.yaml.
	Hooks Hooks
	// LSPServers holds LSP server configurations loaded from .aura/config/lsp/**/*.yaml.
	LSPServers LSPServers
	// Tasks holds scheduled task definitions loaded from .aura/config/tasks/**/*.yaml.
	Tasks task.Tasks
	// Plugins holds plugin definitions loaded from .aura/plugins/*/plugin.yaml.
	Plugins StringCollection[Plugin]
	// ApprovalRules holds persisted bash approval patterns from config/rules/**/*.yaml.
	ApprovalRules ApprovalRules
}

type ConfigPaths struct {
	Global  string // ~/.aura (always)
	Project string // write home (last --config entry)
	Source  string // per-file, the config home this agent was loaded from
}

type CustomCommand struct {
	Metadata struct {
		Name        string `validate:"required"`
		Description string
		Hints       string // Argument hint text shown as ghost text in TUI (e.g. "<file> [options]").
	}
	Body string
}

type DeferredToolIndex struct {
	BuiltIn []string            // non-MCP tool names
	Servers map[string][]string // server name → short tool names
}

type Embeddings struct {
	// Agent is the name of the agent to use for embedding.
	Agent string `yaml:"agent"`
	// MaxResults is the default number of results to return.
	MaxResults int `yaml:"max_results"`
	// Gitignore is additional gitignore patterns for file filtering.
	// Combined with .gitignore at project root if it exists.
	Gitignore string `yaml:"gitignore"`
	// Offload enables explicit model load/unload for the embedding model.
	// When true, the embed model is preloaded before indexing and unloaded after query embedding
	// to free VRAM for subsequent pipeline stages (e.g., reranking).
	Offload bool `yaml:"offload"`
	// Chunking holds chunking parameters.
	Chunking SemanticChunking `yaml:"chunking"`
	// Reranking holds reranking configuration.
	Reranking SemanticReranking `yaml:"reranking"`
}

type Estimation struct {
	// Method selects the estimation algorithm: "rough", "tiktoken", "rough+tiktoken", "native".
	// "rough" = chars/divisor, "tiktoken" = tiktoken encoding, "rough+tiktoken" = max of both,
	// "native" = provider-specific tokenization (llamacpp /tokenize, ollama /api/generate).
	Method string `yaml:"method" validate:"omitempty,oneof=rough tiktoken rough+tiktoken native"`
	// Divisor is the chars-per-token divisor for rough estimation (default 4).
	Divisor int `yaml:"divisor"`
	// Encoding is the tiktoken encoding name (default "cl100k_base").
	Encoding string `yaml:"encoding"`
}

type Features struct {
	Compaction    Compaction     `yaml:"compaction"`
	Title         Title          `yaml:"title"`
	Thinking      Thinking       `yaml:"thinking"`
	Vision        Vision         `yaml:"vision"`
	Embeddings    Embeddings     `yaml:"embeddings"`
	ToolExecution ToolExecution  `yaml:"tools"`
	STT           STT            `yaml:"stt"`
	TTS           TTS            `yaml:"tts"`
	Sandbox       SandboxFeature `yaml:"sandbox"`
	Subagent      Subagent       `yaml:"subagent"`
	PluginConfig  PluginConfig   `yaml:"plugins"`
	MCP           MCPFeature     `yaml:"mcp"`
	Estimation    Estimation     `yaml:"estimation"`
	Guardrail     Guardrail      `yaml:"guardrail"`
}

type FileEntry struct {
	Name         string // display name (e.g., "docs/rules.txt")
	TemplateName string // registered template name (e.g., "file:docs/rules.txt")
}

type Files struct {
	Providers files.Files
	Modes     files.Files
	Agents    files.Files
	Prompts   files.Files
	AgentsMd  files.Files
	MCP       files.Files
	Features  files.Files
	Commands  files.Files
	Skills    files.Files
	Tools     files.Files
	Hooks     files.Files
	Tasks     files.Files
	LSP       files.Files
	Plugins   files.Files
	Rules     files.Files
}

type Guardrail struct {
	// Mode controls what happens when the guardrail flags something.
	//   "block" — reject the tool call / message
	//   "log"   — show info note inline, proceed normally
	// Empty string = disabled (no guardrail checks run). Default.
	Mode string `yaml:"mode" validate:"omitempty,oneof=block log"`
	// OnError controls what happens when the guardrail check itself fails
	// (timeout, network error, model unavailable — after retries).
	//   "block" — fail-closed: block the content (default for mode=block)
	//   "allow" — fail-open: proceed without guardrail check (default for mode=log)
	// Decoupled from Mode so users can have mode=block + on_error=allow.
	OnError string `yaml:"on_error" validate:"omitempty,oneof=block allow"`
	// Timeout is the max duration for a single guardrail check.
	// If exceeded, the check is treated as if the guardrail model is unavailable.
	Timeout time.Duration `yaml:"timeout"`
	// Scope controls which message types are sent to the guardrail model.
	// Each scope has its own agent/prompt — a scope is active when agent or prompt is set.
	Scope GuardrailScope `yaml:"scope"`
	// Tools filters which tools trigger guardrail checks (for tool_calls scope).
	// Same enabled/disabled glob syntax as tools feature config.
	Tools GuardrailTools `yaml:"tools"`
}

type GuardrailScope struct {
	// ToolCalls checks assistant-generated tool calls before execution.
	ToolCalls GuardrailScopeEntry `yaml:"tool_calls"`
	// UserMessages checks user input before it enters conversation.
	UserMessages GuardrailScopeEntry `yaml:"user_messages"`
}

type GuardrailScopeEntry struct {
	// Agent is the dedicated guardrail agent name for this scope.
	Agent string `yaml:"agent"`
	// Prompt is a named system prompt (from prompts/). When set, uses the
	// current agent's provider/model with this prompt instead of a dedicated
	// agent. Overrides Agent (same semantics as compaction.prompt).
	Prompt string `yaml:"prompt"`
}

type GuardrailTools struct {
	// Enabled is a list of glob patterns. Only matching tools are checked.
	// Empty = all tools checked.
	Enabled []string `yaml:"enabled"`
	// Disabled is a list of glob patterns. Matching tools are skipped.
	// Applied after Enabled.
	Disabled []string `yaml:"disabled"`
}

type Hook struct {
	// Event is the hook timing: "pre" (before Execute) or "post" (after Execute).
	Event string `yaml:"event" validate:"required,oneof=pre post"`
	// Matcher is a regex matched against the tool name. Empty = match all tools.
	Matcher string `yaml:"matcher"`
	// Files is a glob pattern matched against file basenames (e.g. "*.go", "*.py").
	// When set, the hook only runs if at least one file path in the tool input matches.
	Files string `yaml:"files"`
	// Command is the shell command executed via sh -c. Receives JSON context on stdin.
	// $FILE env var is set to matched file paths (space-separated).
	Command string `yaml:"command" validate:"required"`
	// Timeout is the max seconds before the hook process is killed. nil = default (10s).
	Timeout *int `yaml:"timeout"`
	// Depends lists hook names that must run before this hook (within the same event).
	Depends []string `yaml:"depends"`
	// Silent suppresses all output and exit codes. The hook runs but never produces messages or blocks.
	Silent *bool `yaml:"silent"`
	// Disabled skips this hook entirely. It still appears in /hooks display but never executes.
	Disabled *bool `yaml:"disabled"`
	// Inherit lists parent hook names for config inheritance.
	Inherit []string `yaml:"inherit"`
}

type HookFilter struct {
	// Enabled is the list of hook name patterns to include.
	Enabled []string `yaml:"enabled"`
	// Disabled is the list of hook name patterns to exclude.
	Disabled []string `yaml:"disabled"`
}

type Hooks map[string]Hook

type LSPServers map[string]lsp.Server

type MCPFeature struct {
	// Enabled is the default for --include-mcps. Glob patterns for servers to connect.
	// Empty = connect all enabled servers. CLI --include-mcps overrides this.
	Enabled []string `yaml:"enabled"`
	// Disabled is the default for --exclude-mcps. Glob patterns for servers to skip.
	// Empty = skip none. CLI --exclude-mcps overrides this.
	Disabled []string `yaml:"disabled"`
}

type MemoriesData struct {
	Local  string // concatenated .aura/memory/*.md contents
	Global string // concatenated ~/.aura/memory/*.md contents
}

type Mode struct {
	// Metadata contains mode configuration details.
	Metadata ModeMetadata
	// Prompt is the mode's prompt template.
	Prompt prompts.Prompt
}

type ModeData struct {
	Name string
}

type ModeMetadata struct {
	// Name is the unique identifier for the mode.
	Name string `validate:"required"`
	// Description explains the mode's purpose.
	Description string
	// Hide excludes this mode from UI listing and cycling.
	Hide *bool
	// Tools defines tool availability for this mode.
	Tools Tools
	// Hooks controls which hooks are active for this mode.
	Hooks HookFilter
	// Features holds per-mode feature overrides. Non-zero values are merged
	// on top of agent features at mode resolution time.
	Features Features
	// Inherit lists parent mode names for config inheritance.
	Inherit []string `yaml:"inherit"`
}

type Model struct {
	// Name is the model identifier.
	Name string `validate:"required"`
	// Provider is the name of the provider hosting the model.
	Provider string `validate:"required"`
	// Think configures extended thinking mode (zero value=off, bool, or "low"/"medium"/"high").
	Think thinking.Value
	// Context is the maximum context window size.
	Context int
	// Generation holds optional sampling, output, and thinking budget parameters.
	Generation *generation.Generation
}

type ModelData struct {
	Name            string
	Family          string
	ParameterCount  int64  // raw value for comparisons: {{ if lt .Model.ParameterCount 10000000000 }}
	ParameterSize   string // display string: "8B", "70B", "1.5B"
	ContextLength   int
	Thinking        bool
	ThinkingLevels  bool
	Tools           bool
	Vision          bool
	Embedding       bool
	Reranking       bool
	ContextOverride bool
}

type ModelFilter struct {
	Include []string `yaml:"include"`
	Exclude []string `yaml:"exclude"`
}

type Namer interface {
	Name() string
}

type Options struct {
	Homes          []string          // all config dirs in merge order (global first, then --config entries)
	WriteHome      string            // primary home for writes (sessions, debug, auth, plugins)
	GlobalHome     string            // ~/.aura — kept for approval provenance + global auth dir
	LaunchDir      string            // CWD at process start, before --workdir
	WorkDir        string            // CWD after --workdir processing
	WithPlugins    bool              // load plugin definitions
	UnsafePlugins  bool              // enable os/exec in plugins (--unsafe-plugins)
	SetVars        map[string]string // --set template variables for task metadata expansion
	ExtraTaskFiles []string          // additional task file glob patterns (from tasks --files)
	CLI            CLIOverrides
}

type Part string

type Paths struct {
	// Home is the config directory path (e.g. ".aura" or "/home/user/.aura").
	Home string
	// Global is the global config directory (~/.aura).
	Global string
	// Launch is the CWD at process start, before os.Chdir(--workdir).
	Launch string
	// Work is the effective working directory after os.Chdir(--workdir).
	Work string
}

type Plugin struct {
	Description string         `yaml:"description"`
	Condition   string         `yaml:"condition"`
	Disabled    *bool          `yaml:"disabled"`
	Once        bool           `yaml:"once"`
	Override    bool           `yaml:"override"` // replace a built-in tool with the same name
	OptIn       bool           `yaml:"opt_in"`   // tool is hidden unless explicitly enabled by name
	Env         []string       `yaml:"env"`      // env var names this plugin may read (["*"] = all)
	Config      map[string]any `yaml:"config"`   // default config values shipped with the plugin

	Name      string         `yaml:"name"` // optional; defaults to directory name in Load()
	Source    string         `yaml:"-"`    // plugin.yaml file path
	Origin    gitutil.Origin `yaml:"-"`    // loaded from .origin.yaml sidecar
	OriginDir string         `yaml:"-"`    // directory where .origin.yaml lives (may differ from Dir() for packs)
}

type PluginConfig struct {
	// Dir overrides the plugin discovery directory for a config home.
	// Relative paths resolve against the home that declares them.
	// Empty = default "plugins/" subdirectory.
	// NOTE: This field exists so the YAML parser accepts it, but plugin
	// discovery uses ResolvePluginDir (peek) because it runs before feature merge.
	Dir string `yaml:"dir"`
	// Unsafe allows plugins to use os/exec and other restricted imports.
	// When false (default), plugins that import os/exec fail at load time.
	Unsafe bool `yaml:"unsafe"`
	// Include filters plugins by name. Empty = load all enabled plugins.
	Include []string `yaml:"include"`
	// Exclude filters plugins by name. Applied after Include.
	Exclude []string `yaml:"exclude"`
	// Config holds plugin config values. Global values are sent to all plugins;
	// Local values are keyed by plugin name and override Global.
	Config struct {
		Global map[string]any            `yaml:"global"`
		Local  map[string]map[string]any `yaml:"local"`
	} `yaml:"config"`
}

type PolicyAction int

type Provider struct {
	// URL is the API endpoint for the provider. Optional for providers with default endpoints (e.g., Anthropic).
	URL string
	// Type is the provider type (e.g., ollama, llamacpp, openrouter, openai, anthropic).
	Type string `validate:"required,oneof=ollama llamacpp openrouter openai anthropic google copilot codex"`
	// Token is the authentication token for API access.
	Token string
	// Models controls which models appear in visual listings.
	Models ModelFilter `yaml:"models"`
	// KeepAlive controls how long models stay loaded in VRAM after a request (Ollama only).
	// Uses Go duration syntax: "5m", "1h", "30s". Empty means provider default.
	KeepAlive string `yaml:"keep_alive"`
	// Timeout is the HTTP response header timeout for provider calls.
	// Uses Go duration syntax: "5m", "30s". Limits time waiting for response headers
	// without affecting long-running streaming responses.
	Timeout string `yaml:"timeout"`
	// Retry configures exponential-backoff retry for transient Chat() failures.
	// Disabled by default (MaxAttempts: 0). Only meaningful for cloud providers.
	Retry Retry `yaml:"retry"`
	// Capabilities declares what this provider supports (chat, embed, rerank, transcribe, synthesize).
	// Empty means all capabilities. Chat implies model listing.
	Capabilities []Capability `yaml:"capabilities"`
	// Source is the file path this provider was loaded from. Set by Load(), not from YAML.
	Source string `yaml:"-"`
	// AuthDirs is the ordered list of directories to search for stored auth tokens.
	// Populated by config.New(), not from YAML. Order: project auth dir, then global auth dir.
	AuthDirs []string `yaml:"-"`
}

type Prune struct {
	// Mode controls when pruning runs: "off", "iteration", "compaction".
	Mode PruneMode `yaml:"mode" validate:"omitempty,oneof=off iteration compaction"`
	// ProtectPercent is the percentage of the main model's context to protect
	// from pruning (most recent messages).
	ProtectPercent float64 `yaml:"protect_percent"`
	// ArgThreshold is the minimum estimated token count for a tool call's
	// arguments to be eligible for pruning.
	ArgThreshold int `yaml:"arg_threshold"`
}

type PruneMode string

type ReadBeforeConfig struct {
	Write  *bool `yaml:"write"`  // nil = default (true)
	Delete *bool `yaml:"delete"` // nil = default (false)
}

type ReadBeforeData struct {
	Write  bool // must read before writing/patching
	Delete bool // must read before deleting
}

type Restrictions struct {
	ReadOnly  []string `mapstructure:"ro" yaml:"ro"`
	ReadWrite []string `mapstructure:"rw" yaml:"rw"`
}

type Retry struct {
	// MaxAttempts is the number of retry attempts before giving up. 0 = disabled.
	MaxAttempts int `yaml:"max_attempts"`
	// BaseDelay is the initial delay between retries (Go duration). Default "1s".
	BaseDelay string `yaml:"base_delay"`
	// MaxDelay is the maximum delay between retries (Go duration). Default "30s".
	MaxDelay string `yaml:"max_delay"`
}

type Runtime struct {

	// WithPlugins indicates whether user-defined Go plugins are enabled.
	WithPlugins bool
	// UnsafePlugins enables os/exec access for plugins (CLI --unsafe-plugins).
	UnsafePlugins bool
	// DisplayProviders holds CLI --providers filter for model listings.
	DisplayProviders []string
	// IncludeTools holds CLI --include-tools glob patterns.
	IncludeTools []string
	// ExcludeTools holds CLI --exclude-tools glob patterns.
	ExcludeTools []string
	// IncludeMCPs holds CLI --include-mcps glob patterns for MCP server filtering.
	IncludeMCPs []string
	// ExcludeMCPs holds CLI --exclude-mcps glob patterns for MCP server filtering.
	ExcludeMCPs []string

	// AllTools is the complete tool set including runtime-dependent tools (todo, vision, query).
	AllTools tool.Tools
	// ExtraFilter holds an additional runtime tool filter (e.g. task-level overrides).
	ExtraFilter *tool.Filter
	// OptInTools lists tool names that are hidden unless explicitly enabled by name or narrow glob.
	OptInTools []string
	// LoadedTools tracks tools loaded via LoadTools this session. Deferred tools
	// in this set stay eager on subsequent rebuilds.
	LoadedTools map[string]bool
	// ConditionState holds the current runtime state for evaluating tool/MCP conditions.
	// Nil means "skip all condition checks" (e.g. `aura tools` CLI, startup before model resolution).
	ConditionState *condition.State
}

type STT struct {
	// Agent is the name of the agent to use for transcription calls.
	Agent string `yaml:"agent"`
	// Language is the default ISO-639-1 language hint (e.g. "en"). Empty = auto-detect.
	Language string `yaml:"language"`
}

type SandboxData struct {
	Enabled   bool // Landlock actually enforcing (available AND requested)
	Requested bool // User wants sandbox (config or runtime toggle, independent of kernel)
	ReadOnly  []string
	ReadWrite []string
	Display   string // Pre-rendered restriction text for prompt injection
}

type SandboxFeature struct {
	Enabled      *bool        `yaml:"enabled"`      // nil = inherit, &true = enable, &false = disable
	Restrictions Restrictions `yaml:"restrictions"` // base paths (override semantics via mergo)
	Extra        Restrictions `yaml:"extra"`        // additional paths (override semantics, concatenated at read time)
}

type SemanticChunking struct {
	// Strategy is the chunking strategy to use.
	Strategy string `yaml:"strategy" validate:"omitempty,oneof=auto ast line"`
	// MaxTokens is the target max tokens per chunk.
	MaxTokens int `yaml:"max_tokens"`
	// OverlapTokens is the overlap tokens between adjacent chunks.
	OverlapTokens int `yaml:"overlap_tokens"`
}

type SemanticReranking struct {
	// Agent is the name of the agent to use for reranking (empty = skip reranking).
	Agent string `yaml:"agent"`
	// Multiplier controls how many extra candidates to fetch for reranking.
	Multiplier int `yaml:"multiplier"`
	// Offload enables explicit model load/unload for the reranker model.
	// When true, the reranker model is loaded before reranking and unloaded after
	// to free VRAM.
	Offload bool `yaml:"offload"`
}

type Skill struct {
	Metadata struct {
		Name        string `validate:"required"`
		Description string `validate:"required"`
	}
	Body string
}

type StringCollection[T any] map[string]T

type Subagent struct {
	// MaxSteps caps the total number of LLM round-trips per subagent run.
	MaxSteps int `yaml:"max_steps"`
	// DefaultAgent is the agent name used when no agent is specified in the Task tool call.
	DefaultAgent string `yaml:"default_agent"`
}

type Summary struct {
	Homes      []string
	Sections   []SummarySection
	Features   Features
	LSPServers LSPServers
}

type SummaryEntry struct {
	Name   string
	Source string
	Detail string
}

type SummarySection struct {
	Label   string
	Entries []SummaryEntry
}

type System struct {
	// Metadata contains system prompt configuration details.
	Metadata SystemMetadata
	// Prompt is the system prompt template.
	Prompt prompts.Prompt
}

type SystemMetadata struct {
	// Name is the unique identifier for the system prompt.
	Name string `validate:"required"`
	// Description explains the system prompt's purpose.
	Description string
	// Inherit lists parent prompt names whose bodies are prepended to this prompt.
	Inherit []string `yaml:"inherit"`
}

type TTS struct {
	// Agent is the name of the agent to use for synthesis calls.
	Agent string `yaml:"agent"`
	// Voice is the default voice identifier (e.g. "alloy", "af_heart").
	Voice string `yaml:"voice"`
	// Format is the default output audio format (e.g. "mp3", "wav").
	Format string `yaml:"format"`
	// Speed is the default playback speed (0.25-4.0). Default: 1.0.
	Speed float64 `yaml:"speed"`
}

type TemplateData struct {
	Config     ConfigPaths
	LaunchDir  string // CWD at process start, before --workdir
	WorkDir    string // CWD after --workdir processing
	Model      ModelData
	Provider   string
	Agent      string
	Mode       ModeData
	Tools      ToolsData        // eager + deferred tool info, filled by BuildAgent
	Vars       map[string]any   // user-defined --set template variables
	Sandbox    SandboxData      // sandbox state, filled by BuildAgent before all template rendering
	ReadBefore ReadBeforeData   // read-before-write policy, filled by BuildAgent
	ToolPolicy ToolPolicyData   // tool policy, filled by BuildAgent
	Memories   MemoriesData     // concatenated memory file contents, filled by BuildAgent
	Files      []FileEntry      // autoloaded file entries for composition
	Workspace  []WorkspaceEntry // workspace (AGENTS.md) entries for composition
}

type Thinking struct {
	// Agent is the name of the agent to use for thinking rewrite (empty = current provider).
	Agent string `yaml:"agent"`
	// Prompt overrides the thinking agent: use the current agent's model with this
	// named system prompt (from prompts/) instead of delegating to a dedicated agent.
	// When set, Agent is ignored. This is the "self-rewrite" signal.
	Prompt string `yaml:"prompt"`
	// KeepLast is the number of recent messages whose thinking is preserved unchanged.
	KeepLast int `yaml:"keep_last"`
	// TokenThreshold is the minimum token count for a thinking block to be stripped or rewritten.
	TokenThreshold int `yaml:"token_threshold"`
}

type Title struct {
	// Disabled skips LLM title generation and uses the first user message instead.
	Disabled *bool `yaml:"disabled"`
	// Agent is the name of the agent to use for title generation.
	// If empty and not disabled, falls back to the current conversation's provider/model.
	Agent string `yaml:"agent"`
	// Prompt overrides the title agent: use the current agent's model with this
	// named system prompt (from prompts/) instead of delegating to a dedicated agent.
	// When set, Agent is ignored.
	Prompt string `yaml:"prompt"`
	// MaxLength is the maximum character length for generated titles.
	MaxLength int `yaml:"max_length"`
}

type ToolBash struct {
	// Truncation controls middle-truncation of Bash tool output.
	Truncation BashTruncation `yaml:"truncation"`
	// Rewrite is a Go text/template applied to every Bash tool command before execution.
	// Template receives {{ .Command }} (the original command) and sprig functions.
	// Empty = no rewrite. Example: "rtk {{ .Command }}"
	Rewrite string `yaml:"rewrite"`
}

type ToolDef struct {
	Disabled    *bool  `yaml:"disabled"`
	Override    bool   `yaml:"override"`
	Description string `yaml:"description"`
	Usage       string `yaml:"usage"`
	Examples    string `yaml:"examples"`
	Condition   string `yaml:"condition"` // condition expression for conditional inclusion
	Parallel    *bool  `yaml:"parallel"`  // overrides tool.Parallel()
	Source      string `yaml:"-"`         // file path this definition was loaded from
}

type ToolDefs map[string]ToolDef

type ToolExecution struct {
	// Mode selects the guard strategy: "tokens" (fixed limit) or "percentage" (context-fill based).
	Mode string `yaml:"mode" validate:"omitempty,oneof=percentage tokens"`
	// Result groups tool result size guard fields.
	Result ToolResult `yaml:"result"`
	// ReadSmallFileTokens is the token threshold below which the Read tool ignores line ranges and returns the full
	// file.
	ReadSmallFileTokens int `yaml:"read_small_file_tokens"`
	// MaxSteps caps the total number of iterations to prevent runaway loops.
	// At this limit, tools are disabled and the LLM must respond with text only.
	MaxSteps int `yaml:"max_steps"`
	// TokenBudget is the cumulative token limit (input + output) for a session.
	// Once reached, the assistant stops immediately. 0 = disabled.
	TokenBudget int `yaml:"token_budget"`
	// RejectionMessage is the fmt template sent back as the tool result when rejected.
	// Receives two %d arguments: estimated tokens, limit.
	RejectionMessage string `yaml:"rejection_message"`
	// Bash groups Bash tool configuration (truncation + command rewrite).
	Bash ToolBash `yaml:"bash"`
	// UserInputMaxPercentage is the context-fill percentage above which user input messages are rejected.
	// Prevents massive messages (typed, @Bash, @File) from entering the conversation and causing
	// unrecoverable context exhaustion. 0 = disabled.
	UserInputMaxPercentage float64 `yaml:"user_input_max_percentage"`
	// ReadBefore controls which file operations require a prior read.
	// write: true (default) = must read before overwriting existing files.
	// delete: false (default) = no read required before deleting.
	// Toggled at runtime with /readbefore (alias /rb).
	ReadBefore ReadBeforeConfig `yaml:"read_before"`
	// Enabled is the default for --include-tools. Glob patterns for tools to include.
	// Empty = no include filter (all tools pass). CLI --include-tools overrides this.
	Enabled []string `yaml:"enabled"`
	// Disabled is the default for --exclude-tools. Glob patterns for tools to exclude.
	// Empty = no exclude filter. CLI --exclude-tools overrides this.
	Disabled []string `yaml:"disabled"`
	// OptIn lists tool names that are registered but hidden unless explicitly enabled
	// by name or narrow glob at any layer (CLI, features, agent, mode, or task).
	// The bare "*" wildcard does NOT satisfy opt-in — only explicit names or narrow globs do.
	OptIn []string `yaml:"opt_in"`
	// Deferred lists tool name patterns excluded from request.Tools and listed in a
	// lightweight system prompt index instead. The model can load them on demand via
	// the LoadTools meta-tool. Empty = all tools are eager (no change in behavior).
	Deferred []string `yaml:"deferred"`
	// WebFetchMaxBodySize is the maximum response body size in bytes for the WebFetch tool.
	WebFetchMaxBodySize int64 `yaml:"webfetch_max_body_size"`
	// Parallel enables concurrent execution of independent tool calls within a single LLM turn.
	// nil = true (default). Explicit false = sequential (legacy behavior).
	Parallel *bool `yaml:"parallel"`
}

type ToolPolicy struct {
	Auto    []string `yaml:"auto"`
	Confirm []string `yaml:"confirm"`
	Deny    []string `yaml:"deny"`
	// contains filtered or unexported fields
}

type ToolPolicyData struct {
	Auto    []string // auto-approved patterns
	Confirm []string // confirmation-required patterns
	Deny    []string // denied patterns
	Display string   // pre-rendered display text
}

type ToolResult struct {
	// MaxTokens is the estimated token limit for a single tool result (used when mode = "tokens").
	MaxTokens int `yaml:"max_tokens"`
	// MaxPercentage is the context-fill percentage above which results are rejected (used when mode = "percentage").
	MaxPercentage float64 `yaml:"max_percentage"`
}

type ToolTrace struct {
	Name     string
	Included bool
	Reason   string
}

type Tools struct {
	// Enabled is the list of explicitly enabled tools.
	Enabled []string
	// Disabled is the list of explicitly disabled tools.
	Disabled []string
	// Policy controls which tool calls are auto-approved, require confirmation, or are blocked.
	Policy ToolPolicy `yaml:"policy"`
}

type ToolsData struct {
	Eager    []string // resolved eager tool names
	Deferred string   // pre-rendered deferred tool index XML (empty = none)
}

type Type string

type Vision struct {
	// Agent is the name of the agent to use for vision calls.
	Agent string `yaml:"agent"`
	// Dimension is the max pixel dimension for image compression (default: 1024).
	Dimension int `yaml:"dimension"`
	// Quality is the JPEG compression quality 1-100 (default: 75).
	Quality int `yaml:"quality"`
}

type WorkspaceEntry struct {
	Type         string // display header (e.g., "Workspace Instructions: local")
	TemplateName string // registered template name (e.g., "ws:AGENTS.md")
}