permconfig

type Config struct {
	// Providers holds strict, operator-tier custom LLM provider definitions. Project
	// values are ignored by Resolver with a value-free warning.
	Providers ProviderDefinitions `yaml:"providers"`
	// ProviderOverrides holds strict operator-tier endpoint overrides for eligible
	// built-in providers. It is never accepted from a project workspace.
	ProviderOverrides ProviderOverrides `yaml:"provider_overrides"`
	// Permissions holds the allow/ask/deny rule-spec lists plus the child-scoped
	// `subagent:` block.
	Permissions Permissions `yaml:"permissions"`
	// Guardrails holds the OPERATOR-TIER LLM-content-checker config (issue #27). It
	// is parsed STRICTLY (unknown sub-keys = error, like permissions:) so a typo
	// cannot silently disable a guardrail. It is honoured ONLY from the user-global +
	// CLI tiers; a project-tier file's guardrails: block is IGNORED with a WARN (a
	// project repo weakening/disabling a checker is a security DOWNGRADE — the usual
	// tighten-only gate reverses here). The presence flag (whether the key appeared at
	// all) is tracked via GuardrailsPresent so the resolver can WARN about an ignored
	// project block. A nil Guardrails means the key was absent.
	Guardrails *GuardrailsSection `yaml:"guardrails"`
	// Posture is the OPERATOR-TIER posture-ladder scalar (the graduated trust/
	// automation tier: strict/trusted/auto/yolo). Like Guardrails it is honoured ONLY
	// from the user-global + CLI tiers; a project-tier file's posture: key is IGNORED
	// with a WARN (a project repo RAISING the automation posture — e.g. posture: yolo
	// — is a security DOWNGRADE the tighten-only project gate forbids, the fail-closed
	// core of this feature). Empty = absent (the resolver returns "" and composition
	// keeps the CLI/default). The composition layer parses the string; permconfig only
	// reads the scalar.
	Posture string `yaml:"posture"`
	// Models holds the per-slot model config (ADR 0030): the `models.slots` /
	// `models.aliases` maps, the session `default`, and the operator-tier `allowlist`
	// cap. At the OPERATOR tier (user-global + CLI) all fields are honoured. At the
	// PROJECT tier (Phase 4) a models: block is honoured WITHIN the operator allowlist
	// on a TRUSTED workspace (slots/aliases/default only); with no operator allowlist
	// it stays WARN-ignored (the opt-in — byte-identical to pre-Phase-4), and a
	// project-tier allowlist: key is always ignored with a WARN (non-wideable cap).
	// The TOP `models:` mapping is parsed STRICTLY (an unknown key like `slotz:`
	// errors), the inner slots/aliases maps stay free-form (composition validates the
	// slot keys fail-soft). A nil Models means the key was absent. The composition
	// layer reads the maps; permconfig only carries them.
	Models *ModelsSection `yaml:"models"`
	// ReasoningEffort is the OPERATOR-TIER reasoning-effort scalar (ADR 0055: the
	// neutral vocabulary "" / "auto" / "low" / "medium" / "high" / "xhigh" / "max").
	// Like Posture it is honoured ONLY from the user-global + CLI tiers; a
	// project-tier file's reasoning-effort: key is IGNORED with a WARN
	// (operator-tier only, for consistency — a project cannot raise the model's
	// reasoning spend). Empty = absent (the resolver returns "" and composition uses
	// the provider default). The composition layer interprets + clamps the token;
	// permconfig only reads the scalar.
	ReasoningEffort string `yaml:"reasoning-effort"`
	// PlanModeAutoApprove is the OPERATOR-TIER plan-mode-auto-approve flag (issue
	// #206 Wave 6a). Like Posture/ReasoningEffort it is honoured ONLY
	// from the user-global + CLI tiers; a project-tier file's plan-mode-auto-approve:
	// key is IGNORED with a WARN (operator-tier only — a project repo enabling
	// autonomous plan approval is a security DOWNGRADE). false = absent (the resolver
	// returns false and composition keeps the default OFF). The composition layer
	// interprets the bool; permconfig only reads the scalar.
	PlanModeAutoApprove bool `yaml:"plan-mode-auto-approve"`
	// Learning configures optional completed-trajectory observation. The subtree is
	// strict; composition parses the closed off/review/auto mode vocabulary.
	Learning *LearningSection `yaml:"learning"`
	// Steer is the OPERATOR-TIER mid-run steer knob (steer-while-running, issue
	// #512): enable (default) or disable the mid-run steer inbox. Like
	// Posture/ReasoningEffort it is honoured ONLY from the user-global + CLI tiers;
	// a project-tier file's steer: key is IGNORED with a WARN (operator-tier only —
	// the harness's operator surface is not a project repo's to flip, in either
	// direction). It is a *bool so ABSENT is distinguishable from an explicit false:
	// nil = absent (the resolver reports not-present and composition keeps the
	// DEFAULT-ON); a non-nil value is honoured (composition maps steer: false onto
	// the opt-OUT DisableSteer).
	Steer *bool `yaml:"steer"`
	// OpenRouter holds the OPERATOR-TIER OpenRouter downstream-provider routing
	// config (issue #480): a per-model preferred DOWNSTREAM provider order, sent as
	// OpenRouter's `provider` request-body object. Like Guardrails/Posture it is
	// honoured ONLY from the user-global + CLI tiers; a project-tier file's
	// openrouter: block is IGNORED with a WARN (steering requests to a particular
	// downstream is a spend/compliance/capability decision the operator owns — the
	// same operator-only discipline as default_provider/allowlist/router). It is
	// parsed STRICTLY (unknown sub-keys = error, like guardrails:/router:) so a
	// typo cannot silently drop a routing preference. A nil OpenRouter means the
	// key was absent. The composition layer reads + validates the maps; permconfig
	// only carries them.
	OpenRouter *OpenRouterSection `yaml:"openrouter"`
	// MCP holds named global Streamable HTTP MCP server profiles. It is strict and
	// OPERATOR-TIER ONLY: project files cannot choose endpoints, authentication,
	// credential references, or egress policy. Values are metadata only; parsing
	// never reads an environment variable, opens a credential store, or performs I/O.
	MCP *MCPSection `yaml:"mcp"`
	// Retention is the strict, versioned operator-only automatic session cleanup policy.
	// Project-tier values are ignored; explicit CLI flags remain the highest precedence.
	Retention *RetentionSection `yaml:"retention"`
	// StorageManagement names the verified OIDC identities allowed to operate on
	// process-wide storage. It is strict and operator-tier only.
	StorageManagement *StorageManagementSection `yaml:"storage_management"`
	// TemporaryStorage controls managed command temporary storage. It is strict and
	// read exclusively from the user-global settings.yaml; project-tier and explicit
	// CLI configuration values are ignored by the Resolver.
	TemporaryStorage *TemporaryStorageSection `yaml:"temporary_storage"`
}

type ContextWindows map[string]map[string]int

type GuardrailRuleSpec struct {
	// Match is the tool-name matcher (exact / "prefix*" / "*").
	Match string `yaml:"match"`
	// Phases lists "pre"/"post"; empty = both.
	Phases []string `yaml:"phases"`
	// Mode is "block"/"sanitize"/"advisory"; empty defaults to block.
	Mode string `yaml:"mode"`
	// Prompt overrides the built-in inspection rubric.
	Prompt string `yaml:"prompt"`
	// FailClosed flips the fail-open default for enforcing modes.
	FailClosed bool `yaml:"failClosed"`
	// FailClosedPresent reports whether the failClosed key was explicitly set in
	// the YAML — a bool can't distinguish "false" from "not set", so this lets the
	// global onCheckerDown toggle distinguish a per-rule explicit opt-out from an
	// unset rule that should inherit the global.
	FailClosedPresent bool `yaml:"-"`
}

type GuardrailsSection struct {
	// Model is the checker model id / alias. Empty leaves the CLI --guardrails-model
	// to supply it; a value here is overridden by the CLI flag when both are set.
	Model string `yaml:"model"`
	// MinContentBytes skips the checker for content shorter than this. 0 = check all.
	MinContentBytes int `yaml:"minContentBytes"`
	// Disabled is the YAML-level kill switch (the CLI --guardrails=off also sets it).
	Disabled bool `yaml:"disabled"`
	// OnCheckerDown sets the global posture when the checker model is unavailable
	// (error/timeout): "warn" (default, fail-open) or "fail" (fail-closed for all
	// rules). Per-rule failClosed overrides: failClosed:true tightens even under
	// warn; failClosed:false (explicit) loosens even under fail. Empty = warn.
	OnCheckerDown string `yaml:"onCheckerDown"`
	// DefaultMode sets the enforcement mode for the built-in default rules when no
	// explicit rules are configured: "block" (default), "advisory", or "sanitize".
	// An explicit rules list replaces the defaults entirely (this key is ignored).
	DefaultMode string `yaml:"defaultMode"`
	// Escape is the ADR-0080 escape knob: when true AND a checker model is
	// configured, an out-of-root FS escape at posture auto routes through the
	// guardrail checker (an unsafe verdict denies; a checker error fails closed
	// to the write-escape Ask). Default false = the un-routed posture table.
	Escape bool `yaml:"escape"`
	// Rules is the guardrail rule list.
	Rules []GuardrailRuleSpec `yaml:"rules"`
}

type LearningAutomaticSection struct {
	// Cooldown is the per-principal weighted-admission cooldown; zero disables it.
	Cooldown time.Duration `yaml:"cooldown"`
	// Window is the sliding count/token window, strictly 1m..24h.
	Window time.Duration `yaml:"window"`
	// MaxReflections is the global count cap; zero disables automatic reflection.
	MaxReflections int `yaml:"max_reflections"`
	// MaxTokens is the global reserved-token cap; zero disables automatic reflection.
	MaxTokens int `yaml:"max_tokens"`
	// MaxReflectionsPerPrincipal is the per-principal count cap; zero disables automatic reflection.
	MaxReflectionsPerPrincipal int `yaml:"max_reflections_per_principal"`
	// MaxTokensPerPrincipal is the per-principal reserved-token cap; zero disables automatic reflection.
	MaxTokensPerPrincipal int `yaml:"max_tokens_per_principal"`
}

type LearningSection struct {
	// Mode controls automatic completed-trajectory observation: off (default; no
	// automatic reflection), review (signal-gated reflection stages durable proposals
	// without memory writes), or auto (stage first, then conservatively promote only
	// eligible non-conflicting facts). Operator settings establish the ceiling;
	// project settings may only tighten it under off < review < auto and never raise
	// autonomy. It does not override separately configured maintenance schedules such
	// as --user-model-consolidate-interval.
	Mode string `yaml:"mode"`
	// Sensitivity controls weighted automatic admission. Empty means balanced.
	Sensitivity string `yaml:"sensitivity"`
	// Skills controls learned-skill lifecycle policy.
	Skills *LearningSkillsSection `yaml:"skills"`
	// Automatic is operator-only admission policy. Standard non-off composition
	// applies it through a durable ledger, making count/token windows, cooldown,
	// and deduplication deployment-wide across cooperating processes.
	Automatic *LearningAutomaticSection `yaml:"automatic"`
}

type LearningSkillsSection struct {
	// Activation is validated (default for Auto) or evaluated. Project settings
	// may only tighten validated to evaluated.
	Activation string `yaml:"activation"`
}

type MCPAuthProfile struct {
	// Mode is exactly none, static_bearer, or oauth.
	Mode string `yaml:"mode"`
	// StaticBearer names the bearer-token environment reference.
	StaticBearer *MCPStaticBearerProfile `yaml:"static_bearer"`
	// OAuth declares the OAuth identity, client, credentials, scopes, and network policy.
	OAuth *MCPOAuthProfile `yaml:"oauth"`
}

type MCPBrokerProfile struct {
	// CallbackURL is required exactly when broker mode contains an OAuth route. It must be an absolute HTTPS URL without userinfo, query, or fragment; an omitted path or / is normalized to /.
	CallbackURL string `yaml:"callback_url"`
}

type MCPCIMDClientProfile struct {
	// DocumentURL is the required HTTPS metadata-document URL.
	DocumentURL string `yaml:"document_url"`
}

type MCPDCRClientProfile struct {
	// DiscoveryURL is the required HTTPS authorization-server metadata URL.
	DiscoveryURL string `yaml:"discovery_url"`
}

type MCPEnvironmentCredentialProfile struct {
	// CredentialEnv is a MECATL_* environment variable containing the opaque credential record.
	CredentialEnv string `yaml:"credential_env"`
	// AllowProcessLocalRefresh permits refreshed credentials to live only in this process.
	AllowProcessLocalRefresh bool `yaml:"allow_process_local_refresh"`
}

type MCPLocalCredentialProfile struct {
	// Root is the required absolute credential-store root.
	Root string `yaml:"root"`
	// KeyEnv is a MECATL_* environment variable name containing the encryption key.
	KeyEnv string `yaml:"key_env"`
}

type MCPOAuth2UpstreamProfile struct {
	AuthorizationEndpoint string `yaml:"authorization_endpoint"`
	// TokenEndpoint is a canonical HTTPS URL with no query string or fragment:
	// the hardened runtime token client pins the exact origin and controls the
	// request query itself.
	TokenEndpoint string `yaml:"token_endpoint"`
}

type MCPOAuthClientProfile struct {
	// Mode is exactly preregistered, cimd, or dcr.
	Mode string `yaml:"mode"`
	// Preregistered declares a confidential client registered with the issuer.
	Preregistered *MCPPreregisteredClientProfile `yaml:"preregistered"`
	// CIMD declares an HTTPS client-id metadata document URL.
	CIMD *MCPCIMDClientProfile `yaml:"cimd"`
	// DCR declares an RFC 8414 metadata URL for RFC 7591 registration.
	DCR *MCPDCRClientProfile `yaml:"dcr"`
}

type MCPOAuthCredentialProfile struct {
	// Mode is exactly local or environment.
	Mode string `yaml:"mode"`
	// Local declares encrypted mutable credentials rooted at an absolute path.
	Local *MCPLocalCredentialProfile `yaml:"local"`
	// Environment declares one externally provisioned read-only credential record.
	Environment *MCPEnvironmentCredentialProfile `yaml:"environment"`
}

type MCPOAuthNetworkProfile struct {
	// AdditionalOrigins lists canonical exact origins additionally allowed for OAuth traffic.
	AdditionalOrigins []string `yaml:"additional_origins"`
	// PrivateOrigins lists allowed origins that may resolve only to RFC1918 IPv4 or ULA IPv6 addresses. Loopback, link-local, metadata, unspecified, multicast, mapped, public, and other special addresses remain denied.
	PrivateOrigins []string `yaml:"private_origins"`
	// MaxRedirects is the redirect bound, from zero through five.
	MaxRedirects int `yaml:"max_redirects"`
}

type MCPOAuthProfile struct {
	// Profile is the required global-mode credential identity profile and is forbidden in broker mode.
	Profile string `yaml:"profile"`
	// Principal is the required global-mode credential identity principal and is forbidden in broker mode.
	Principal string `yaml:"principal"`
	// Issuer is the canonical exact origin used by OIDC discovery. It is forbidden
	// when Upstream explicitly selects generic OAuth2.
	Issuer string `yaml:"issuer"`
	// Upstream optionally selects OIDC discovery or explicit generic OAuth2.
	// Omitted defaults to OIDC.
	Upstream *MCPOAuthUpstreamProfile `yaml:"upstream"`
	// Client selects exactly one preregistered, CIMD, or DCR client declaration.
	Client MCPOAuthClientProfile `yaml:"client"`
	// Scopes is the non-empty allowlist of OAuth scopes the client may request.
	Scopes []string `yaml:"scopes"`
	// RequestRefreshToken asks the authorization server for refresh capability.
	RequestRefreshToken bool `yaml:"request_refresh_token"`
	// Credentials selects one global-mode local or environment credential source and is forbidden in broker mode.
	Credentials MCPOAuthCredentialProfile `yaml:"credentials"`
	// Network is required. Global profiles enforce its exact-origin egress policy;
	// broker OAuth accepts only an explicit empty mapping until ToolHive can enforce it equivalently.
	Network *MCPOAuthNetworkProfile `yaml:"network"`
	// Tools optionally declares this protected backend's tool catalogue
	// statically. Declarations are visible before connection; the first call
	// starts ToolHive's aggregate authorization for every protected backend.
	// The granted bundle unlocks the declared surface only. Omitted, the backend
	// remains discoverable only through pre-prompt workspace enrollment.
	Tools []MCPStaticToolProfile `yaml:"tools"`
}

type MCPOAuthUpstreamProfile struct {
	Mode   string                    `yaml:"mode"`
	OAuth2 *MCPOAuth2UpstreamProfile `yaml:"oauth2"`
}

type MCPPreregisteredClientProfile struct {
	// ID is the required preregistered OAuth client identifier.
	ID string `yaml:"id"`
	// SecretEnv is a MECATL_* environment variable name containing the client secret.
	SecretEnv string `yaml:"secret_env"`
}

type MCPSection struct {
	// Mode selects global or broker authority. Empty uses the command-root default.
	Mode string `yaml:"mode"`
	// Broker contains options meaningful only in broker mode.
	Broker MCPBrokerProfile `yaml:"broker"`
	// Servers is the ordered list of neutral Streamable HTTP route declarations.
	Servers []MCPServerProfile `yaml:"servers"`
}

type MCPServerProfile struct {
	// Name is an ASCII [A-Za-z0-9_]+ identifier, unique case-insensitively.
	Name string `yaml:"name"`
	// URL is an absolute HTTP(S) endpoint without userinfo or a fragment.
	URL string `yaml:"url"`
	// Auth selects exactly one of none, static_bearer, or oauth.
	Auth MCPAuthProfile `yaml:"auth"`
}

type MCPStaticBearerProfile struct {
	// TokenEnv is a MECATL_* environment variable name containing the opaque token.
	TokenEnv string `yaml:"token_env"`
}

type MCPStaticToolProfile struct {
	Name        string          `yaml:"name"`
	Description string          `yaml:"description"`
	InputSchema json.RawMessage `yaml:"input_schema"`
	ReadOnly    bool            `yaml:"read_only"`
}

type ModelsSection struct {
	// Slots binds a slot name (a call-slot "compaction"/"ask-reviewer"/"guardrail" or
	// a tier "cheap"/"fast"/"reasoning") to a model selector (alias or concrete id).
	Slots map[string]string `yaml:"slots"`
	// Aliases binds a short alias to a concrete model id (merged onto the CLI
	// --model-alias map, CLI winning per key).
	Aliases map[string]string `yaml:"aliases"`
	// Default is the session-default model selector (alias or concrete id). It is the
	// project-overridable session default (ADR 0030 Phase 4) — within the operator
	// allowlist; the operator's own Default is uncapped. Empty = absent.
	Default string `yaml:"default"`
	// Subagent is the OPERATOR-TIER def-less child-default model selector (alias or
	// concrete id): the settings.yaml twin of the --subagent-model flag (issue #288).
	// It sets the global default model for every Subagent / Parallel-branch / team-member
	// child that does not pin its own model (via an agent definition or a per-call
	// override). Operator-tier ONLY: a project-tier subagent: is IGNORED with a WARN (the
	// child-default model is an operator decision — the same operator-only captureModels
	// discipline as default_provider/allowlist/router). The CLI --subagent-model WINS when
	// both are set. Validated FAIL-FAST at Build (normalizeSubagentModel): a value that
	// does not resolve to a usable model id is a startup error (unlike fail-soft
	// models.default). Empty = absent (the flag/inherit-parent behaviour is unchanged).
	Subagent string `yaml:"subagent"`
	// DefaultProvider is the OPERATOR-TIER deployment-wide default provider id (e.g.
	// openai, openrouter, anthropic, toolhive). It mirrors the --default-provider flag
	// (app.Config.DefaultProvider) so an operator can declare "toolhive is my default
	// despite my API key" persistently in settings.yaml without unsetting the key. It
	// feeds the UNCHANGED preferredDefaultProvider ladder as an explicit override — it
	// does NOT lower the precedence of key-driven providers. Operator-tier only: a
	// project-tier default_provider: is IGNORED with a WARN (the same operator-only
	// captureModels discipline as posture/guardrails/allowlist). Validated FAIL-FAST at
	// Build (validateDefaultModel): an unknown/unavailable provider is a startup error.
	// Empty = absent (the ladder's preferred default wins). The name pair
	// (default = model, default_provider = provider) mirrors the wire grammar exactly.
	DefaultProvider string `yaml:"default_provider"`
	// Allowlist is the OPERATOR-TIER, non-wideable cap (ADR 0030 Phase 4): the set of
	// model selectors (alias names and/or concrete ids) a PROJECT-tier models: block
	// may bind to. An empty/absent allowlist means project models stay WARN-ignored
	// (the opt-in: no cap ⇒ no project override, byte-identical to pre-Phase-4). It is
	// honoured ONLY from the operator tiers; a project-tier allowlist: key is ignored
	// with a WARN (a project cannot widen its own cap).
	Allowlist []string `yaml:"allowlist"`
	// Router is the OPERATOR-TIER semantic Subagent model-router taxonomy (ADR 0031,
	// Phase 5; enable model superseded by ADR 0042): a classifier slot, the routing
	// categories, the default category, and the YAML kill-switch. It is operator-tier
	// ONLY — a project-tier router: sub-block is STRIPPED with a WARN (the taxonomy is
	// an autonomous-spend/capability decision the operator owns, like the allowlist).
	// nil/absent = no taxonomy ⇒ the router is OFF (byte-identical, silent). Per ADR
	// 0042 the TAXONOMY is the enable: a non-empty router: with categories turns the
	// router ON unless `disabled: true` (or the CLI kill-switch) forces it off — the
	// guardrails-parity enable model, replacing 0031's flag-to-enable.
	Router *RouterSection `yaml:"router"`
	// ContextWindows is the OPERATOR-TIER exact provider ID → exact final model ID
	// → total context token override map. It is intentionally not a selector map:
	// aliases and slots are resolved before this lookup, and project values are ignored.
	ContextWindows ContextWindows `yaml:"context_windows"`
}

type OpenRouterModelRoute struct {
	// Order lists downstream provider slugs (lowercase-kebab, e.g. "anthropic",
	// "google-vertex", "deepinfra/turbo") tried in order. Setting it disables
	// OpenRouter's default price load-balancing. Base-slug matching applies:
	// "google-vertex" matches all its regions/variants (service tiers excepted).
	Order []string `yaml:"order"`
	// AllowFallbacks, when explicitly false, pins the request to Order with no
	// fallback to other downstreams. Omit the key to keep OpenRouter's default
	// (true); set it to false to disable fallback.
	AllowFallbacks *bool `yaml:"allow_fallbacks"`
}

type OpenRouterSection struct {
	// Models maps a model id (or alias, resolved in composition) to its
	// downstream-provider routing preference.
	Models map[string]OpenRouterModelRoute `yaml:"models"`
}

type Options struct {
	// Conventional turns on auto-discovery of the project-level conventional files
	// (the shared/local .mecatl + .claude files) and the user-global files. Default
	// false keeps discovery fully off (only ExplicitFiles, if any, are loaded).
	Conventional bool
	// ImportClaude turns on importing Claude-Code settings.json (project + user),
	// with the lossy fail-safe table applied (see claudeimport.go). Default false.
	ImportClaude bool
	// TrustProject, when true, honours a project's ALLOW rules (shared AND local —
	// both are project-supplied). When false (the default — the safe stance) a
	// project's allows are DROPPED while its deny/ask rules are still honoured.
	// User-global and explicit (CLI) config is always trusted regardless.
	TrustProject bool
	// ExplicitFiles are operator-pointed YAML config files (e.g. from a repeatable
	// --permission-config flag), loaded at ScopeCLI (the HIGHEST config precedence,
	// fully trusted) regardless of Conventional. Read from the host filesystem at
	// construction.
	ExplicitFiles []string
	// Diagnostics is the operational-logging sink for the lossy import report
	// (demoted/inert/dropped specs) and the per-file fail-soft skip lines. nil is
	// tolerated: newWithEnv defaults it to port.NopDiagnostics so the resolver stays
	// silent rather than nil-panicking. The composition layer injects the shared sink.
	Diagnostics port.Diagnostics
}

type Permissions struct {
	// Allow lists rule specs that GRANT a tool call (effect Allow) on the MAIN
	// engine. Under an untrusted project these are DROPPED by the trust gate
	// (see Resolver).
	Allow []string `yaml:"allow"`
	// Ask lists rule specs that REQUIRE approval (effect Ask) on the MAIN
	// engine. Always honoured.
	Ask []string `yaml:"ask"`
	// Deny lists rule specs that BLOCK a tool call (effect Deny) EVERYWHERE —
	// main engine and subagents (a deny only tightens). Always honoured.
	Deny []string `yaml:"deny"`
	// Subagent holds the child-scoped rule-spec lists (issue #32): rules that
	// bind ONLY subagent/member/branch engines, resolved through the child-ask
	// model (a subagent allow can clear a substitution-floored ask; a subagent
	// ask surfaces to the human or auto-denies; a subagent deny blocks).
	Subagent SubagentPermissions `yaml:"subagent"`
}

type ProviderAuth struct {
	Method string `yaml:"method"`
}

type ProviderDefinition struct {
	ID           string
	BaseURL      string       `yaml:"base_url"`
	DefaultModel string       `yaml:"default_model"`
	APIFlavor    string       `yaml:"api_flavor"`
	Auth         ProviderAuth `yaml:"auth"`
}

type ProviderDefinitions map[string]ProviderDefinition

type ProviderOverride struct {
	BaseURL string `yaml:"base_url"`
}

type ProviderOverrides map[string]ProviderOverride

type Report struct {
	// Demoted records Allow specs that were demoted to Ask for safety (e.g. a
	// Claude WebFetch(domain:...) allow — see importClaudeRules).
	Demoted []ReportEntry
	// Inert records specs that parsed but cannot match anything as written (e.g. a
	// Read(~/path) whose "~" is left unexpanded), so the operator knows the rule
	// has no effect.
	Inert []ReportEntry
	// Dropped records specs that could not be parsed at all and were discarded.
	Dropped []ReportEntry
}

type ReportEntry struct {
	Spec   string
	Reason string
}

type Resolver struct {
	// contains filtered or unexported fields
}

type RetentionLimitSection struct {
	// MaxAge deletes eligible rows older than this Go duration; 0 disables the age limit.
	MaxAge string `yaml:"max_age"`
	// MaxCount keeps the newest eligible rows up to this count; 0 disables the count limit.
	MaxCount               int  `yaml:"max_count"`
	MaxAgeSet, MaxCountSet bool `yaml:"-"`
}

type RetentionSection struct {
	// Version is the required schema version; the only supported value is 1.
	Version int `yaml:"version"`
	// Main controls top-level operator/service sessions.
	Main RetentionLimitSection `yaml:"main"`
	// Child controls subagent, parallel-branch, and team-member sessions.
	Child RetentionLimitSection `yaml:"child"`
	// Scheduled controls scheduled-fire sessions.
	Scheduled RetentionLimitSection `yaml:"scheduled"`
	// SweepCadence is the repeat interval; 0 disables repeats while retaining the compatibility startup sweep.
	SweepCadence string `yaml:"sweep_cadence"`
	// AcknowledgeMainDeletion explicitly consents to destructive main-session cleanup.
	AcknowledgeMainDeletion bool `yaml:"acknowledge_main_deletion"`
	SweepCadenceSet         bool `yaml:"-"`
}

type RouterCategory struct {
	// Name is the routing key the classifier echoes back as its verdict and the key
	// composition maps to Model.
	Name string `yaml:"name"`
	// Description is the one-line summary the classifier reads to choose this category.
	Description string `yaml:"description"`
	// Model is the model selector (alias / slot / concrete id) a task classified into
	// this category is minted on, resolved through the operator-merged alias map.
	Model string `yaml:"model"`
}

type RouterSection struct {
	// ClassifierSlot names the model slot the CLASSIFIER itself runs on (the tiny,
	// cheap one-turn classification call). Empty falls through to the `router` slot's
	// default tier (cheap) — the classifier is housekeeping, not the routed work.
	ClassifierSlot string `yaml:"classifier-slot"`
	// Categories are the routing choices. Each carries a Name (the classifier's verdict
	// key), a Description (the classifier's only signal — make them distinct), and a
	// Model selector (an alias / slot / concrete id, resolved through the operator-
	// merged alias map; operator taxonomy targets are UNCAPPED).
	Categories []RouterCategory `yaml:"categories"`
	// DefaultCategory is the category the classifier is told to choose when none clearly
	// fits (advisory to the classifier; the real safety net is the fail-soft inherit).
	DefaultCategory string `yaml:"default-category"`
	// Disabled is the YAML-level kill switch (ADR 0042, mirroring
	// GuardrailsSection.Disabled): per ADR 0042 a non-empty taxonomy ENABLES the router,
	// so `disabled: true` is the "taxonomy defined but temporarily off" override. The
	// CLI kill-switch --subagent-model-router=false also sets it (the two OR together).
	// Default false ⇒ the router is enabled whenever categories are present.
	Disabled bool `yaml:"disabled"`
}

type StorageManagementPrincipal struct {
	// Issuer must equal the verified token issuer byte-for-byte.
	Issuer string `yaml:"issuer"`
	// Subject must equal the verified token subject byte-for-byte.
	Subject string `yaml:"subject"`
}

type StorageManagementSection struct {
	// Version is the required schema version; the only supported value is 1.
	Version int `yaml:"version"`
	// Principals lists exact verified OIDC issuer/subject pairs. Empty grants nobody.
	Principals []StorageManagementPrincipal `yaml:"principals"`
}

type SubagentPermissions struct {
	// Allow lists child-scoped rule specs with effect Allow (trust-gated for
	// project tiers).
	Allow []string `yaml:"allow"`
	// Ask lists child-scoped rule specs with effect Ask (always honoured). A
	// configured subagent Ask is NEVER auto-approved by the isolation carve-out —
	// it surfaces to a human or auto-denies.
	Ask []string `yaml:"ask"`
	// Deny lists child-scoped rule specs with effect Deny (always honoured).
	Deny []string `yaml:"deny"`
}

type TemporaryStorageSection struct {
	Mode                string        `yaml:"mode"`
	ManagedRoot         string        `yaml:"managed_root"`
	SystemTempDir       string        `yaml:"system_temp_dir"`
	CommandReapAfter    time.Duration `yaml:"command_reap_after"`
	ReapInterval        time.Duration `yaml:"reap_interval"`
	ReapTimeout         time.Duration `yaml:"reap_timeout"`
	ShutdownReapTimeout time.Duration `yaml:"shutdown_reap_timeout"`
}