subagents

type MultiStepHandler struct {
	// Completer is the LLM provider used by the sub-agent loop.
	Completer provider.Completer
	// FullRegistry is the parent's complete tool registry.
	// The handler creates a restricted copy (minus delegation tools).
	FullRegistry *tools.Registry
	// Dispatcher is the parent session dispatcher. It is used only as a policy
	// source; nested tool execution uses a dispatcher built from the restricted
	// registry.
	Dispatcher *runtime.Dispatcher
	// Model is the model name to use.
	Model string
	// Reasoning is the dial configured for Model, applied to every step of the
	// nested loop so a delegated task does not silently run at a different
	// reasoning depth than the task that spawned it.
	Reasoning reasoning.Setting
	// ReasoningFunc reads a session-owned dial at invocation time. It
	// supersedes Reasoning when present, so a runtime effort choice reaches a
	// handler built before the choice was made.
	ReasoningFunc func() reasoning.Setting
	// SystemPrompt is the system prompt for the sub-agent.
	SystemPrompt string
	// MemoryContext is the rendered core-memory context frame
	// (chat.MemoryContextContent), delivered as a user-role message right
	// after the system message rather than composed into SystemPrompt, so
	// memory changes never touch the cached system-prompt prefix. Empty
	// means no memory injection.
	MemoryContext string
	// MaxSteps is the maximum number of LLM turns.
	MaxSteps int
	// WorkLimits bounds cumulative provider and tool work for this invocation.
	WorkLimits runtime.WorkLimits
	// DisableProviderReplay prevents provider-internal replays for this work.
	DisableProviderReplay bool
	// WireStreamTransport opts every nested turn of this handler into the
	// provider's wire-stream transport: stream:true on the wire, the
	// non-stream contract on the return path. The content-idle watchdog in
	// the provider layer then bounds each attempt, so a keepalive trickle
	// cannot hold a nested turn open past a deterministic bound. Set from
	// [subagents] wire_stream at every construction site.
	WireStreamTransport bool
	// ToolTimeout is the per-tool-call timeout.
	ToolTimeout time.Duration
	// ToolRunTimeout is the [tools] tool_run_timeout_seconds knob: the SDK
	// tool-registry's registry-wide run backstop for tools with no declared
	// Capability.Timeout. <= 0 (the default) means no registry-wide cap
	// (mapped to the SDK's TimeoutNone); see agent.Options.ToolRunTimeout.
	ToolRunTimeout time.Duration
	// RequestTimeout is the per-LLM-request timeout for each turn inside the
	// sub-agent. When zero, the agent loop falls back to the parent context
	// deadline, which may be hours for a long-running root session. A hung LLM
	// call would then block the subagent indefinitely. Handlers set this from
	// [subagents] default_request_timeout_seconds; when that knob is unset,
	// they apply DefaultSubagentRequestTimeoutSec (1800s, 30 minutes) - the
	// 12-hour orchestration default no longer feeds individual requests. The
	// derived http.Client wall stays above this budget plus a margin, so the
	// budget is what ends an overlong request.
	RequestTimeout time.Duration
	// SteerWatchdog bounds steer latency when no interrupt signal is wired: the
	// loop's watcher cancels the in-flight LLM call once a steer has been
	// pending for this long (plan 54 §4.5). 0 disables the watchdog.
	SteerWatchdog time.Duration
	// TotalTimeout is the maximum wall-clock time for the entire sub-agent.
	TotalTimeout time.Duration
	// MaxTokens is the max tokens per LLM response.
	MaxTokens int
	// MaxContextTokens is the local prompt budget for every nested request.
	MaxContextTokens int
	// MaxContextTokensFunc reads a session-owned budget at invocation time.
	// It supersedes MaxContextTokens when present.
	MaxContextTokensFunc func() int
	// MaxToolResultChars caps each tool result stored in the nested loop's
	// history, in bytes. 0 means uncapped. Set from the same
	// [tools] max_tool_result_bytes knob as the interactive session loop.
	MaxToolResultChars int
	// BatchResultBudgetBytes bounds what one nested tool batch adds to the
	// sub-agent's history across all its parallel calls. Same operator knob as
	// the interactive loop ([tools] batch_result_budget_bytes); the counter is
	// per batch, so every nested loop gets its own automatically.
	BatchResultBudgetBytes int
	// RefOnlyTools names tools whose results are always spooled as refs by the
	// nested loop. Same operator knob as the interactive loop
	// ([tools] ref_only_tools); empty = off.
	RefOnlyTools []string
	// RemainderSpool stores truncated tool-result bodies for read_output.
	// Shared with the session's registered read_output tool so notices and
	// reads use one grant domain. Nil omits refs from truncation notices.
	RemainderSpool *remainder.Spool
	// OutputSchema is the handler-default schema (skill/agent). Request.OutputSchema
	// overrides when set. Nil means free-text output.
	OutputSchema map[string]any
	// SchemaRetryMax is corrective re-entries after the first invalid reply.
	// <=0 uses default 2.
	SchemaRetryMax int
	// OnEvent is called for sub-agent tool events (optional, for TUI).
	OnEvent func(agent.Event)
	// ContextPreparationManager is deliberately the preparation-only capability.
	// A nested handler never receives a context store or checkpoint publisher.
	ContextPreparationManager contextmgr.PreparationManager
	ContextPreparationInput   contextmgr.PrepareInput
}

type OneShotHandler struct {
	// Completer is the LLM provider used to make the one-shot call.
	Completer provider.Completer
	// Model is the model name to use (e.g. "deepseek-v4-flash").
	Model string
	// SystemPrompt is the system prompt for the sub-agent LLM call.
	SystemPrompt string
	// MaxContextTokens rejects an irreducible nested prompt locally.
	MaxContextTokens int
	// MaxContextTokensFunc reads a session-owned budget at invocation time.
	// It supersedes MaxContextTokens when present.
	MaxContextTokensFunc func() int
	// MaxTokens reserves the configured completion allowance.
	MaxTokens *int
	// Reasoning is the dial configured for Model. A delegated task runs on a
	// configured model just like the root session, so it must think at the
	// depth that model declares rather than at the provider's default.
	Reasoning reasoning.Setting
	// ReasoningFunc reads a session-owned dial at invocation time. It
	// supersedes Reasoning when present, so a runtime effort choice reaches a
	// handler built before the choice was made.
	ReasoningFunc func() reasoning.Setting
	// TotalTimeout is the maximum wall-clock time for the whole call, with
	// the same semantics as MultiStepHandler.TotalTimeout: <= 0 adds no
	// bound, a tighter req.Timeout wins, and the parent deadline is never
	// extended. Construction sites that carry the
	// default_total_timeout_seconds budget set it via totalTaskTimeout-style
	// resolution; zero leaves the per-task timeout as the only bound.
	TotalTimeout time.Duration
	// OutputSchema is the handler-default schema, mirroring
	// MultiStepHandler.OutputSchema. Request.OutputSchema overrides it; nil on
	// both means a free-text answer.
	OutputSchema map[string]any
	// WireStream opts this one-shot call into the provider's wire-stream
	// transport: stream:true on the wire, the plain non-stream contract on
	// the return path (the full answer still comes back as one string). Set
	// from [subagents] wire_stream at the construction site.
	WireStream bool
}

type Policy struct {
	Workers, MaxDepth, MaxFanout int
	MaxBudget                    int
	Timeout                      time.Duration
	// SpawnStagger delays each subsequent task's job feed inside one batch by
	// this duration, spreading concurrent LLM call starts so N workers do not
	// hit the provider on the same instant (the step-1 thundering-herd hang).
	// Zero disables; the interactive session maps it from
	// [subagents] spawn_stagger_ms.
	SpawnStagger time.Duration
}

type Pool struct {

	// ContextForTask, when set, derives a per-task context from the pool
	// context before dispatch (plan 53). Used to inject task identity and
	// (phase 03) mailbox handles without fingerprinted Task fields.
	ContextForTask func(ctx context.Context, taskID string) context.Context
	// OnTaskDone, when set, is invoked on the worker goroutine immediately
	// after a task's handler returns, with the STAMPED per-task context
	// (ContextForTask has already applied TaskIdentity{RunID, TaskID, Agent})
	// and the computed result (status, output, error). The coordinator uses it
	// to finalize terminal tasks early — CAS the ledger status, mark the
	// mailbox terminal, and decline parked asks — instead of waiting for the
	// whole pool to finish (plan R9). The result value returned to the caller
	// is never modified by the callback; nil means no-op.
	OnTaskDone func(ctx context.Context, t Task, r Result)
	// contains filtered or unexported fields
}

type Result struct {
	TaskID     string
	Output     json.RawMessage
	Err        error
	Status     string
	Provenance runtime.Metadata
}

type Task struct {
	ID, Name, Owner string
	// RawID is the model-supplied task id verbatim, before dispatch_tasks
	// namespaces it into ID for harness-level uniqueness
	// (internal/cliorchestrate/task_namespace.go's namespacedTaskID). Kept
	// alongside ID so tools that only see a run_id - join_run,
	// inspect_agents, run_messages, send_to_task - can report/resolve the
	// id the model actually knows, without guessing at a namespace
	// boundary from ID's string shape. Empty for any caller that never
	// namespaces (spawn_agent, or a task built directly, not through
	// dispatch_tasks).
	RawID string
	// AgentName and AgentDigest identify the immutable authorized definition.
	// Name is a private runtime target and never comes from model input.
	AgentName, AgentDigest, Skill string
	// ProviderName and Model describe the resolved work binding. Current policy
	// re-authorizes them before a resumed task executes.
	// ProviderName and Model ARE included in the coordinator fingerprint
	// projection (spawn.go), so adding or changing them here WILL change
	// idempotency digests for agent-routed tasks. Delegate/oneshot tasks
	// carry empty values so are unaffected by these fields.
	ProviderName, Model string
	// SessionID, TurnID, and Role retain caller identity across asynchronous
	// coordinator execution so nested tool calls remain attributable.
	SessionID, TurnID, Role string
	// InvocationKey scopes dispatcher idempotency independently from the
	// user-facing task ID, which may repeat across batches.
	InvocationKey         string
	DependsOn             []string
	Scope                 string
	Permission            string
	Input                 json.RawMessage
	Depth                 int
	Timeout               time.Duration
	Budget                int
	WorkLimits            runtime.WorkLimits
	DisableProviderReplay bool
	IdempotencyKey        string
	// OutputSchema, when non-nil, is the resolved JSON Schema the child's final
	// reply must satisfy (plan tools/02). Nil means free-text output (today's
	// contract). Work-defining: included in the coordinator fingerprint.
	OutputSchema map[string]any
	// InputSchema, when non-nil, validates Task.Input at admission.
	InputSchema map[string]any
}

type ToolCallSink func(ToolCallStep)

type ToolCallStep struct {
	ToolCallID string
	Name       string
	Kind       string // "start" | "end"
	Input      string
	Output     string
	At         time.Time
}