agent

type Agent struct {
	Model     model.Model
	ModelName string
	// FallbackModels is the fallback chain recorded in the trajectory and
	// run.started. Model must then be a *model.Fallback over ModelName
	// followed by these specs; empty means no fallback.
	FallbackModels []string
	// ReasoningEffort is recorded in new trajectories; the Model sends it.
	ReasoningEffort string
	// OpenAIAPI is the openai provider's resolved transport, recorded in
	// trajectories and run.started; the Model uses it.
	OpenAIAPI string
	// Profile is the config profile selected with --profile, recorded in
	// the trajectory and run.started; "" when none.
	Profile string
	// ProviderAPI and ProviderBaseURL describe a config-defined provider,
	// recorded in trajectories and run.started; empty for built-ins.
	ProviderAPI     string
	ProviderBaseURL string
	Tools           *tools.Executor
	// RedactSecrets describes Tools.Redactor by name for the trajectory
	// and run.started; nil when redact_secrets is off.
	RedactSecrets *trajectory.RedactSecretsInfo
	Config        config.AgentConfig
	Out           io.Writer // progress log; nil discards
	Err           io.Writer // warnings; nil discards
	Verbose       bool
	// Streamed means the model already wrote its text to Out as it arrived.
	Streamed bool
	// CompactFirst compacts the conversation before the run's first model
	// request, whatever its size (chat's /compact). NoCompact wins.
	CompactFirst bool
	// SkipAgentsMD stops Run from appending the nearest AGENTS.md at or above
	// <root> to the system prompt.
	SkipAgentsMD bool
	// ScopedAgentsMD delivers AGENTS.md files in directories below <root>
	// with the results of the built-in file tools that touch paths there
	// (--scoped-agents-md). SkipAgentsMD turns it off.
	ScopedAgentsMD bool
	// SkillsEnabled records that skills discovery was on for this run; the
	// discovered skills are Tools.Skills.
	SkillsEnabled bool
	// Plugins records the loaded plugins for trajectories and run.started.
	Plugins []trajectory.PluginInfo
	// Memory is the project memory loaded at run start (memory.enabled);
	// nil means memory is off. Its section follows AGENTS.md.
	Memory *ProjectMemory
	// Ratchet is the Project rules section (issue #249) placed after the
	// project memory section; "" adds nothing.
	Ratchet string
	// TaskPreamble is placed before the task in a fresh run's first user
	// message (the session handoff, issue #251); t.Task stays the task.
	TaskPreamble string
	// NoCompact turns off context compaction: the full history is always
	// sent, and a context-overflow error ends the run.
	NoCompact bool
	// Hooks run around tool calls the executor permits, and stop hooks
	// before a successful finish; nil runs none.
	Hooks *hooks.Runner
	// Policy is the compiled tool permission policy; nil enforces nothing.
	// It is applied between the executor's Permits check and the hooks, so a
	// denial reuses the error-result path and hooks never override it.
	Policy *permissions.Policy
	// Lockdown is the run's untrusted-content taint state (#171); nil is
	// off. Children share their parent's.
	Lockdown *lockdown.State
	// PermissionApprover answers a policy "ask" through the channel the run
	// has (a terminal prompt, ACP session/request_permission, ...). nil
	// resolves asks with the policy's non-interactive decision.
	PermissionApprover func(ctx context.Context, req permissions.Request) permissions.Answer

	// OnStep is called after every step, e.g. to save the trajectory. A
	// non-nil error stops the run.
	OnStep func(*trajectory.Trajectory) error
	// OnEvent receives machine-readable progress events when configured.
	OnEvent func(string, map[string]any)
	// Resume, when non-nil, continues that trajectory instead of starting a
	// fresh run: its messages, accounting totals, and steps are the starting
	// state, and a continuation notice is appended before the first request.
	Resume       *trajectory.Trajectory
	ResumeSource string // audit-only input path for resume provenance
	// FollowUp, with Resume, continues a finished (Submitted or Completed)
	// checkpoint with this new user instruction, or answers a NeedsInput
	// checkpoint's question. It must be empty for an unfinished checkpoint
	// and set for the others.
	FollowUp string
	// Continue marks Resume as the trajectory this process's previous Run
	// returned (an ACP session's earlier turn), not a loaded checkpoint:
	// the checks against changes between invocations are skipped, and
	// FollowUp continues it whatever status that turn ended with.
	Continue bool
	// TaskImages (--image) are attached to the task message of a fresh run,
	// or to the follow-up message with FollowUp. The message text gets one
	// label line per image.
	TaskImages []model.Image
	// OutputSchema, when non-nil, adds the submit_result tool and makes the
	// run succeed only with a result that validates against it.
	OutputSchema *outschema.Schema
	// Snapshots, when non-nil, captures the workspace: a baseline before
	// the first request, before every tool batch that can change files, and
	// at the end of the run (--snapshots).
	Snapshots Snapshotter
	// Worktree, when non-nil, records the --worktree checkout a fresh run
	// works in; it is copied into the new trajectory.
	Worktree *trajectory.WorktreeInfo
	// Review, when non-nil, records the change set a fresh review run was
	// given; it is copied into the new trajectory.
	Review *trajectory.ReviewInfo

	// Subagents runs the opt-in delegate tool's children; Tools.Delegate
	// offers the tool. nil leaves delegate calls failing with an error.
	Subagents *Subagents

	// Workers runs the opt-in worker tool's children; Tools.Workers
	// offers the tool. nil leaves worker calls failing with an error.
	Workers *Workers
	// Routes are the resolved model routes (main, delegated tasks) this
	// run uses, reported in run.started; informational only.
	Routes []routing.Route
	// Helpers maps an auxiliary task (routing.TaskCompaction,
	// routing.TaskReview) to the model serving it; a task without an
	// entry uses Model.
	Helpers map[string]model.Model
	// UsageRole and UsageTask label this agent's own requests in
	// usage_by_role and model.request; empty means main/main.
	UsageRole, UsageTask string
	// contains filtered or unexported fields
}

type ChildRoute struct {
	Match     []string
	Type      string
	Model     model.Model
	ModelName string
}

type Options struct {
	// Identity: what runs and how it is recorded.
	Model           model.Model
	ModelName       string
	FallbackModels  []string
	ReasoningEffort string
	OpenAIAPI       string
	Profile         string
	ProviderAPI     string
	ProviderBaseURL string
	Routes          []routing.Route
	Helpers         map[string]model.Model

	// Tools and the limits, policy and hooks around them.
	Tools         *tools.Executor
	Config        config.AgentConfig
	RedactSecrets *trajectory.RedactSecretsInfo
	Hooks         *hooks.Runner
	Policy        *permissions.Policy
	Lockdown      *lockdown.State
	Subagents     *Subagents
	Workers       *Workers
	OutputSchema  *outschema.Schema
	Snapshots     Snapshotter

	// Output.
	Out      io.Writer
	Err      io.Writer
	Verbose  bool
	Streamed bool

	// Context and instructions.
	SkipAgentsMD   bool
	ScopedAgentsMD bool
	NoCompact      bool
	CompactFirst   bool
	TaskImages     []model.Image
	Worktree       *trajectory.WorktreeInfo
	Review         *trajectory.ReviewInfo

	// Resume: what this run continues.
	Resume       *trajectory.Trajectory
	ResumeSource string
	FollowUp     string
	Continue     bool
}

type ProjectMemory struct {
	// Path is the store file the entries came from.
	Path string
	// Lines are the loaded entries, newest first.
	Lines []memory.Line
	// Omitted counts active entries left out to stay within max_bytes.
	Omitted int
}

type Snapshotter interface {
	Take(kind string, step int) (trajectory.Snapshot, error)
}

type Subagents struct {
	// Model and ModelName are the children's model; the caller builds it
	// (by default the parent's model spec, without streaming).
	Model     model.Model
	ModelName string
	// MaxSteps caps each child's model calls; 0 means
	// config.DefaultSubagentMaxSteps.
	MaxSteps int
	// Streamed reports whether Model writes text to the terminal itself.
	Streamed bool
	// Routes pick another model per task (models.delegated.routes).
	Routes []ChildRoute
}

type Workers struct {
	// Model and ModelName are the workers' model (by default the parent's
	// model spec, without streaming).
	Model     model.Model
	ModelName string
	// MaxSteps caps each worker's model calls; 0 means
	// config.DefaultWorkerMaxSteps.
	MaxSteps int
	// Tools are the configured worker tools; nil means
	// config.DefaultWorkerTools. A worker gets only those the parent has.
	Tools []string
	// Routes pick another model per task (models.delegated.routes).
	Routes []ChildRoute
	// RunName prefixes worker branch and worktree names
	// (tinyagent/<RunName>-w<n>); "" generates one per process.
	RunName string
	// MaxConcurrent caps how many of one response's worker calls run at
	// once; 0 or 1 runs them one at a time.
	MaxConcurrent int
}