config

type AgentConfig struct {
	MaxSteps int `json:"max_steps,omitempty"`

	// AppendSystemPrompt is layer-5 operator text appended to the
	// assembled system prompt (agent.WithExtraInstruction) — the
	// documented, encouraged customization path: the harness
	// contract and mode overlay stay intact underneath. Mirrored by
	// the --append-system-prompt flag (flag beats config). #459.
	AppendSystemPrompt string `json:"append_system_prompt,omitempty"`

	// SystemPromptFile names a file whose contents REPLACE the
	// assembled system prompt wholesale (agent.WithInstruction).
	// You lose the harness contract — compaction summaries arrive
	// unexplained and tool-use degradation is on you; prefer
	// AppendSystemPrompt. Mirrored by --system-prompt-file (flag
	// beats config). #459.
	SystemPromptFile string `json:"system_prompt_file,omitempty"`

	// MaxTurnCostUSD caps a single conversation turn's cumulative
	// spend. When the post-turn hook detects spend ≥ this value, the
	// agent emits a structured turn-error (kind=cost_ceiling) and
	// refuses new turns until the operator clears the flag via
	// Agent.ResetCostCeiling. Pointer so unset is distinguishable
	// from the deliberate 0 (which would mean "no budget — refuse
	// every turn", which we treat as "disabled"). 0 or negative ==
	// disabled. Defense against the read-file-loop class of bug
	// (#144) within a single turn.
	MaxTurnCostUSD *float64 `json:"max_turn_cost_usd,omitempty"`

	// MaxSessionCostUSD caps the session's cumulative spend across
	// all turns (parent + subtask). Tripped → same behavior as
	// MaxTurnCostUSD. Useful for long-running autonomous deploys
	// where individual turns are reasonable but the session adds up.
	MaxSessionCostUSD *float64 `json:"max_session_cost_usd,omitempty"`

	// AutoContinue controls continuing restart-interrupted turns
	// automatically (#539, #559, docs/auto-continue-design.md). Nil/absent
	// leaves the feature at its precondition-gated default (on for a
	// multi-session or --no-repl daemon with a durable eventlog, off
	// elsewhere — see AutoContinueConfig.Enabled). A session interrupted
	// mid-turn by a daemon restart resumes with intact history; whether it
	// then finishes the turn or waits for the next message is what this
	// controls. Applies to lazily-resumed multi-session agents; autonomous
	// runs have their own checkpoint/resume machinery.
	AutoContinue *AutoContinueConfig `json:"auto_continue,omitempty"`

	// SessionTitle controls whether each session gets a short label
	// derived from its first prompt, so a session picker lists work
	// instead of IDs (#808). Nil/absent = on: the cost is one
	// cheap-tier call per session, and a picker full of UUIDs is not
	// a picker. Set false to turn the call off — the session keeps
	// whatever an operator names it by hand, so this disables
	// inference, not titles.
	//
	// Pointer for the usual reason: absent has to be distinguishable
	// from a deliberate false.
	SessionTitle *bool `json:"session_title,omitempty"`

	// DisplayName overrides the brand line at the top of the TUI. By
	// default the TUI shows the AppName (e.g. "core-agent"); set this
	// to give the agent a human-friendly identity ("Triage Bot",
	// "Code Reviewer", etc.). Empty falls back to AppName.
	DisplayName string `json:"display_name,omitempty"`

	// Description is a one-line summary of what this agent does.
	// Used in two places: (1) ADK's llmagent.Config.Description, which
	// becomes part of the system prompt ("you are an agent named X,
	// description: ..."), and (2) the /.well-known/agent-card.json
	// `description` field if the card endpoint is enabled. Set once,
	// fanned out to both. Empty = no description in the system prompt
	// and the card endpoint stays off unless --agent-card-description
	// overrides.
	Description string `json:"description,omitempty"`
}

type AlertAuth struct {
	BearerEnv    string `json:"bearer_env,omitempty"`
	BasicEnvUser string `json:"basic_env_user,omitempty"`
	BasicEnvPass string `json:"basic_env_pass,omitempty"`
}

type AlertTarget struct {
	// Name is the identifier the agent uses and the suffix in
	// permissions.allow patterns ("alert:<name>"). [A-Za-z0-9_-]{1,64}.
	Name string `json:"name"`
	// Kind is the transport. "" or "webhook" today; the field exists
	// so future kinds (smtp, polling APIs) can be added without a
	// schema break.
	Kind string `json:"kind,omitempty"`
	// URL or URLEnv — exactly one. Prefer URLEnv for any destination
	// whose URL embeds a secret (Slack Incoming Webhooks put the token
	// in the path), so the secret stays in a K8s Secret / env var.
	URL    string `json:"url,omitempty"`
	URLEnv string `json:"url_env,omitempty"`
	// Template selects the wire format (see AlertTemplate* constants).
	Template string `json:"template"`
	// Conversation is the destination conversation, for templates that
	// address one: required by "switchboard", rejected by every other
	// template so a field that would silently do nothing cannot be set.
	//
	// It is the gateway's platform-specific conversation key — for Slack
	// a channel ID ("C0123") or "channel:thread_ts" to post into an
	// existing thread. Routing config, like the URL, so it lives beside
	// the URL rather than in the model's arguments: the same reason the
	// tool has no arbitrary-URL parameter, one level in. A literal (no
	// *_env sibling) because a conversation key is not a secret — unlike
	// a Slack Incoming Webhook URL, which carries its token in the path.
	Conversation string `json:"conversation,omitempty"`
	// Auth is optional per-target auth material, resolved from env at
	// call time. Absent = no auth headers (the Slack Incoming Webhook
	// case — the token is already in the URL).
	Auth *AlertAuth `json:"auth,omitempty"`
	// Description is a human/LLM-facing hint surfaced in the tool
	// schema so the model knows what each target is for.
	Description string `json:"description,omitempty"`
}

type AlertsConfig struct {
	// Targets is the operator-declared allow-list of escalation
	// destinations. The agent fires a target by name; there is no
	// arbitrary-URL parameter, so a hallucinated target name is
	// rejected rather than dialed (SSRF-safe by construction).
	Targets []AlertTarget `json:"targets,omitempty"`
	// RateLimitPerTarget bounds how often a SINGLE target can fire,
	// to catch pathological alert loops (not to enforce operational
	// cadence — distinct targets are independent). Empty = no limit.
	// Format: a Go duration ("30s" = 1 per 30s) or "N/window"
	// ("5/min", "100/hour"). See ParseAlertRateLimit.
	RateLimitPerTarget string `json:"rate_limit_per_target,omitempty"`
}

type AnthropicConfig struct {
	APIKey      string             `json:"api_key,omitempty"`
	Vertex      *VertexConfig      `json:"vertex,omitempty"`
	PromptCache *PromptCacheConfig `json:"prompt_cache,omitempty"`
}

type AttachConfig struct {
	// Server-side: where the attach listener binds. Set at most one.
	// Non-loopback listen addresses (e.g. "0.0.0.0:7777") refuse to
	// start without authentication (TokenEnv bearer token, mTLS, or
	// enforced multi-session auth) — see pkg/attach.NewServer (#376).
	Listen     string `json:"listen,omitempty"`      // e.g. "127.0.0.1:7777"
	UnixSocket string `json:"unix_socket,omitempty"` // e.g. "/var/run/core-agent.sock"

	// TLS material. TLSCert + TLSKey enable HTTPS; ClientCA additionally
	// enables mTLS (client cert required). Paths only — keys live on disk.
	TLSCert  string `json:"tls_cert,omitempty"`
	TLSKey   string `json:"tls_key,omitempty"`
	ClientCA string `json:"client_ca,omitempty"`

	// TokenEnv is the name of the env var that holds the bearer token
	// clients must present. The secret itself never lives in config.
	TokenEnv string `json:"token_env,omitempty"`

	// ReadOnly disables POST /inject and /wake; read endpoints stay open.
	ReadOnly bool `json:"readonly,omitempty"`

	// PeerHub turns on the peer-registration endpoints on this listener.
	PeerHub bool `json:"peer_hub,omitempty"`

	// PeerStateFile makes the hub's peer registry durable across
	// restarts (#595): registrations are snapshotted here on every
	// change and reloaded at startup, so a hub restart doesn't blank
	// the fleet until every peer's next heartbeat fails. Ignored
	// unless PeerHub is set. Put it on a volume that outlives the
	// pod; the file holds registration IDs, so it is written 0600 and
	// wants a directory to match. Empty keeps the registry in-memory.
	PeerStateFile string `json:"peer_state_file,omitempty"`

	// Peer-side: this agent registers with a remote hub.
	RegisterTo       string `json:"register_to,omitempty"`       // hub URL
	RegisterEndpoint string `json:"register_endpoint,omitempty"` // expanded via os.ExpandEnv
	RegisterName     string `json:"register_name,omitempty"`     // defaults to hostname when empty

	// MultiSession enables per-caller authentication + per-session
	// ACL on the attach listener. Zero value (disabled) keeps the
	// daemon in single-user mode — the listener treats every request
	// as the same anonymous Caller and TokenEnv / BearerToken still
	// gate at the transport layer as today. See
	// docs/multi-session-design.md.
	MultiSession MultiSessionConfig `json:"multi_session,omitempty"`

	// CostRateLimit tunes the per-caller token bucket that bounds the
	// COST-BEARING attach endpoints (the five slash ops, POST
	// /sessions, pricing/refresh) — see #463. Omitted (nil) keeps the
	// library defaults: burst 5, 10/minute per caller. Reads, /events
	// streams, /inject, and /wake are never limited.
	CostRateLimit *CostRateLimitConfig `json:"cost_rate_limit,omitempty"`

	// ShutdownTimeout caps how long the attach listener's graceful
	// HTTP shutdown waits for in-flight requests once SSE streams are
	// hung up, as a time.Duration string (e.g. "5s"). Omitted/empty
	// keeps the library default (5s). Counts toward the daemon's
	// total teardown budget — keep it comfortably under the
	// supervisor's kill timeout (K8s terminationGracePeriodSeconds,
	// default 30s). See #538.
	ShutdownTimeout string `json:"shutdown_timeout,omitempty"`
}

type AutoContinueConfig struct {
	// Enabled turns the feature on. A *bool tristate (#559): nil (unset,
	// or a nil parent pointer) means "on by default when the feature can
	// apply" — i.e. a multi-session daemon or a --no-repl single-user
	// daemon with a durable eventlog; interactive REPL/TUI and in-process
	// library use are excluded by that precondition, so they never
	// auto-continue by default. An explicit false is a hard opt-out; an
	// explicit true forces it on (and, in a mode where it cannot apply,
	// warns and is ignored). The precondition gate lives with the CLI
	// wiring (resolveAutoContinue in cmd/core-agent) since config alone
	// cannot see the run mode or eventlog presence.
	Enabled *bool `json:"enabled,omitempty"`

	// Freshness bounds how old an interruption may be and still get
	// auto-continued, as a time.Duration string. Omitted/empty
	// defaults to "1h". Explicit "0s" disables the window (always
	// continue). Staler interruptions wait for the next real
	// message.
	Freshness string `json:"freshness,omitempty"`

	// MaxPerBoot caps how many sessions the boot-time scan will
	// continue in one daemon start, oldest interruption first.
	// Omitted/0 defaults to 10. (The scan itself lands with the
	// design doc's PR 2; the lazy-resume trigger ignores this cap —
	// a touched session is one the operator is already paying
	// attention to.)
	MaxPerBoot int `json:"max_per_boot,omitempty"`

	// Retry controls the in-lifetime retry driver: a background pass
	// that re-attempts a stranded continuation without waiting for a
	// reboot or a human message (#575 defect B), so a transient
	// continuation failure self-heals on a long-lived daemon. It stays
	// bounded by the crash-loop breaker + per-session cumulative cap —
	// a daemon-killing turn kills the driver too, so only survivable
	// failures are ever re-fired.
	//
	// A *bool so the default (nil) can be "on wherever auto-continue is
	// enabled": with the driver on, the promise shifts from "one
	// automatic retry, then wait for a human" to "self-heal up to the
	// cap, minutes apart, unattended". Set an explicit false to keep the
	// one-shot-then-wait contract.
	Retry *bool `json:"retry,omitempty"`

	// RetryInterval is how often the retry driver re-runs a guarded
	// pass, as a time.Duration string. Omitted/empty defaults to "5m".
	// The per-session single-retry guard (breakerWindow, 10m) is the
	// effective per-session cadence, so values below it simply no-op on
	// recently-attempted sessions. Must parse and be > 0.
	RetryInterval string `json:"retry_interval,omitempty"`
}

type BuiltinToolsConfig struct {
	// WebSearch toggles server-side web search grounding.
	// Provider defaults: Gemini on, Anthropic off.
	WebSearch *bool `json:"web_search,omitempty"`

	// URLContext toggles fetching and grounding on URLs the model
	// decides to visit. Gemini only; default on.
	URLContext *bool `json:"url_context,omitempty"`

	// CodeExecution toggles sandboxed Python execution on the
	// provider's servers. Gemini only; default off.
	CodeExecution *bool `json:"code_execution,omitempty"`
}

type CallPeerConfig struct {
	// Enabled registers the tool. Absent it, a hub daemon can still be
	// registered WITH by peers; it just can't call them.
	Enabled bool `json:"enabled,omitempty"`

	// Name renames the tool (default "call_peer"). Recipes with their
	// own vocabulary for delegation can match it. Note the permission
	// key follows the name: rename to "ask_operator" and the allow
	// pattern becomes "ask_operator:<peer>".
	Name string `json:"name,omitempty"`

	// Description replaces the model-facing description. Use it to
	// pin the prompt shape a fleet expects ("always name the cluster
	// and the namespace"); the built-in text explains the mechanics
	// but knows nothing about the deployment.
	Description string `json:"description,omitempty"`

	// TokenEnv names the env var holding the bearer token this agent
	// presents to peers. Empty means unauthenticated calls, which only
	// makes sense when the peers themselves run without
	// attach.token_env. Named-but-empty at call time is an error, not
	// an anonymous request.
	TokenEnv string `json:"token_env,omitempty"`

	// TimeoutSeconds bounds one delegated call end to end. Default 120;
	// ceiling 900. The callee runs a full agent turn, so this is not an
	// HTTP timeout — but it must stay short enough that a wedged peer
	// can't pin this agent's turn open indefinitely.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`

	// MaxResponseBytes caps how much of the peer's answer enters this
	// agent's context. Default 16384. Over the cap the answer is cut
	// and flagged truncated; the peer's session ID comes back either
	// way, so the full transcript stays reachable.
	MaxResponseBytes int `json:"max_response_bytes,omitempty"`
}

type CheckpointConfig struct {
	// Mode selects which parties can declare a task boundary.
	//
	// Values, strongest to weakest:
	//   - "model"    (default) — the model-facing mark_task_done tool,
	//     the operator's /done, and the Checkpointer heuristic are all
	//     live. Today's behavior.
	//   - "operator" — /done and the heuristic stay; mark_task_done is
	//     not registered, so the model cannot self-declare completion.
	//   - "off"      — no checkpointing at all. /done reports that the
	//     agent was built without a checkpointer.
	//
	// Empty == "model".
	//
	// "operator" exists for long-lived services (#905). mark_task_done's
	// description tells the model to use it "generously at natural task
	// boundaries", and its detail arg asks for a completion summary —
	// framing written for an interactive coding session. A daemon
	// consuming machine signals has no conversation about to shift to a
	// new task, so every inbox bundle after a closed incident looks like
	// a boundary; a live deployment produced sixteen mark_task_done
	// calls in one session and answered an unrelated operator question
	// with a completion report instead. A tool description outranks the
	// persona at the point of decision, and a recipe author cannot edit
	// it, so the lever has to be here.
	//
	// This field exists so a recipe can ship its posture instead of
	// relying on every invocation and deploy manifest remembering a
	// flag — same argument as SafetyConfig.Watchdog (#660). It also
	// splits what --no-checkpoint conflated: that flag removes the
	// model's trigger, the operator's /done, and the heuristic
	// together, which is not what its help text promised.
	//
	// CLI override: --checkpoint=model|operator|off. The older
	// --no-checkpoint is retained as an alias for "off".
	Mode string `json:"mode,omitempty"`
}

type CompactionConfig struct {
	// Threshold overrides the fallback utilization threshold used
	// when the current model's tier isn't classified or isn't in
	// ThresholdByTier. Pointer so absence is distinguishable from
	// the deliberate value 0 (which would disable compaction).
	// Must be in (0, 1) when set.
	Threshold *float64 `json:"threshold,omitempty"`

	// ThresholdByTier overrides per-tier defaults. Keys are tier
	// labels from pkg/modeltier ("frontier", "mid", "small"). Set
	// only the tiers you want to override; the rest take their
	// package defaults (0.85 / 0.65 / 0.35). Values must be in
	// (0, 1).
	//
	// Example — keep frontier sessions on the historical default
	// while compacting Flash/Haiku much earlier:
	//   "compaction": {
	//     "threshold_by_tier": { "small": 0.30 }
	//   }
	ThresholdByTier map[string]float64 `json:"threshold_by_tier,omitempty"`
}

type Config struct {
	Version     int               `json:"version"`
	Model       ModelConfig       `json:"model"`
	Permissions PermissionsConfig `json:"permissions,omitempty"`
	PathScope   PathScopeConfig   `json:"path_scope,omitempty"`
	Agent       AgentConfig       `json:"agent,omitempty"`
	ToolOutput  ToolOutputConfig  `json:"tool_output,omitempty"`
	Tools       ToolsConfig       `json:"tools,omitempty"`
	Subagents   []SubagentSpec    `json:"subagents,omitempty"`
	Hooks       hooks.Config      `json:"hooks,omitempty"`
	Mock        MockConfig        `json:"mock,omitempty"`
	OTEL        OTELConfig        `json:"otel,omitempty"`
	URLScope    URLScopeConfig    `json:"url_scope,omitempty"`
	Alerts      AlertsConfig      `json:"alerts,omitempty"`
	Attach      AttachConfig      `json:"attach,omitempty"`
	Pricing     PricingFileConfig `json:"pricing,omitempty"`
	UI          UIConfig          `json:"ui,omitempty"`
	Compaction  CompactionConfig  `json:"compaction,omitempty"`
	Checkpoint  CheckpointConfig  `json:"checkpoint,omitempty"`
	Session     SessionConfig     `json:"session,omitempty"`
	Safety      SafetyConfig      `json:"safety,omitempty"`

	// ContentRoots are operator-declared external directories trusted as
	// additional instruction/skill scopes, so an unmodified external agent
	// tree (e.g. a kube-agents checkout) can be consumed without vendoring a
	// copy. Paths are resolved relative to the agents dir. Each root is loaded
	// as its own trusted scope: instruction @include stays confined within the
	// root, and skills compose at precedence project > content_roots (listed
	// order) > home-agents > user. Empty = only the project root is trusted
	// (today's behavior exactly). CLI: --agents-content-dir (repeatable),
	// merged with this field. See docs/external-content-root-design.md.
	ContentRoots []string `json:"content_roots,omitempty"`
}

type ContextCacheConfig struct {
	// Enabled defaults to true (nil = ON). Set to false to disable
	// caching without touching the other fields.
	Enabled *bool `json:"enabled,omitempty"`
	// TTL is how long each Create/Update requests the cache live for.
	// Format: any string time.ParseDuration accepts (e.g. "6h", "30m").
	// Empty → 6h. Vertex caps at 24h.
	TTL string `json:"ttl,omitempty"`
	// Refresh triggers a background Update when time-to-expiry drops
	// below this value. Format matches TTL. Empty → 30min.
	Refresh string `json:"refresh,omitempty"`
}

type CostRateLimitConfig struct {
	PerMinute int  `json:"per_minute,omitempty"`
	Burst     int  `json:"burst,omitempty"`
	Disabled  bool `json:"disabled,omitempty"`
}

type MockConfig struct {
	Script string `json:"script,omitempty"`
	Strict bool   `json:"strict,omitempty"`
	Record string `json:"record,omitempty"`
}

type ModelConfig struct {
	Provider  string           `json:"provider,omitempty"`
	Name      string           `json:"name"`
	APIKey    string           `json:"api_key,omitempty"`
	Vertex    *VertexConfig    `json:"vertex,omitempty"`
	Anthropic *AnthropicConfig `json:"anthropic,omitempty"`
	// Pricing is a per-model rate override keyed by model name
	// (case-insensitive). Survives /model switches mid-session —
	// every model the operator routes to can carry its own rates.
	// Layered with .agents/pricing.json + ~/.core-agent/pricing.json
	// + the compiled-in fallback; see pkg/pricing for the
	// lookup chain. Previously a single *PricingConfig that matched
	// only Model.Name; PR core-agent/#NN renamed the JSON key
	// `pricing` from "{input_per_mtok, output_per_mtok}" to a map.
	Pricing PricingMap `json:"pricing,omitempty"`

	// BuiltinTools gates the PROVIDER's server-side built-in tools.
	// Absent (the common case) means every tool keeps its provider
	// default. See BuiltinToolsConfig — and note this is a different
	// axis from `tools.disable` / `--no-builtin-tools`, which govern
	// core-agent's own function tools.
	BuiltinTools *BuiltinToolsConfig `json:"builtin_tools,omitempty"`
}

type MultiSessionAuthConfig struct {
	// Kind selects the Authenticator implementation.
	// Recognized values:
	//   - "" or "bearer_table" — static token → identity table loaded
	//     from TableFile (default; v2.4)
	// Future: "oidc" / "mtls" / "k8s_sa" (interfaces designed; not
	// shipped in v2.4).
	Kind string `json:"kind,omitempty"`

	// TableFile is the path to users.json when Kind="bearer_table".
	// File must be mode 0600 or stricter (the loader rejects anything
	// laxer). Required when Kind="bearer_table" and Enabled=true.
	TableFile string `json:"table_file,omitempty"`
}

type MultiSessionConfig struct {
	// Enabled switches the attach listener from single-user mode
	// (daemon-level bearer token, no per-caller threading) to
	// multi-session mode (per-caller authentication, ACL enforcement,
	// audit log identity threading). Default false.
	Enabled bool `json:"enabled,omitempty"`

	// UsersDir is the directory holding per-caller instruction
	// overlays (Phase 3 / PR γ). Each subdirectory named after a
	// Caller's Identity may contain an .agents/ tree merged on top of
	// the daemon-wide instruction stack for sessions belonging to
	// that Caller. Empty disables the overlay path.
	UsersDir string `json:"users_dir,omitempty"`

	// Auth selects the Authenticator implementation and its
	// configuration. Only "bearer_table" is shipped in v2.4; OIDC /
	// JWT / mTLS / K8s ServiceAccount kinds are designed but
	// deferred.
	Auth MultiSessionAuthConfig `json:"auth,omitempty"`

	// AdminIdentities lists the Caller identities that bypass every
	// per-session authorization check (Admin role). Use sparingly —
	// these identities can read every session in the daemon.
	AdminIdentities []string `json:"admin_identities,omitempty"`

	// AllowAnonymous, when true, lets requests without a valid
	// credential resolve to the DefaultIdentity Caller instead of
	// returning 401. Dangerous in shared environments where every
	// unauthenticated request becomes the same Caller. Default false.
	AllowAnonymous bool `json:"allow_anonymous,omitempty"`

	// DefaultIdentity is the Caller.Identity stamped onto the
	// implicit anonymous Caller (when multi-session is disabled or
	// AllowAnonymous=true). Default "anon".
	DefaultIdentity string `json:"default_identity,omitempty"`

	// ProxyIdentities lists Caller identities permitted to assert
	// other Callers via the AssertedCallerHeader. Typical use:
	// chat-bot service-account identities ("sa:slack-bot") that
	// authenticate as themselves but speak on behalf of human users.
	// Empty disables the proxy path.
	ProxyIdentities []string `json:"proxy_identities,omitempty"`

	// AssertedCallerHeader is the header name a proxy Caller uses to
	// assert the effective identity. Default "X-Asserted-Caller".
	AssertedCallerHeader string `json:"asserted_caller_header,omitempty"`

	// SessionIdleTimeout bounds how long an in-memory session may
	// sit untouched before the eviction sweep removes it. Evicted
	// sessions remain resumable from disk (the ACL row stays);
	// the next Lookup re-resumes them lazily via the SessionResumer.
	//
	// Parsed via time.ParseDuration ("24h", "30m", "7d" all work).
	// Omitted or empty → default 24h. Explicit "0s" DISABLES the
	// sweep entirely — sessions stay in memory until the daemon
	// stops. Use "0s" for tiny local-dev daemons where memory
	// isn't a concern; use a shorter value for tight-budget pods.
	//
	// Only meaningful when Enabled=true and the daemon has an
	// aclStore wired (i.e., --session-db is set). See
	// docs/session-resume-design.md §"Lifecycle primitive".
	SessionIdleTimeout string `json:"session_idle_timeout,omitempty"`
}

type OTELConfig struct {
	Exporter string            `json:"exporter,omitempty"` // "none" | "console" | "otlp"
	Endpoint string            `json:"endpoint,omitempty"`
	Metrics  OTELMetricsConfig `json:"metrics,omitempty"`
}

type OTELMetricsConfig struct {
	Exporter       string `json:"exporter,omitempty"`
	PrometheusAddr string `json:"prometheus_addr,omitempty"`

	// SessionLabels controls whether per-session identity attributes
	// (session.id, app.name, user.id) are stamped on the usage
	// metrics. Absent/true — the default — preserves the per-session
	// series shape; false aggregates across sessions before export,
	// for fleet operators where per-session labels would blow up
	// series cardinality (many short-lived attach sessions × models).
	// Per-tool and per-turn histograms never carry session labels
	// regardless of this setting.
	SessionLabels *bool `json:"session_labels,omitempty"`
}

type PathScopeAllowEntry struct {
	Path   string `json:"path"`
	Access string `json:"access"`
}

type PathScopeConfig struct {
	Allow      []string              `json:"allow,omitempty"`
	AllowPaths []PathScopeAllowEntry `json:"allow_paths,omitempty"`
}

type PermissionsConfig struct {
	Mode  string   `json:"mode,omitempty"`  // "ask" | "allow" | "yolo" | "plan" | "acceptEdits"
	Allow []string `json:"allow,omitempty"` // pattern allowlist
	Deny  []string `json:"deny,omitempty"`  // pattern denylist

	// UseBuiltinAllow toggles core-agent's built-in conservative
	// read-only allowlist bundle. Defaults to true when nil (the
	// pointer carries an explicit "off" signal vs "unset"). false
	// drops the entire built-in bundle including any opt-ins in
	// BuiltinAllowExtras. See permissions/builtin_allow.go for the
	// bundle catalog.
	UseBuiltinAllow *bool `json:"use_builtin_allow,omitempty"`

	// BuiltinAllowExtras names additional built-in bundles to merge
	// on top of read_only when UseBuiltinAllow is on. Unknown names
	// fail at config-validation time rather than silently dropping
	// permissions. Known bundles: see permissions.KnownBundles().
	BuiltinAllowExtras []string `json:"builtin_allow_extras,omitempty"`

	// RequirePlanArtifact is the deprecated two-state spelling of
	// PlanMode: true means PlanModeRequired, absent/false means "no
	// opinion" (PlanMode, then the task profile, then off). It cannot
	// express PlanModeAdvisory, which is why PlanMode exists.
	//
	// Read it through ResolvedPlanMode rather than directly — a
	// consumer switching on this bool sees "off" for an advisory run
	// and would skip registering record_plan.
	//
	// Deprecated: set PlanMode instead. Removed in the next major.
	RequirePlanArtifact bool `json:"require_plan_artifact,omitempty"`

	// PlanMode controls the two things record_plan does — persist a
	// plan artifact, and gate mutating tools on one existing —
	// independently, because operators need them independently
	// (#215).
	//
	//   "off"       record_plan is not registered; no artifact, no gate.
	//   "advisory"  record_plan IS registered and the artifact persists
	//               to .agents/plans/plan-N.md, but NO mutating call is
	//               ever blocked on plan state. The audit surface
	//               without the two-turn ceremony — the shape an
	//               autonomous triage or alert-response agent wants.
	//   "required"  advisory plus the plan-first gating pre-check:
	//               mutating tool calls (write/edit/delete/bash, spawn
	//               family, MCP tools) are denied until the model calls
	//               record_plan. Read-only tools and record_plan itself
	//               remain allowed so research happens normally.
	//               Composes with every Mode — even ModeYolo denies
	//               before a plan is recorded; once recorded, the
	//               mode's usual semantics resume.
	//
	// Empty means unset: ResolvedPlanMode falls back to
	// RequirePlanArtifact, then to off. Prompting the model to
	// actually call record_plan in advisory mode is the recipe's job
	// (AGENTS.md / skill instructions) — the runtime only guarantees
	// the tool is there and the artifact lands.
	// See docs/plan-first-design.md.
	PlanMode string `json:"plan_mode,omitempty"`
}

type PricingConfig struct {
	InputPerMTok                float64 `json:"input_per_mtok,omitempty"`
	CachedInputPerMTok          float64 `json:"cached_input_per_mtok,omitempty"`
	CacheCreationInputPerMTok   float64 `json:"cache_creation_input_per_mtok,omitempty"`
	CacheCreation1hInputPerMTok float64 `json:"cache_creation_1h_input_per_mtok,omitempty"`
	OutputPerMTok               float64 `json:"output_per_mtok,omitempty"`
}

type PricingFileConfig struct {
	// Refresh enables the daily background fetch from Source into
	// ~/.core-agent/pricing.json's external section. Defaults to
	// true (most operators want fresh rates). Disable for
	// air-gapped pods or CI where outbound network is blocked or
	// undesirable.
	//
	// Pointer so the JSON unmarshaler can distinguish "unset
	// (default true)" from "explicit false". A bare `null` or
	// missing field yields the default.
	Refresh *bool `json:"refresh,omitempty"`

	// Source overrides the upstream URL the refresher fetches from.
	// Empty defaults to pricing.DefaultRefreshSource (LiteLLM's
	// model_prices_and_context_window.json). Override for mirrors
	// or internal pricing services.
	Source string `json:"source,omitempty"`
}

type PricingMap map[string]PricingConfig

type PromptCacheConfig struct {
	// Enabled defaults to true (nil = ON). Set to false to disable
	// caching for this provider.
	Enabled *bool `json:"enabled,omitempty"`

	// TTL is the breakpoint lifetime requested on cache writes:
	// "5m" (default) or "1h". Empty means 5m.
	//
	// The trade is a real one and the reason this is a knob rather
	// than a default: a 1-hour breakpoint bills writes at 2x base
	// input where a 5-minute one bills 1.25x, so it pays only when
	// the gaps between turns routinely exceed five minutes — a
	// human-paced review session, a cron-driven agent, an operator
	// approving each tool call. A tight agentic loop refreshes the
	// 5-minute window on every turn and should stay on the default,
	// where the extra 0.75x would be pure loss.
	//
	// Both TTLs are priced separately and the response reports which
	// one each write used, so the ledger tells the truth either way
	// (#770).
	TTL string `json:"ttl,omitempty"`
}

type SafetyConfig struct {
	// SmallTierParent controls what happens when an interactive
	// session starts on a small-tier parent model (Flash/Haiku-class).
	// These models work well as agentic_* subtask workers (#118-122)
	// but loop and stall as the parent for long interactive sessions
	// — see #121 for the smoke that motivated this guard.
	//
	// Values: "warn" (default) logs a one-line operator notice but
	// proceeds; "refuse" exits with a config-error code; "allow"
	// suppresses the check entirely. Empty == "warn".
	//
	// The check is skipped regardless when:
	//   - `-p` one-shot mode (operator knows what they're doing;
	//     might be a script invoking Flash on purpose)
	//   - `--yolo` (trust-the-operator mode)
	//   - The parent's tier doesn't classify (unknown model)
	//
	// CLI override: --small-tier-parent=warn|refuse|allow.
	SmallTierParent string `json:"small_tier_parent,omitempty"`

	// Watchdog selects the behavioral watchdog's posture — the
	// runaway-tool-loop backstop from #123/#623.
	//
	// Values: "off" (no observation), "warn" (observe the tool-call
	// stream and log structured alerts, but never halt), "feedback"
	// (same, plus the alert is injected into the model's next-turn
	// context as a "[watchdog]" block so the party making the looping
	// call finds out about it — #159), "enforce" (all of that plus a
	// turn-error of kind=watchdog; the agent refuses new turns until
	// Agent.ResetWatchdog clears it).
	//
	// The values form a ladder — each includes the one before it. In
	// particular "enforce" injects too: an operator reset resumes a
	// model whose context still ends in the loop it was halted for,
	// and without the observation the next turn re-trips.
	//
	// "feedback" is a correction, not a backstop: nothing stops a model
	// that reads the observation and loops anyway. Unattended runs want
	// "enforce".
	//
	// Empty == unset, which resolves to a *mode-dependent* default:
	// "enforce" for unattended runs (-p one-shot, --no-repl daemon,
	// or a non-TTY stdin) and "warn" for interactive REPL/TUI runs.
	// An unattended daemon has no operator watching the alert stream,
	// so observe-and-log is not a backstop there (#642).
	//
	// This field exists so a recipe can ship its own backstop instead
	// of relying on every invocation and deploy manifest remembering
	// --watchdog=enforce (#660).
	//
	// CLI override: --watchdog=off|warn|feedback|enforce.
	Watchdog string `json:"watchdog,omitempty"`

	// BashSearchGate controls what happens when the model reaches for
	// a search-shaped shell command — `grep -rn foo .`, `find . -name
	// '*.go'`, `rg`, `ag`, `ack`, `fd` — while the native `grep` /
	// `glob` tools are registered to do the same job.
	//
	// Bash-as-grep is a training prior strong enough that advisory
	// tool-description hints bounce off it: probe data in
	// docs/gemini-tier1-followup-plan.md measured a Gemini variant
	// picking `bash` for search 15/27 times with the structured tools
	// right there in its catalog, and the description literally saying
	// "PREFERRED over bash grep". A description is read once at
	// registration and never reinforced; a refusal is in-context,
	// immediate, and names the tool to use instead (#158).
	//
	// Values: "enforce" (default) refuses the call with a structured
	// error naming the native equivalent; "warn" runs the command but
	// attaches a notice to the tool result; "allow" disables the check.
	// Empty == "enforce".
	//
	// This is a steering control, not a security boundary: it refuses
	// a *shape*, and only the shape a model reaches for by reflex.
	// Everything else bash can do — tests, builds, git, formatters —
	// is untouched, which is the point. `--disable-tools=bash` is the
	// blunt version and it takes `go test` with it.
	//
	// The gate only refuses what it can redirect. Disable `grep` and
	// `glob` here in tools.disable and it goes inert rather than
	// refusing with a pointer to tools that aren't in the catalog.
	//
	// CLI override: --bash-search-gate=enforce|warn|allow.
	BashSearchGate string `json:"bash_search_gate,omitempty"`
}

type SessionConfig struct {
	// TaskClass is the operator-declared task class. Must be one
	// of pkg/taskclass.Classes() ("debug" | "implement" | "chat"
	// | "research" | "review") or empty. When set, the CLI applies
	// the matching Profile to whichever flags the operator left
	// unspecified (--model, --ask, compaction threshold, etc.).
	// Explicit CLI flags always win over the task profile.
	//
	// Useful for project-local defaults — e.g. an infra repo's
	// .agents/config.json sets "debug" because debugging is what
	// happens there; operators get the right defaults without
	// having to remember --task=debug on every invocation.
	TaskClass string `json:"task_class,omitempty"`
}

type SpawnAgentConfig struct {
	// SyncWaitTimeout bounds how long `spawn_agent {wait: true}` holds
	// the parent's turn open, as a time.Duration string ("10m").
	// Omitted/empty keeps the 5m default.
	//
	// The cap is on the *wait*, not on the subagent: past it the tool
	// returns and the subagent keeps running, its result delivered on
	// a later turn as a pushed report. So raising this trades parent
	// latency for the parent seeing the answer in the turn that asked
	// for it — which is what a deep diagnostic wants, since a parent
	// that gets a timeout tends to redo the work itself (#692).
	//
	// An explicit "0s" removes the cap: the wait then ends when the
	// subagent finishes on its own turn/wallclock budget, or when the
	// parent's context is canceled. That is a real setting for a
	// recipe with tight per-subagent budgets, not a way to hang — but
	// it does mean the subagent's budgets are the only bound left.
	// Negative is rejected.
	SyncWaitTimeout string `json:"sync_wait_timeout,omitempty"`
}

type SubagentBudgets struct {
	MaxTurns            int     `json:"max_turns,omitempty"`
	MaxCostUSD          float64 `json:"max_cost_usd,omitempty"`
	MaxWallclockSeconds int     `json:"max_wallclock_seconds,omitempty"`
}

type SubagentSpec struct {
	Name         string       `json:"name"`
	Description  string       `json:"description,omitempty"`
	Instructions string       `json:"instructions,omitempty"`
	Model        *ModelConfig `json:"model,omitempty"`
	MaxDepth     int          `json:"max_depth,omitempty"`
	Tools        []string     `json:"tools,omitempty"`
	MCP          []string     `json:"mcp,omitempty"`
	Skills       []string     `json:"skills,omitempty"`
	Root         string       `json:"root,omitempty"`

	// Budgets bounds one delegation to this subagent. Honored on BOTH
	// doors the subagent is reachable through — as a parent tool call
	// and by spawn_agent reference — because a cap that binds only one
	// of them is worse than none: the operator reads the config and
	// believes the subagent is bounded.
	//
	// Zero/omitted means "no declared cap": the async door then falls
	// back to the manager's defaults (50 turns / $1 / 10m), and the
	// synchronous door stays unbounded, which is what it has always
	// been. A per-spawn override may only tighten what is declared here.
	Budgets *SubagentBudgets `json:"budgets,omitempty"`
}

type ToolOutputConfig struct {
	MaxBytes int                              `json:"max_bytes,omitempty"`
	MaxLines int                              `json:"max_lines,omitempty"`
	PerTool  map[string]ToolOutputPerToolCaps `json:"per_tool,omitempty"`
}

type ToolOutputPerToolCaps struct {
	MaxBytes int `json:"max_bytes,omitempty"`
	MaxLines int `json:"max_lines,omitempty"`
}

type ToolsConfig struct {
	Disable       []string            `json:"disable,omitempty"`
	WaitAndVerify WaitAndVerifyConfig `json:"wait_and_verify,omitempty"`
	CallPeer      CallPeerConfig      `json:"call_peer,omitempty"`
	SpawnAgent    SpawnAgentConfig    `json:"spawn_agent,omitempty"`
}

type UIConfig struct {
	// Theme picks the rendering style for the core-tui surface.
	// Three reserved buckets:
	//   - "auto"  (default) — detect via terminal background query.
	//   - "dark"            — force dark theme; skips the OSC-11 query.
	//   - "light"           — force light theme; skips the OSC-11 query.
	// Any other lowercase identifier (letters, digits, dash,
	// underscore) is treated as a named theme from core-tui's
	// BuiltinThemes registry (e.g. "gopher", "google"). The /theme
	// picker writes back through PersistThemeChoice using these
	// names, so the field round-trips picker choices. Unknown
	// names fall back to the auto path at launch.
	Theme string `json:"theme,omitempty"`

	// Mouse enables terminal mouse capture so the wheel scrolls the
	// chat viewport. When enabled, plain click-drag no longer selects
	// text — terminals route around the capture when Shift is held
	// (Shift-drag to select, copy as usual). Pointer so unset means
	// "use the default" (true). Toggle at runtime with /mouse.
	Mouse *bool `json:"mouse,omitempty"`
}

type URLScopeConfig struct {
	Allow                  []string                     `json:"allow,omitempty"`
	Deny                   []string                     `json:"deny,omitempty"`
	MaxBodyBytes           int                          `json:"max_body_bytes,omitempty"`
	TimeoutSeconds         int                          `json:"timeout_seconds,omitempty"`
	Headers                map[string]map[string]string `json:"headers,omitempty"`
	AllowMetadataEndpoints bool                         `json:"allow_metadata_endpoints,omitempty"`

	// Proxy controls outbound proxying for fetch_url (#429):
	//
	//   ""       (default) — no proxy. HTTP_PROXY/HTTPS_PROXY env
	//            vars are deliberately IGNORED: with a proxy in the
	//            path, hostname targets are resolved AT the proxy,
	//            outside the SSRF guard's resolve-validate-pin dial,
	//            so proxying must be an explicit operator decision,
	//            not ambient environment.
	//   "env"    — honor the standard proxy environment variables
	//            (HTTP_PROXY / HTTPS_PROXY / NO_PROXY).
	//   <url>    — route through this fixed proxy URL
	//            (http://, https://, or socks5://).
	//
	// In either non-empty mode the operator delegates private/
	// metadata-range SSRF policy for hostname targets to the proxy;
	// literal-IP targets are still screened locally on the initial
	// URL and every redirect hop.
	Proxy string `json:"proxy,omitempty"`
}

type VertexConfig struct {
	Project  string `json:"project"`
	Location string `json:"location"`

	// ContextCache toggles Vertex explicit context caching for the
	// stable request prefix (system instruction + tools). When nil
	// or Enabled != false, caching is ON — the daemon creates a
	// CachedContent resource on the first turn and stamps it onto
	// every subsequent turn's GenerateContentConfig.CachedContent.
	// See docs/vertex-context-caching-design.md and
	// internal/vertexcache/manager.go.
	ContextCache *ContextCacheConfig `json:"context_cache,omitempty"`
}

type WaitAndVerifyConfig struct {
	// PollAllow names tools that may be polled despite not being
	// classified read-only by the runtime. This exists for MCP: ADK's
	// MCP adapter does not surface the server's readOnlyHint
	// annotation, so an MCP tool lands on the fail-safe "mutating"
	// side of tools.IsReadOnlyTool and would be refused. Listing a
	// tool here is the operator asserting it only observes state.
	//
	// For a server that is read-only in its entirety — a provider's
	// /mcp/read-only endpoint — prefer `read_only: true` on the
	// ServerSpec in mcp.json (#693), which classifies every tool the
	// server exposes. This list is then for the finer case: one
	// read-only tool on a server that also mutates.
	//
	// Names are the ones the model sees, i.e. namespaced for MCP
	// ("gke_get_pod" and not "get_pod").
	PollAllow []string `json:"poll_allow,omitempty"`

	// MaxTimeoutSeconds caps the total wall clock one wait may spend.
	// Default 300. A call asking for more is rejected rather than
	// silently shortened.
	MaxTimeoutSeconds int `json:"max_timeout_seconds,omitempty"`

	// MaxAttempts caps how many times one wait may call its target.
	// Default 60.
	MaxAttempts int `json:"max_attempts,omitempty"`
}