agent

type AgentGuardSpec struct {
	// Name is the agent identifier the contextguard plugin keys
	// summaries by. For the root, this is cfg.Root.Name. For
	// static templates, this is the template's Name field.
	Name string

	// Config is the user-facing ContextGuardConfig from baifo.yaml
	// for this agent. An Enabled=false config disables the row
	// silently; the builder skips it.
	Config config.ContextGuardConfig
}

type Builder struct {
	Providers *providers.Registry
	Secrets   *secrets.Store
	Audit     *audit.Recorder

	// MCPs is optional. When nil, Spec.MCPs must be empty or Build
	// returns an error. Provided as a field (not a parameter) so the
	// rest of the wiring stays compact.
	MCPs *mcps.Registry

	// ModelWrapper, when non-nil, is given the LLM the providers
	// registry produced and returns the one the agent will actually
	// use. Used to install diagnostic wrappers (request dumpers,
	// rate-limiters, ...) without sprinkling conditionals through the
	// build path. A nil wrapper is a no-op (identity).
	ModelWrapper func(model.LLM) model.LLM

	// OpaqueTools lists tool names whose arguments must NOT be walked
	// by the secrets expander. The canonical population is the spawn
	// tool names (see internal/tools/spawn.OpaqueToolNames), which
	// take agent specs as input. If the expander ran on them, a
	// ${secret:NAME} placeholder embedded in the child's prompt or
	// initial_message would be substituted eagerly with the raw value
	// and baked into the child agent's prompt, bypassing the child's
	// own allowlist. Leaving the placeholders intact lets the child's
	// own BeforeToolCallback decide, at its own tool boundary, whether
	// to expand (using its own, typically narrower, allower).
	//
	// nil or empty disables the guard. Callers should pass the list
	// verbatim; the Builder converts it into a set internally.
	OpaqueTools []string

	// ScrubAllResponses controls the AfterToolCallback's
	// comprehensive-redaction pass: when true (the recommended
	// default), every tool result is scanned for ANY raw value
	// currently stored in `Secrets`, not just the values the
	// BeforeToolCallback substituted in this call. This closes the
	// "tools that emit secrets they were not given" gap (think of an
	// MCP echoing a debug header that contains a token from a
	// different secret in the store).
	//
	// Set to false to disable the comprehensive pass, useful only
	// for debugging or when the operator has profiled and found the
	// scan dominates a hot path. The targeted pass (scrubbing values
	// expanded in this call) remains active regardless.
	ScrubAllResponses bool

	// MinScrubLength is the minimum length (in bytes) a stored
	// secret value must have to be eligible for the comprehensive
	// pass. Below this floor the value is skipped to avoid
	// catastrophic false positives: e.g. a stored value of "1234"
	// would otherwise redact every "1234" anywhere in any tool
	// result.
	//
	// The targeted pass is unaffected: short values stay protected
	// when the LLM explicitly references them via ${secret:NAME}.
	// Recommended floor is 8 bytes (real API keys are far longer);
	// 0 or negative disables the filter entirely (every length goes
	// through), which is documented as dangerous in CONFIG.md and
	// SECRETS.md.
	MinScrubLength int
}

type Instance struct {
	ID    string
	Spec  Spec
	Agent agent.Agent

	// LLM is the model the agent was built with. Exposed so the
	// context-guard plugin can hand it to the contextguard library
	// for summarisation. nil only when the agent has no LLM, which
	// is currently impossible (Build returns ErrNoRoot in that case)
	// but kept nullable to match agent.Agent's contract.
	LLM model.LLM
}

type ReasoningConfig struct {
	// Request-level config (consumed by Gemini and OpenAI).
	GenerateContentConfig *genai.GenerateContentConfig

	// Construction-time config (consumed by Anthropic).
	ModelOptions *providers.ModelOptions
}

type Spec struct {
	Name        string
	Description string
	Prompt      string

	// Provider + Model resolve through the providers.Registry.
	Provider string
	Model    string

	// AllowedSecrets is the whitelist for the secret expander. The
	// length encodes the policy:
	//
	//   - nil or empty → the agent cannot dereference any secret
	//     (least-privilege default). Built sub-agents land here when
	//     the operator declared no allowed_secrets on a template, or
	//     when a dynamic spawn omitted the field.
	//   - non-empty    → exactly those names are allowed.
	//
	// The ROOT agent does not go through this field. It is built
	// with UnrestrictedSecrets=true and gets AllowAll instead, so it
	// can dereference every secret the operator stored. See
	// SECRETS.md for the threat-model rationale.
	AllowedSecrets []string

	// UnrestrictedSecrets, when true, replaces the per-name allowlist
	// with AllowAll. Reserved for the root agent. Sub-agents must
	// leave this false and use AllowedSecrets to enumerate exactly
	// what they can see.
	UnrestrictedSecrets bool

	// MCPs lists the MCP names (as declared in baifo.yaml) whose tools
	// should be exposed to this agent. The Builder resolves them via
	// mcps.Registry.Tools.
	MCPs []string

	// Skills lists the skill slugs that should be available to this
	// agent. Skills do not contribute tool.Tool entries yet (see the
	// SKILL TOOLSET note in memory); reserved here so callers can
	// already wire the field from baifo.yaml.
	Skills []string

	// Reasoning is the optional reasoning-effort knob: one of
	// "minimal" / "low" / "medium" / "high" (empty = leave the model's
	// own default). The builder turns it into a request-level
	// GenerateContentConfig.ThinkingConfig (honoured by openai and
	// gemini) AND, for anthropic, a construction-time thinking budget
	// passed through providers.ModelOptions. Validation of the value
	// lives at the config / spawn boundary; an unrecognised value here
	// is treated as "unset" so a bad string never breaks agent
	// construction.
	Reasoning string

	// ReasoningAPI optionally overrides which Anthropic reasoning API the
	// model speaks: "enabled" (classic budget-based) or "adaptive"
	// (effort-based, Opus 4.5+). Empty lets the builder auto-detect from
	// the catwalk catalogue. Ignored by non-anthropic providers. An
	// unrecognised value is treated as "unset".
	ReasoningAPI string

	// ExtraTools are additional tools to attach beyond what MCPs and
	// Skills provide. Mostly useful for tests and for spawn/supervise
	// machinery in future phases.
	ExtraTools []tool.Tool
}