latest

type APIToolConfig struct {
	Instruction string            `json:"instruction,omitempty"`
	Name        string            `json:"name,omitempty"`
	Required    []string          `json:"required,omitempty"`
	Args        map[string]any    `json:"args,omitempty"`
	Endpoint    string            `json:"endpoint,omitempty"`
	Method      string            `json:"method,omitempty"`
	Headers     map[string]string `json:"headers,omitempty"`
	// OutputSchema optionally describes the API response as JSON Schema for MCP/Code Mode consumers; runtime still returns the raw string body.
	OutputSchema map[string]any `json:"output_schema,omitempty"`
}

type AgentConfig struct {
	Name           string
	Model          string          `json:"model,omitempty"`
	Fallback       *FallbackConfig `json:"fallback,omitempty"`
	Description    string          `json:"description,omitempty"`
	WelcomeMessage string          `json:"welcome_message,omitempty"`
	Toolsets       []Toolset       `json:"toolsets,omitempty"`
	Instruction    string          `json:"instruction,omitempty"`
	// InstructionFile names one or more files, relative to the config file's
	// directory, whose contents are loaded into Instruction when the config is
	// loaded. It accepts either a single path (`instruction_file: prompt.md`)
	// or a list (`instruction_file: [intro.md, rules.md]`); when several files
	// are given their contents are concatenated in order, separated by a blank
	// line. It keeps long behavioral prompts out of the YAML, letting
	// infrastructure configuration and instruction content evolve in separate
	// files. Mutually exclusive with Instruction. Only file-based config
	// sources are supported (not OCI/URL/bytes sources, which have no directory
	// to resolve against). The field is cleared once resolved so the in-memory
	// config stays self-contained (see config.Load).
	InstructionFile InstructionFiles `json:"instruction_file,omitempty" yaml:"instruction_file,omitempty"`
	Harness         *HarnessConfig   `json:"harness,omitempty"`
	SubAgents       []string         `json:"sub_agents,omitempty"`
	Handoffs        []string         `json:"handoffs,omitempty"`
	// ForceHandoff names an agent that unconditionally receives the
	// conversation whenever this agent produces a final response,
	// bypassing the LLM's tool-calling entirely. Unlike Handoffs (which
	// rely on the model choosing to call the handoff tool), the runtime
	// intercepts the natural stop and routes deterministically, making
	// strict pipelines reliable. The full conversation context carries
	// over to the target agent.
	ForceHandoff string `json:"force_handoff,omitempty" yaml:"force_handoff,omitempty"`

	AddDate            bool `json:"add_date,omitempty"`
	AddEnvironmentInfo bool `json:"add_environment_info,omitempty"`
	// ReadOnly makes every one of the agent's toolsets read-only: only
	// tools whose annotations carry a read-only hint are listed and
	// callable. Equivalent to setting `readonly: true` on each toolset.
	ReadOnly bool `json:"readonly,omitempty" yaml:"readonly,omitempty"`
	// RedactSecrets enables every leg of the redact_secrets feature:
	// the pre_tool_use builtin (scrubs tool arguments), the
	// before_llm_call hook (scrubs outgoing chat content), and the
	// tool_response_transform hook (scrubs tool output before it
	// reaches event consumers, the persisted session, the post_tool_use
	// hook, or the next LLM call). Equivalent to writing all three
	// hook entries by hand — the runtime auto-injects them when this
	// flag is true. See pkg/hooks/builtins/redact_secrets.go for the
	// hook-side implementation.
	//
	// Pointer (tri-state) so we can distinguish "unset" (nil → default
	// on) from "explicitly disabled" (false). Use
	// [AgentConfig.RedactSecretsEnabled] to read the effective value.
	RedactSecrets           *bool             `json:"redact_secrets,omitempty"`
	CodeModeTools           bool              `json:"code_mode_tools,omitempty"`
	AddDescriptionParameter bool              `json:"add_description_parameter,omitempty"`
	MaxIterations           int               `json:"max_iterations,omitempty"`
	MaxConsecutiveToolCalls int               `json:"max_consecutive_tool_calls,omitempty"`
	MaxOldToolCallTokens    int               `json:"max_old_tool_call_tokens,omitempty"`
	NumHistoryItems         int               `json:"num_history_items,omitempty"`
	AddPromptFiles          []string          `json:"add_prompt_files,omitempty" yaml:"add_prompt_files,omitempty"`
	Commands                types.Commands    `json:"commands,omitempty"`
	StructuredOutput        *StructuredOutput `json:"structured_output,omitempty"`
	Skills                  SkillsConfig      `json:"skills,omitzero"`
	// UseCommands and UseSkills reference reusable groups defined in the
	// top-level Config.Commands / Config.Skills sections. The referenced
	// groups are merged into Commands / Skills during config resolution;
	// inline entries on the agent take precedence on name conflicts.
	UseCommands []string `json:"use_commands,omitempty"`
	UseSkills   []string `json:"use_skills,omitempty"`
	// UseToolsets references reusable toolset definitions defined in the
	// top-level Config.Toolsets section. The referenced toolsets are appended
	// to the agent's own Toolsets during config resolution (see
	// resolveToolsetDefinitions). Inline toolsets on the agent come first.
	UseToolsets []string     `json:"use_toolsets,omitempty"`
	Hooks       *HooksConfig `json:"hooks,omitempty"`
	Cache       *CacheConfig `json:"cache,omitempty"`
}

type Agents []AgentConfig

type AuthConfig struct {
	// Type discriminates which authentication scheme to use.
	// Currently supported: "workload_identity_federation".
	Type string `json:"type" yaml:"type"`
	// Federation holds the parameters for the workload_identity_federation
	// scheme. Required when Type == "workload_identity_federation".
	Federation *FederationAuthConfig `json:"workload_identity_federation,omitempty" yaml:"workload_identity_federation,omitempty"`
}

type BackoffConfig struct {
	Initial    Duration `json:"initial,omitzero" yaml:"initial,omitempty"`
	Max        Duration `json:"max,omitzero" yaml:"max,omitempty"`
	Multiplier float64  `json:"multiplier,omitempty" yaml:"multiplier,omitempty"`
	// Jitter is a 0..1 fraction of the computed delay applied as a
	// uniform random offset. 0 disables jitter (the default).
	Jitter float64 `json:"jitter,omitempty" yaml:"jitter,omitempty"`
}

type CacheConfig struct {
	Enabled       bool   `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	CaseSensitive bool   `json:"case_sensitive,omitempty" yaml:"case_sensitive,omitempty"`
	TrimSpaces    bool   `json:"trim_spaces,omitempty" yaml:"trim_spaces,omitempty"`
	Path          string `json:"path,omitempty" yaml:"path,omitempty"`
}

type CapabilitiesConfig struct {
	// Image reports whether the model accepts image attachments.
	Image bool `json:"image,omitempty"`
	// PDF reports whether the model accepts PDF (application/pdf) attachments.
	PDF bool `json:"pdf,omitempty"`
}

type Config struct {
	Version   string                    `json:"version,omitempty"`
	Agents    Agents                    `json:"agents,omitempty"`
	Providers map[string]ProviderConfig `json:"providers,omitempty"`
	Models    map[string]ModelConfig    `json:"models,omitempty"`
	MCPs      map[string]MCPToolset     `json:"mcps,omitempty"`
	RAG       map[string]RAGToolset     `json:"rag,omitempty"`
	// Commands and Skills are reusable, named groups shared across agents.
	// An agent opts into a group by listing its name in AgentConfig.UseCommands
	// or AgentConfig.UseSkills; the group is merged into the agent during config
	// resolution (see resolveCommandDefinitions / resolveSkillDefinitions). This
	// mirrors the top-level MCPs/RAG reference-by-name convention.
	Commands map[string]types.Commands `json:"commands,omitempty"`
	Skills   map[string]SkillsConfig   `json:"skills,omitempty"`
	// Toolsets is a map of reusable, named toolset definitions shared across
	// agents. An agent opts in by listing a name in AgentConfig.UseToolsets;
	// the named toolset is appended to the agent during config resolution
	// (see resolveToolsetDefinitions). This mirrors the top-level MCPs/RAG
	// reference-by-name convention but works for any toolset type.
	Toolsets    map[string]Toolset `json:"toolsets,omitempty"`
	Metadata    Metadata           `json:"metadata"`
	Permissions *PermissionsConfig `json:"permissions,omitempty"`
	Runtime     *RuntimeDefaults   `json:"runtime,omitempty"`
}

type DeferConfig struct {
	// DeferAll is true when all tools should be deferred
	DeferAll bool `json:"-"`
	// Tools is the list of specific tool names to defer (empty if DeferAll is true)
	Tools []string `json:"-"`
}

type Duration struct {
	time.Duration
}

type FallbackConfig struct {
	// Models is a list of fallback models to try in order if the primary fails.
	// Each entry can be a model name from the models section or an inline provider/model format.
	Models []string `json:"models,omitempty"`
	// Retries is the number of retries per model with exponential backoff.
	// Default is 2 (giving 3 total attempts per model). Use -1 to disable retries entirely.
	// Retries only apply to retryable errors (5xx, timeouts); non-retryable errors (429, 4xx)
	// skip immediately to the next model.
	Retries int `json:"retries,omitempty"`
	// Cooldown is the duration to stick with a successful fallback model before
	// retrying the primary. Only applies after a non-retryable error (e.g., 429).
	// Default is 1 minute. Use Go duration format (e.g., "1m", "30s", "2m30s").
	Cooldown Duration `json:"cooldown"`
}

type FederationAuthConfig struct {
	// FederationRuleID identifies the Anthropic OidcFederationRule that
	// governs token exchange. Required; must start with "fdrl_".
	FederationRuleID string `json:"federation_rule_id" yaml:"federation_rule_id"`
	// OrganizationID is the UUID of the Anthropic organization that owns
	// the federation rule. Required.
	OrganizationID string `json:"organization_id" yaml:"organization_id"`
	// ServiceAccountID is the optional expected-target check for federation
	// rules with target_type=SERVICE_ACCOUNT. Must start with "svac_". Omit
	// for target_type=USER rules where the principal is derived from the
	// JWT.
	ServiceAccountID string `json:"service_account_id,omitempty" yaml:"service_account_id,omitempty"`
	// IdentityToken describes how to obtain a fresh JWT for each exchange.
	// Required.
	IdentityToken *IdentityTokenSourceConfig `json:"identity_token" yaml:"identity_token"`
}

type FlexibleModelConfig struct {
	ModelConfig
}

type HarnessConfig struct {
	// Type identifies the external harness provider: claude-code, codex, pi, or opencode.
	Type string `json:"type,omitempty"`
	// Model is passed to harnesses that accept a model flag. When omitted,
	// docker-agent lets the external CLI use its own default model.
	Model string `json:"model,omitempty"`
	// Effort is forwarded to Claude Code's --effort flag.
	Effort string `json:"effort,omitempty"`
	// Agent is forwarded to opencode's --agent flag.
	Agent string `json:"agent,omitempty"`
	// Thinking enables opencode's --thinking flag.
	Thinking bool `json:"thinking,omitempty"`
}

type HookDefinition struct {
	// Name gives the hook a friendly label for logs and runtime events.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Type specifies the hook type. Supported values:
	//   - "command":  run a shell command (default)
	//   - "builtin":  invoke a named, in-process Go function (the name
	//                 lives in Command). The set of registered builtins
	//                 is owned by the runtime; the docker-agent runtime
	//                 ships add_date, add_environment_info,
	//                 add_prompt_files, redact_secrets (see also the
	//                 redact_secrets agent flag), and several others
	//                 documented in pkg/hooks/builtins.
	//   - "model":    ask an LLM and translate its reply into the hook's
	//                 native output. See Model / Prompt / Schema. Used to
	//                 implement "LLM as a judge" pre_tool_use hooks,
	//                 turn-start summarizers, etc., with no Go code.
	Type string `json:"type" yaml:"type"`

	// Command is the shell command (Type==command) or the builtin name
	// (Type==builtin) to invoke.
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Args are arbitrary string arguments passed to the hook handler.
	// Builtin handlers receive them as the args parameter; future handler
	// kinds (http, mcp, ...) can adopt the same field. Empty for command
	// hooks today (the shell command stays self-contained).
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// Timeout is the execution timeout in seconds (default: 60)
	Timeout int `json:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Env adds or overrides environment variables for this hook only.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// WorkingDir overrides the runtime working directory for this hook.
	WorkingDir string `json:"working_dir,omitempty" yaml:"working_dir,omitempty"`

	// OnError controls non-fail-closed hook failures: warn (default), ignore, or block.
	OnError string `json:"on_error,omitempty" yaml:"on_error,omitempty"`

	// Model is the model spec ("provider/model", e.g. "openai/gpt-4o-mini")
	// invoked by Type==model hooks. Required for that type, ignored
	// otherwise.
	Model string `json:"model,omitempty" yaml:"model,omitempty"`

	// Prompt is the user-message template rendered for each invocation
	// of a Type==model hook. It is parsed as a Go text/template with the
	// hook [Input] as the data context (so {{ .ToolName }},
	// {{ .ToolInput }}, etc. work). Required for Type==model.
	Prompt string `json:"prompt,omitempty" yaml:"prompt,omitempty"`

	// Schema selects a well-known response interpretation for Type==model
	// hooks. The empty value means "return the model's reply as
	// additional_context". Other values (registered by the runtime) ask
	// the provider for strict-JSON output and translate the result into
	// the right Output shape (e.g. "pre_tool_use_decision" produces a
	// permission_decision verdict).
	Schema string `json:"schema,omitempty" yaml:"schema,omitempty"`
}

type HookMatcherConfig struct {
	// Matcher is a regex pattern to match tool names (e.g., "shell|edit_file")
	// Use "*" to match all tools. Case-sensitive.
	Matcher string `json:"matcher,omitempty" yaml:"matcher,omitempty"`

	// Hooks are the hooks to execute when the matcher matches
	Hooks []HookDefinition `json:"hooks" yaml:"hooks"`

	// PreemptYolo opts a pre_tool_use entry into firing BEFORE the
	// deterministic approval pipeline (--yolo, permission patterns).
	// A deny/ask verdict from a preempting hook cannot be bypassed by
	// auto-approval rules; an allow verdict is advisory (the pipeline
	// still runs Decide() and the rest of pre_tool_use). Default
	// pre_tool_use entries fire AFTER Decide(), as before. Only valid
	// on pre_tool_use; ignored on other events.
	//
	// Used by the safer_shell builtin (auto-registered with this flag
	// when a shell toolset has `safer: true`). Custom hooks set it to
	// true when they implement a security-critical check that must
	// not be bypassed by --yolo.
	PreemptYolo *bool `json:"preempt_yolo,omitempty" yaml:"preempt_yolo,omitempty"`
}

type HooksConfig struct {
	// PreToolUse hooks run before tool execution
	PreToolUse []HookMatcherConfig `json:"pre_tool_use,omitempty" yaml:"pre_tool_use,omitempty"`

	// PostToolUse hooks run after a tool completes — both success and
	// failure: a failed tool call still fires this event, with the
	// failure surfaced in tool_response (notably the is_error flag and
	// any error text). Use post_tool_use to react to either outcome
	// (logging, audits, circuit-breakers); branch on tool_response.is_error
	// in the handler when you only want to act on one of them.
	PostToolUse []HookMatcherConfig `json:"post_tool_use,omitempty" yaml:"post_tool_use,omitempty"`

	// PermissionRequest hooks run just before the runtime would prompt
	// the user to approve a tool call (i.e. when neither --yolo nor a
	// permissions rule short-circuited the decision). Hooks may auto-allow
	// or auto-deny via hook_specific_output.permission_decision so the
	// user is not prompted; otherwise the runtime falls through to the
	// usual interactive confirmation. Tool-matched, like pre_tool_use.
	PermissionRequest []HookMatcherConfig `json:"permission_request,omitempty" yaml:"permission_request,omitempty"`

	// SessionStart hooks run when a session begins
	SessionStart []HookDefinition `json:"session_start,omitempty" yaml:"session_start,omitempty"`

	// UserPromptSubmit hooks run once per user message, after the user
	// has submitted their prompt and before the first model call of the
	// turn. The submitted text is passed in the prompt field. Hooks can
	// block submission (decision="block" / continue=false / exit code 2)
	// or contribute additional_context that is spliced into the
	// conversation as a transient system message for that turn only.
	// Sub-sessions (transferred tasks, background agents) do not fire
	// this event because their kick-off message is synthesised by the
	// runtime, not authored by the user.
	UserPromptSubmit []HookDefinition `json:"user_prompt_submit,omitempty" yaml:"user_prompt_submit,omitempty"`

	// UserSteeringMessagesSubmit hooks run once each time the runtime
	// drains the steering queue and appends the queued user messages to
	// the session — i.e. messages the user submitted while the agent was
	// already working (mid-turn, after the model stopped, or while idle
	// before the first model call). The drained messages are passed in
	// the steering_messages field. Like user_prompt_submit, hooks can
	// block the run (decision="block" / continue=false / exit code 2) or
	// contribute additional_context that is spliced into the conversation
	// as a transient system message for the steered turn only — it is NOT
	// persisted to the session.
	UserSteeringMessagesSubmit []HookDefinition `json:"user_steering_messages_submit,omitempty" yaml:"user_steering_messages_submit,omitempty"`

	// UserFollowupSubmit hooks run once each time the runtime dequeues a
	// follow-up message at the end of a turn and starts a fresh turn for
	// it. Follow-ups are user messages queued for end-of-turn processing
	// (the FollowUp API / queue), as opposed to mid-turn steering. The
	// follow-up text is passed in the prompt field. Like
	// user_prompt_submit, hooks can block the run (decision="block" /
	// continue=false / exit code 2) or contribute additional_context that
	// is spliced into the conversation as a transient system message for
	// the follow-up turn only — it is NOT persisted to the session.
	UserFollowupSubmit []HookDefinition `json:"user_followup_submit,omitempty" yaml:"user_followup_submit,omitempty"`

	// TurnStart hooks run at the start of every agent turn (each model
	// call). Their AdditionalContext is appended as transient system
	// messages for that turn only — it is NOT persisted to the session,
	// so per-turn signals (date, prompt files, ...) are recomputed every
	// turn instead of bloating the message history on every resume.
	TurnStart []HookDefinition `json:"turn_start,omitempty" yaml:"turn_start,omitempty"`

	// TurnEnd hooks run once per agent turn when the turn finishes —
	// the symmetric counterpart of TurnStart. Fires no matter why the
	// turn ended: a normal stop, an error, a hook-driven shutdown, the
	// loop detector, or context cancellation. The reason is reported
	// in the hook input's reason field ("normal", "continue",
	// "steered", "error", "canceled", "hook_blocked",
	// "loop_detected"). Observational; output is ignored.
	TurnEnd []HookDefinition `json:"turn_end,omitempty" yaml:"turn_end,omitempty"`

	// BeforeLLMCall hooks run just before each model call (after
	// turn_start). Use this for observability, cost guardrails, or
	// auditing without contributing system messages — turn_start is the
	// right event for the latter.
	BeforeLLMCall []HookDefinition `json:"before_llm_call,omitempty" yaml:"before_llm_call,omitempty"`

	// AfterLLMCall hooks run just after each successful model call,
	// before the response is recorded into the session and tool calls
	// are dispatched. Receives the assistant text content in
	// stop_response.
	AfterLLMCall []HookDefinition `json:"after_llm_call,omitempty" yaml:"after_llm_call,omitempty"`

	// SessionEnd hooks run when a session ends
	SessionEnd []HookDefinition `json:"session_end,omitempty" yaml:"session_end,omitempty"`

	// PreCompact hooks run just before the runtime compacts the session
	// transcript into a summary. The trigger is reported in the source
	// field: "manual" (user-initiated /compact), "auto" (proactive
	// threshold), "overflow" (context-overflow recovery), or
	// "tool_overflow" (proactive after tool results pushed past the
	// threshold). Hooks may block compaction (decision="block" /
	// continue=false / exit code 2) or contribute additional_context
	// that is appended to the compaction prompt — useful for steering
	// the summary without modifying the agent's instruction.
	PreCompact []HookDefinition `json:"pre_compact,omitempty" yaml:"pre_compact,omitempty"`

	// SubagentStop hooks run when a sub-agent (transferred task,
	// background agent, skill sub-session) finishes. The sub-agent's
	// name is passed in agent_name and its final assistant message in
	// stop_response. Useful for handoff auditing and per-sub-agent
	// metrics, separately from the parent's stop event.
	SubagentStop []HookDefinition `json:"subagent_stop,omitempty" yaml:"subagent_stop,omitempty"`

	// OnUserInput hooks run when the agent needs user input
	OnUserInput []HookDefinition `json:"on_user_input,omitempty" yaml:"on_user_input,omitempty"`

	// Stop hooks run when the model finishes responding and is about to hand control back to the user
	Stop []HookDefinition `json:"stop,omitempty" yaml:"stop,omitempty"`

	// Notification hooks run when the agent sends a notification (error, warning) to the user
	Notification []HookDefinition `json:"notification,omitempty" yaml:"notification,omitempty"`

	// OnError hooks run when the runtime hits an error during a turn
	// (model failures, repetitive tool-call loops). Fires alongside
	// Notification with level="error".
	OnError []HookDefinition `json:"on_error,omitempty" yaml:"on_error,omitempty"`

	// OnMaxIterations hooks run when the runtime reaches its configured
	// max_iterations limit. Fires alongside Notification with
	// level="warning".
	OnMaxIterations []HookDefinition `json:"on_max_iterations,omitempty" yaml:"on_max_iterations,omitempty"`

	// OnAgentSwitch hooks run whenever the runtime moves the active
	// agent to a new one — transfer_task, handoff, force_handoff, or
	// the return after a transferred task completes. Observational;
	// useful for audit, transcript, and metrics pipelines.
	OnAgentSwitch []HookDefinition `json:"on_agent_switch,omitempty" yaml:"on_agent_switch,omitempty"`

	// OnSessionResume hooks run when the user explicitly approves the
	// runtime to continue past its configured max_iterations limit.
	// Observational; useful for alerting on extended-runtime sessions.
	OnSessionResume []HookDefinition `json:"on_session_resume,omitempty" yaml:"on_session_resume,omitempty"`

	// OnToolApprovalDecision hooks run after the runtime's tool
	// approval chain resolves a verdict for a tool call. Observational;
	// gives audit pipelines a structured "who approved what" record
	// without re-implementing the chain.
	OnToolApprovalDecision []HookDefinition `json:"on_tool_approval_decision,omitempty" yaml:"on_tool_approval_decision,omitempty"`

	// BeforeCompaction hooks run immediately before a session compaction.
	// Hooks may veto compaction (Decision: "block") or supply a custom
	// summary via HookSpecificOutput.summary, in which case the runtime
	// applies that summary verbatim and skips the LLM call. Hooks receive
	// the current input/output token counts, the model context limit, and
	// a compaction_reason of "threshold", "overflow", or "manual".
	BeforeCompaction []HookDefinition `json:"before_compaction,omitempty" yaml:"before_compaction,omitempty"`

	// AfterCompaction hooks run after a successful compaction (a summary
	// was applied to the session). The Input.summary field carries the
	// produced summary text. AfterCompaction is purely observational.
	AfterCompaction []HookDefinition `json:"after_compaction,omitempty" yaml:"after_compaction,omitempty"`

	// ToolResponseTransform hooks run between a tool's exec and the
	// runtime's emission/record of the response. Hooks may rewrite the
	// tool's textual output by returning a non-empty
	// HookSpecificOutput.updated_tool_response — the runtime applies
	// the rewrite before the response fans out to event consumers, the
	// recorded chat message, and the post_tool_use hook input. This is
	// the third leg of the redact_secrets feature: pre_tool_use scrubs
	// arguments, before_llm_call scrubs outgoing chat content, and
	// tool_response_transform scrubs tool output. Tool-matched, like
	// pre_tool_use / post_tool_use.
	ToolResponseTransform []HookMatcherConfig `json:"tool_response_transform,omitempty" yaml:"tool_response_transform,omitempty"`

	// WorktreeCreate hooks run once, just after `docker agent run
	// --worktree` creates a git worktree and before the session starts.
	// They execute inside the new worktree (their working directory is
	// the fresh checkout) with the worktree path, branch, and source
	// repository root passed in worktree_path / worktree_branch /
	// worktree_source_dir. Use them to prepare the checkout — copy
	// untracked files like .env from the source dir, install
	// dependencies, warm caches. A hook may abort the run by blocking
	// (decision="block" / continue=false / exit code 2); stdout is added
	// as context.
	WorktreeCreate []HookDefinition `json:"worktree_create,omitempty" yaml:"worktree_create,omitempty"`
}

type IdentityTokenSourceConfig struct {
	// File reads the token from a file path. The file is re-read on every
	// federation exchange (suitable for K8s projected SA tokens, SPIFFE
	// helpers, Vault sidecars and other rotating-on-disk credentials).
	// Surrounding whitespace is trimmed.
	File string `json:"file,omitempty" yaml:"file,omitempty"`

	// Env reads the token from the named environment variable. The variable
	// is resolved through the runtime environment.Provider, so it works
	// with the standard process env, .env files, and Docker Desktop secret
	// providers. Surrounding whitespace is trimmed.
	Env string `json:"env,omitempty" yaml:"env,omitempty"`

	// Command executes a subprocess and uses its stdout as the token.
	// The first element is the executable; the remainder are arguments.
	// The command is re-run on every federation exchange. Stderr is logged.
	// Surrounding whitespace is trimmed from stdout.
	Command []string `json:"command,omitempty" yaml:"command,omitempty"`

	// URL fetches the token from an HTTP(S) endpoint via GET. ${VAR}
	// references in the URL are expanded against the runtime environment.
	// Useful for cloud metadata servers (GCP, Azure IMDS) and the
	// GitHub Actions OIDC token endpoint.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
	// Headers are sent with the URL request. Values support ${VAR}
	// expansion against the runtime environment, which lets you inject a
	// short-lived bearer token (e.g. ACTIONS_ID_TOKEN_REQUEST_TOKEN) without
	// putting it in the YAML.
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
	// ResponseField, when set, parses the URL response as JSON and reads
	// the named top-level field. When empty, the entire response body
	// (with surrounding whitespace trimmed) is used as the token.
	// Examples: GitHub Actions returns {"value":"<jwt>"} → "value";
	// GCP metadata returns the raw JWT → leave empty.
	ResponseField string `json:"response_field,omitempty" yaml:"response_field,omitempty"`
}

type InlineSkill struct {
	// Name is the skill identifier used by read_skill / run_skill and the
	// /<name> slash command. Required.
	Name string `json:"name" yaml:"name"`
	// Description is injected into the system prompt so the model knows when
	// the skill applies. Required.
	Description string `json:"description" yaml:"description"`
	// Instructions is the skill body (equivalent to the Markdown content
	// below the SKILL.md frontmatter). Required.
	Instructions string `json:"instructions" yaml:"instructions"`
	// Context, when set to "fork", runs the skill as an isolated sub-agent
	// (exposed via run_skill) instead of inlining it in the conversation.
	Context string `json:"context,omitempty" yaml:"context,omitempty"`
	// Model optionally overrides the model used while a fork-mode skill runs.
	// Ignored for non-fork skills.
	Model string `json:"model,omitempty" yaml:"model,omitempty"`
	// AllowedTools optionally records the tools the skill expects. It mirrors
	// the SKILL.md `allowed-tools` field. For a fork-mode skill it is enforced
	// as an allow-list over the parent agent's inherited tools while the skill
	// runs in its sub-session: only tools whose names match an entry are kept.
	// Entries are matched with filepath.Match-style globs (e.g. "read_*"),
	// falling back to an exact match. Ignored for non-fork skills.
	AllowedTools []string `json:"allowed_tools,omitempty" yaml:"allowed_tools,omitempty"`
	// Toolsets lists names of reusable toolset definitions (from the top-level
	// `toolsets` section) to expose to the skill while it runs in its fork
	// sub-session, in addition to the parent agent's tools. Ignored for
	// non-fork skills.
	Toolsets []string `json:"toolsets,omitempty" yaml:"toolsets,omitempty"`
}

type InstructionFiles []string

type LifecycleConfig struct {
	// Profile is a shorthand that picks defaults for all the other fields.
	// Empty means "resilient". Explicit fields override the profile.
	Profile string `json:"profile,omitempty" yaml:"profile,omitempty"`

	// Required, when set, indicates the toolset is critical to the agent.
	//
	// NOTE: this field is currently informational — the runtime does NOT
	// yet block agent startup on it. The wiring lives behind a planned
	// eager-startup commit; until then, callers can read the effective
	// value via IsRequired() but the supervisor itself does not act on it.
	//
	// nil pointer means "use the profile default" (true under "strict",
	// false otherwise).
	Required *bool `json:"required,omitempty" yaml:"required,omitempty"`

	// StartupTimeout caps the duration of the initial Connect call.
	//
	// NOTE: this field is currently informational — the runtime does NOT
	// yet enforce it. The supervisor's Start uses the caller's context
	// for cancellation today; honouring StartupTimeout requires the same
	// eager-startup wiring as Required.
	//
	// Zero means "no timeout".
	StartupTimeout Duration `json:"startup_timeout,omitzero" yaml:"startup_timeout,omitempty"`

	// CallTimeout is informational; it documents the user's expectation
	// for individual tool calls. The runtime currently uses the caller's
	// context for cancellation.
	CallTimeout Duration `json:"call_timeout,omitzero" yaml:"call_timeout,omitempty"`

	// Restart controls how the supervisor reacts to an unexpected
	// disconnect: "never", "on_failure" (default), or "always".
	Restart string `json:"restart,omitempty" yaml:"restart,omitempty"`

	// MaxRestarts is the maximum number of consecutive restart attempts
	// after a disconnect. 0 = use profile default (5). -1 = unlimited.
	MaxRestarts int `json:"max_restarts,omitempty" yaml:"max_restarts,omitempty"`

	// Backoff controls the wait between restart attempts.
	Backoff *BackoffConfig `json:"backoff,omitempty" yaml:"backoff,omitempty"`
}

type MCPToolset struct {
	Toolset `json:",inline" yaml:",inline"`
}

type Metadata struct {
	Author      string `json:"author,omitempty"`
	License     string `json:"license,omitempty"`
	Description string `json:"description,omitempty"`
	Readme      string `json:"readme,omitempty"`
	Version     string `json:"version,omitempty"`
}

type ModelConfig struct {
	// Name is the manifest model name (map key), populated at runtime.
	// Not serialized — set by teamloader/model_switcher when resolving models.
	Name     string `json:"-"`
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	// DisplayModel holds the original model name from the YAML config, before alias resolution.
	// When set, provider.ID() returns Provider + "/" + DisplayModel instead of the resolved name.
	// This ensures the UI shows the user-configured name (e.g., "claude-haiku-4-5")
	// while the API uses the resolved name (e.g., "claude-haiku-4-5-20251001").
	DisplayModel      string   `json:"-"`
	Temperature       *float64 `json:"temperature,omitempty"`
	MaxTokens         *int64   `json:"max_tokens,omitempty"`
	TopP              *float64 `json:"top_p,omitempty"`
	FrequencyPenalty  *float64 `json:"frequency_penalty,omitempty"`
	PresencePenalty   *float64 `json:"presence_penalty,omitempty"`
	BaseURL           string   `json:"base_url,omitempty"`
	ParallelToolCalls *bool    `json:"parallel_tool_calls,omitempty"`
	TokenKey          string   `json:"token_key,omitempty"`
	// ProviderOpts allows provider-specific options.
	ProviderOpts map[string]any `json:"provider_opts,omitempty"`
	TrackUsage   *bool          `json:"track_usage,omitempty"`
	// ThinkingBudget controls reasoning effort/budget.
	// Accepts an integer token count or a string effort level.
	// See [effort.ValidNames] for the full list of accepted strings.
	// Provider-specific mappings are in the effort package.
	ThinkingBudget *ThinkingBudget `json:"thinking_budget,omitempty"`
	// TaskBudget caps the total tokens a model can spend across an agentic task.
	// Forwarded to Anthropic as `output_config.task_budget` for every Claude
	// model — docker-agent does not gate by model name. At the time of writing,
	// only Claude Opus 4.7 actually honors it; other models will reject the
	// field. Accepts an integer token count or a {type: tokens, total: N} object.
	TaskBudget *TaskBudget `json:"task_budget,omitempty"`
	// Auth selects a non-API-key authentication scheme for this model
	// (currently: Anthropic Workload Identity Federation). When set, it
	// takes precedence over both the provider's API-key path and any
	// auth defined on the referenced ProviderConfig.
	Auth *AuthConfig `json:"auth,omitempty"`
	// Routing defines rules for routing requests to different models.
	// When routing is configured, this model becomes a rule-based router:
	// - The provider/model fields define the fallback model
	// - Each routing rule maps to a different model based on examples
	Routing []RoutingRule `json:"routing,omitempty"`
	// FirstAvailable lists candidate model references, in priority order.
	// At load time docker-agent selects the first candidate whose credentials
	// are configured. Candidates may be named models or inline "provider/model"
	// specs. Local providers (dmr, ollama) need no credentials and make reliable
	// final fallbacks. When set, other model configuration fields must be empty.
	FirstAvailable []string `json:"first_available,omitempty"`
	// TitleModel names the model used to generate session titles when an agent
	// runs with this model. It lets a heavyweight primary model delegate the
	// cheap title-generation call to a smaller/faster model. The value can be a
	// model name from the models section or an inline "provider/model" spec.
	// When empty, title generation reuses the agent's own model.
	TitleModel string `json:"title_model,omitempty"`
	// Capabilities optionally declares the model's attachment capabilities,
	// overriding the automatic models.dev-based detection. See [CapabilitiesConfig].
	Capabilities *CapabilitiesConfig `json:"capabilities,omitempty"`
}

type PermissionsConfig struct {
	// Allow lists tool name patterns that are auto-approved without user confirmation
	Allow []string `json:"allow,omitempty"`
	// Ask lists tool name patterns that always require user confirmation,
	// even for tools that are normally auto-approved (e.g. read-only tools)
	Ask []string `json:"ask,omitempty"`
	// Deny lists tool name patterns that are always rejected
	Deny []string `json:"deny,omitempty"`
}

type PostEditConfig struct {
	Path string `json:"path"`
	Cmd  string `json:"cmd"`
}

type ProviderConfig struct {
	// Provider specifies the underlying provider type. Supported values include:
	// "openai", "anthropic", "google", "amazon-bedrock", "dmr", and any built-in alias.
	// Defaults to "openai" when not set, preserving backward compatibility.
	Provider string `json:"provider,omitempty"`
	// APIType specifies which API schema to use. Only applicable for OpenAI-compatible providers.
	// Supported values:
	// - "openai_chatcompletions" (default for openai): Use the OpenAI Chat Completions API
	// - "openai_responses": Use the OpenAI Responses API
	APIType string `json:"api_type,omitempty"`
	// BaseURL is the base URL for the provider's API endpoint
	BaseURL string `json:"base_url,omitempty"`
	// UnloadAPI is the path (or absolute URL) to the provider's
	// model-unload endpoint. When the agent wires the [unload] builtin
	// into its `on_agent_switch` hook chain, the previous agent's
	// models are POSTed `{"model": "<id>"}` here at every switch.
	// Cloud providers should leave this unset.
	//
	// [unload]: https://pkg.go.dev/github.com/docker/docker-agent/pkg/hooks/builtins#Unload
	UnloadAPI string `json:"unload_api,omitempty"`
	// TokenKey is the environment variable name containing the API token
	TokenKey string `json:"token_key,omitempty"`
	// Temperature is the default sampling temperature for models using this provider
	Temperature *float64 `json:"temperature,omitempty"`
	// MaxTokens is the default maximum number of tokens for models using this provider
	MaxTokens *int64 `json:"max_tokens,omitempty"`
	// TopP is the default top-p sampling parameter
	TopP *float64 `json:"top_p,omitempty"`
	// FrequencyPenalty is the default frequency penalty
	FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`
	// PresencePenalty is the default presence penalty
	PresencePenalty *float64 `json:"presence_penalty,omitempty"`
	// ParallelToolCalls controls whether parallel tool calls are enabled by default
	ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty"`
	// ProviderOpts allows provider-specific options
	ProviderOpts map[string]any `json:"provider_opts,omitempty"`
	// TrackUsage controls whether token usage tracking is enabled by default
	TrackUsage *bool `json:"track_usage,omitempty"`
	// ThinkingBudget controls reasoning effort/budget for models using this provider
	ThinkingBudget *ThinkingBudget `json:"thinking_budget,omitempty"`
	// TaskBudget caps the total tokens a model can spend across an agentic task.
	// Forwarded to Anthropic as `output_config.task_budget` for every Claude
	// model — docker-agent does not gate by model name. At the time of writing,
	// only Claude Opus 4.7 actually honors it; other models will reject the
	// field. Accepts an integer token count or a {type: tokens, total: N} object.
	TaskBudget *TaskBudget `json:"task_budget,omitempty"`
	// Auth selects a non-API-key authentication scheme for this provider
	// (currently: Anthropic Workload Identity Federation). When set, the
	// provider's regular API-key path is bypassed.
	Auth *AuthConfig `json:"auth,omitempty"`
}

type RAGChunkingConfig struct {
	Size                  int  `json:"size,omitempty"`
	Overlap               int  `json:"overlap,omitempty"`
	RespectWordBoundaries bool `json:"respect_word_boundaries,omitempty"`
	// CodeAware enables code-aware chunking for source files. When true, the
	// chunking strategy uses tree-sitter for AST-based chunking, producing
	// semantically aligned chunks (e.g., whole functions). Falls back to
	// plain text chunking for unsupported languages.
	CodeAware bool `json:"code_aware,omitempty"`
}

type RAGConfig struct {
	Tool       RAGToolConfig       `json:"tool"`                  // Tool configuration
	Docs       []string            `json:"docs,omitempty"`        // Shared documents across all strategies
	RespectVCS *bool               `json:"respect_vcs,omitempty"` // Whether to respect VCS ignore files like .gitignore (default: true)
	Strategies []RAGStrategyConfig `json:"strategies,omitempty"`  // Array of strategy configurations
	Results    RAGResultsConfig    `json:"results"`
}

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

type RAGFusionConfig struct {
	Strategy string             `json:"strategy,omitempty"` // Fusion strategy: "rrf" (Reciprocal Rank Fusion), "weighted", "max"
	K        int                `json:"k,omitempty"`        // RRF parameter k (default: 60)
	Weights  map[string]float64 `json:"weights,omitempty"`  // Strategy weights for weighted fusion
}

type RAGRerankingConfig struct {
	Model     string  `json:"model"`               // Model reference for reranking (e.g., "hf.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF")
	TopK      int     `json:"top_k,omitempty"`     // Optional: only rerank top K results (0 = rerank all)
	Threshold float64 `json:"threshold,omitempty"` // Optional: minimum score threshold after reranking (default: 0.5)
	Criteria  string  `json:"criteria,omitempty"`  // Optional: domain-specific relevance criteria to guide scoring
}

type RAGResultsConfig struct {
	Limit             int                 `json:"limit,omitempty"`               // Maximum number of results to return (top K)
	Fusion            *RAGFusionConfig    `json:"fusion,omitempty"`              // How to combine results from multiple strategies
	Reranking         *RAGRerankingConfig `json:"reranking,omitempty"`           // Optional reranking configuration
	Deduplicate       bool                `json:"deduplicate,omitempty"`         // Remove duplicate documents across strategies
	IncludeScore      bool                `json:"include_score,omitempty"`       // Include relevance scores in results
	ReturnFullContent bool                `json:"return_full_content,omitempty"` // Return full document content instead of just matched chunks
}

type RAGStrategyConfig struct {
	Type     string            `json:"type"`            // Strategy type: "chunked-embeddings", "bm25", etc.
	Docs     []string          `json:"docs,omitempty"`  // Strategy-specific documents (augments shared docs)
	Database RAGDatabaseConfig `json:"database"`        // Database configuration
	Chunking RAGChunkingConfig `json:"chunking"`        // Chunking configuration
	Limit    int               `json:"limit,omitempty"` // Max results from this strategy (for fusion input)

	// Strategy-specific parameters (arbitrary key-value pairs)
	// Examples:
	// - chunked-embeddings: embedding_model, similarity_metric, threshold, vector_dimensions
	// - bm25: k1, b, threshold
	Params map[string]any // Flattened into parent JSON
}

type RAGToolConfig struct {
	Name        string `json:"name,omitempty"`        // Custom name for the tool (defaults to RAG source name if empty)
	Description string `json:"description,omitempty"` // Tool description (what the tool does)
	Instruction string `json:"instruction,omitempty"` // Tool instruction (how to use the tool effectively)
}

type RAGToolset struct {
	Toolset `json:",inline" yaml:",inline"`
}

type Remote struct {
	URL           string             `json:"url"`
	TransportType string             `json:"transport_type,omitempty"`
	Headers       map[string]string  `json:"headers,omitempty"`
	OAuth         *RemoteOAuthConfig `json:"oauth,omitempty"`
}

type RemoteOAuthConfig struct {
	ClientID     string   `json:"clientId"`
	ClientSecret string   `json:"clientSecret,omitempty"`
	CallbackPort int      `json:"callbackPort,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
	// CallbackRedirectURL, when set, is used as the OAuth redirect URI
	// instead of the default http://127.0.0.1:{callbackPort}/callback.
	// This allows inserting a public-facing proxy (e.g. a URL shortener or
	// a pre-registered static redirect) in front of the local callback
	// server — useful for authorization servers that require the redirect
	// URI to be HTTPS or pre-registered.
	//
	// The literal placeholder ${callbackPort} is replaced with the actual
	// port the local callback server is listening on (either CallbackPort
	// when set, or a random free port otherwise). The external URL is
	// expected to redirect the browser back to
	// http://127.0.0.1:{callbackPort}/callback preserving the OAuth query
	// parameters.
	CallbackRedirectURL string `json:"callbackRedirectURL,omitempty"`
}

type RoutingRule struct {
	// Model is a reference to another model in the models section or an inline model spec (e.g., "openai/gpt-4o")
	Model string `json:"model"`
	// Examples are phrases that should trigger routing to this model
	Examples []string `json:"examples"`
}

type RuntimeDefaults struct {
	// Sandbox, when true, runs the agent inside a Docker sandbox by
	// default — equivalent to passing --sandbox on the command line.
	// Useful for agents that always need filesystem/network isolation.
	Sandbox bool `json:"sandbox,omitempty" yaml:"sandbox,omitempty"`

	// NetworkAllowlist is the list of hosts that should be added to
	// the sandbox's default-deny network proxy when this agent runs in
	// a sandbox. Each entry is a hostname with an optional ":port"
	// suffix (e.g. "api.example.com", "registry.npmjs.org:443"). The
	// list is unioned with the gateway and tool-install hosts the
	// runner already opens automatically; commas and whitespace are
	// rejected to keep a single entry from smuggling several rules
	// into the policy engine.
	//
	// Use this when an agent's tools call hosts the auto-installer
	// can't infer (custom MCP endpoints, third-party APIs, registries
	// not covered by the aqua resolver, etc.) instead of relying on
	// the wider fallback host set the kit uses on resolution failures.
	NetworkAllowlist []string `json:"network_allowlist,omitempty" yaml:"network_allowlist,omitempty"`
}

type ScriptShellToolConfig struct {
	Cmd         string `json:"cmd"`
	Description string `json:"description"`

	// Args is directly passed as "properties" in the JSON schema
	Args map[string]any `json:"args,omitempty"`

	// Required is directly passed as "required" in the JSON schema
	Required []string `json:"required"`

	Env        map[string]string `json:"env,omitempty"`
	WorkingDir string            `json:"working_dir,omitempty"`
}

type SkillsConfig struct {
	// Sources lists where to load skills from: "local" and/or HTTP/HTTPS URLs.
	Sources []string
	// Include optionally filters loaded skills by name. When non-empty, only
	// skills whose Name matches an entry in this list are exposed to the agent.
	Include []string
	// Inline holds skills defined directly in the agent config. They are
	// always exposed (never subject to the Include filter) and are not
	// affected by Sources.
	Inline []InlineSkill
}

type StructuredOutput struct {
	// Name is the name of the response format
	Name string `json:"name"`
	// Description is optional description of the response format
	Description string `json:"description,omitempty"`
	// Schema is a JSON schema object defining the structure
	Schema map[string]any `json:"schema"`
	// Strict enables strict schema adherence (OpenAI only)
	Strict bool `json:"strict,omitempty"`
}

type TaskBudget struct {
	// Type is the budget kind. Only "tokens" is supported today; defaults to
	// "tokens" when Total is set via the integer shorthand.
	Type string `json:"type,omitempty"`
	// Total is the total budget value (token count for Type == "tokens").
	Total int `json:"total,omitempty"`
}

type ThinkingBudget struct {
	// Effort stores string-based reasoning effort levels
	Effort string `json:"effort,omitempty"`
	// Tokens stores integer-based token budgets
	Tokens int `json:"tokens,omitempty"`
}

type Toolset struct {
	Type        string   `json:"type,omitempty"`
	Tools       []string `json:"tools,omitempty"`
	Instruction string   `json:"instruction,omitempty"`
	Toon        string   `json:"toon,omitempty"`

	// ReadOnly restricts the toolset to tools whose annotations carry a
	// read-only hint. Every other tool is filtered out, so the agent can
	// list and call only the non-mutating subset of the toolset.
	ReadOnly bool `json:"readonly,omitempty" yaml:"readonly,omitempty"`

	// Model overrides the LLM used for the turn that processes tool results
	// from this toolset, enabling per-toolset model routing. Value can be a
	// model name from the models section or "provider/model" (e.g. "openai/gpt-4o-mini").
	Model string `json:"model,omitempty"`

	Defer DeferConfig `json:"defer,omitzero" yaml:"defer,omitempty"`

	// For the `mcp` tool
	Command string   `json:"command,omitempty"`
	Args    []string `json:"args,omitempty"`
	Ref     string   `json:"ref,omitempty"`
	Remote  Remote   `json:"remote"`
	Config  any      `json:"config,omitempty"`

	// For `mcp` and `lsp` tools - version/package reference for auto-installation.
	// Format: "owner/repo" or "owner/repo@version"
	// When empty and auto-install is enabled, docker agent auto-detects from the command name.
	// Set to "false" or "off" to disable auto-install for this toolset.
	Version string `json:"version,omitempty"`

	// For the `a2a`, `api`, `openapi` and `fetch` tools
	Name    string            `json:"name,omitempty"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`

	// For `shell`, `script`, `mcp` or `lsp` tools
	Env map[string]string `json:"env,omitempty"`

	// For the `todo` tool
	Shared bool `json:"shared,omitempty"`

	// For the `memory` and `tasks` tools
	Path string `json:"path,omitempty"`

	// For the `script` tool
	Shell map[string]ScriptShellToolConfig `json:"shell,omitempty"`

	// For the `filesystem` tool - post-edit commands
	PostEdit []PostEditConfig `json:"post_edit,omitempty"`

	APIConfig APIToolConfig `json:"api_config"`

	// For the `filesystem` tool - VCS integration
	IgnoreVCS *bool `json:"ignore_vcs,omitempty"`

	// For the `filesystem` tool - allow-list of directories the tools are
	// permitted to access. Each entry may be "." (the agent's working
	// directory), "~" or "~/..." (the user's home directory), an absolute
	// path, or a relative path (anchored at the working directory). When
	// non-empty, every read/write operation is rejected unless its target
	// resolves under one of the listed roots. Symlinks are followed before
	// the containment check so they cannot be used to escape the allow-list.
	// An empty or omitted list preserves the default behaviour (any path
	// reachable by the process is allowed).
	AllowList []string `json:"allow_list,omitempty" yaml:"allow_list,omitempty"`

	// For the `filesystem` tool - deny-list of directories the tools are
	// forbidden to access. Same expansion and matching rules as `allow_list`.
	// The deny-list takes precedence over `allow_list`: a path that matches
	// both is rejected. An empty or omitted list disables the deny-list.
	DenyList []string `json:"deny_list,omitempty" yaml:"deny_list,omitempty"`

	// For the `mcp_catalog` tool - allow-list of catalog server ids that
	// are offered by default. When non-empty, only these servers are
	// searchable and enableable; every other catalog entry is hidden. An
	// empty or omitted list offers the full catalog. Combine with
	// `blocked_servers` to subtract individual ids from the allowed set
	// (block takes precedence).
	AllowedServers []string `json:"allowed_servers,omitempty" yaml:"allowed_servers,omitempty"`

	// For the `mcp_catalog` tool - block-list of catalog server ids that
	// are removed from the offered set. Applied after `allowed_servers`,
	// so a server listed in both is blocked. An empty or omitted list
	// disables the block-list.
	BlockedServers []string `json:"blocked_servers,omitempty" yaml:"blocked_servers,omitempty"`

	// For the `lsp` tool
	FileTypes []string `json:"file_types,omitempty"`

	// HTTP timeout in seconds for `fetch`, `api`, `openapi`, and `a2a` toolsets.
	// Defaults to 30 seconds when omitted.
	Timeout int `json:"timeout,omitempty"`

	// For the `fetch` tool - allow-list of domains the tool is permitted to fetch.
	// A pattern matches the host exactly (case-insensitive) and any of its subdomains;
	// e.g. "example.com" matches "example.com" and "docs.example.com" but not
	// "badexample.com". A leading dot (".example.com") restricts the match to
	// strict subdomains. Mutually exclusive with `blocked_domains`.
	AllowedDomains []string `json:"allowed_domains,omitempty" yaml:"allowed_domains,omitempty"`

	// For the `fetch` tool - deny-list of domains the tool is forbidden to fetch.
	// Uses the same matching rules as `allowed_domains`. Mutually exclusive with
	// `allowed_domains`.
	BlockedDomains []string `json:"blocked_domains,omitempty" yaml:"blocked_domains,omitempty"`

	// For the `fetch`, `api`, `openapi`, `a2a` and remote `mcp` toolsets — opt in
	// to dialling non-public IP addresses.
	//
	// By default, protected HTTP clients refuse connections (after DNS
	// resolution, so DNS rebinding is also blocked) to loopback (127/8,
	// ::1), RFC1918 private ranges, link-local — including the cloud
	// metadata endpoint at 169.254.169.254 — multicast and the unspecified
	// address. Set this to true to permit those addresses, which is required
	// when an agent legitimately needs to call internal services.
	//
	// For `fetch`, `allowed_domains` and `blocked_domains` are evaluated
	// independently of this flag: even with `allow_private_ips: true`, an
	// entry in `blocked_domains` (or absence from `allowed_domains`) still
	// rejects the request before any network call.
	// nil means the field was omitted and may inherit from a referenced definition.
	AllowPrivateIPs *bool `json:"allow_private_ips,omitempty" yaml:"allow_private_ips,omitempty"`

	// For the `shell` toolset — opt in to a sudo privilege escalation flow.
	// When enabled, sudo commands prompt the user for their password (masked)
	// through the host UI via SUDO_ASKPASS; in non-interactive runs the prompt
	// is declined automatically and sudo fails as before. No effect on Windows.
	// nil/false keeps the default behaviour (sudo has no TTY and fails fast).
	SudoAskpass *bool `json:"sudo_askpass,omitempty" yaml:"sudo_askpass,omitempty"`

	// For the `shell` toolset — opt in to destructive-command detection.
	// When enabled, the agent auto-registers the safer_shell builtin under
	// pre_tool_use with preempt_yolo:true. Destructive commands (rm -rf, docker
	// volume rm, mkfs, …) get an Ask verdict carrying a blast-radius
	// classification; known-safe reads (ls, git status, docker ps, …)
	// flow through silently; everything else asks with blast_radius=unknown
	// so the user sees the prompt before --yolo or permission allow-rules
	// can auto-approve it. nil/false leaves the agent's shell calls subject
	// only to the regular approval pipeline.
	Safer *bool `json:"safer,omitempty" yaml:"safer,omitempty"`

	// For the `rag` tool
	RAGConfig *RAGConfig `json:"rag_config,omitempty" yaml:"rag_config,omitempty"`

	// For the `model_picker` tool
	Models []string `json:"models,omitempty"`

	// For `mcp` and `lsp` tools - optional working directory override.
	// When set, the toolset process is started from this directory.
	// Relative paths are resolved relative to the agent's working directory.
	WorkingDir string `json:"working_dir,omitempty"`

	// For `mcp` and `lsp` tools — lifecycle policy controlling startup,
	// restart, and backoff behaviour. nil means "use the resilient defaults"
	// (auto-restart on failure, 5 attempts, 1s..32s exponential backoff).
	Lifecycle *LifecycleConfig `json:"lifecycle,omitempty"`
}