agent

type AgentMeta struct {
	// Name is the agent def's routing key (the value the model passes as `agent`).
	Name string
	// Description is the one-line summary the model uses to choose a specialist.
	Description string
	// Limits are the per-def session stop conditions the child session runs under
	// when this agent is selected. The composition root derives them from the def's
	// maxTurns/maxToolCalls (per-field falling back to the Subagent tool's default
	// limits), so a def with no limits carries the same bound as the default
	// explorer. A zero Limits value is treated as "no per-def override" — Execute
	// then uses the Subagent tool's default limits, exactly as the no-`agent` path does.
	Limits session.Limits
	// AuthorityCeiling is the resolved read-only definition tool ceiling. It is
	// honoured only when Managed is true; lower tiers can never establish a ceiling.
	AuthorityCeiling governance.CapabilitySet
	// WritableAuthorityCeiling is the corresponding direct-write ceiling used only
	// for a fresh mode:"read-write" delegation to this definition.
	WritableAuthorityCeiling governance.CapabilitySet
	Managed                  bool
}

type ArtifactHandle string

type BashStatusTool struct{}

type BashTool struct{}

type BranchJudge interface {
	// Judge picks the winner among candidates, guided by criteria. It returns the
	// 0-based position WITHIN candidates (not a branch index) and a short rationale.
	// Implementations MUST be non-interactive and bounded. ParallelTool treats a nil
	// error with an out-of-range index — or any error — as "fall back to the first
	// successful branch", so a judge must never be load-bearing for correctness.
	Judge(ctx context.Context, candidates []BranchSummary, criteria string) (winner int, rationale string, err error)
}

type BranchSummary struct {
	// Label is the branch's stable, human-meaningful tag (e.g. "branch-2").
	Label string
	// Summary is the branch's terminal result text.
	Summary string
	// Failed reports whether the branch failed. ParallelTool only ever passes
	// SUCCESSFUL candidates to a judge (you cannot pick a crashed branch), so this
	// is false in the default flow; the field exists so a future caller (e.g. a
	// team tournament) can pass the full set if it wants.
	Failed bool
}

type CascadeCompactor struct {
	// Counter sizes the history between tiers; nil → HeuristicTokenCounter.
	Counter TokenCounter
	// BudgetTokens is the target the cascade reduces toward. Tiers stop running
	// once the history is at or below it. Zero means "run every deterministic
	// tier once" (snip→strip→collapse), which is the offline default.
	BudgetTokens int
	// KeepLastTurns overrides cascadeKeepLastTurns when > 0.
	KeepLastTurns int
	// StripToolBodyChars overrides cascadeStripToolBodyChars when > 0.
	StripToolBodyChars int
	// MaxCollapseChars overrides cascadeMaxCollapseChars when > 0.
	MaxCollapseChars int

	// LLM, when non-nil, enables tier 4 (LLM summary of the oldest segment). When
	// nil the cascade stops at tier 3 and never makes a model call.
	LLM port.LLMProvider
	// Model is the model identifier passed to the LLM on the tier-4 summary call.
	Model string
	// SummaryMaxTokens is the SOFT size budget for the tier-4 summary, expressed
	// in the summariser PROMPT (the trailing instruction), not enforced — the
	// model may overshoot and the cascade accepts it (fail-open). It is NOT a
	// port.LLMRequest field: the request stays provider-neutral, so the budget
	// rides as prompt text only. Zero means defaultSummaryMaxTokens.
	SummaryMaxTokens int
}

type ChildAskReview struct {
	// Allowed reports the verdict. An allow approves THIS ONE call only — it is
	// never learned as a rule, so an identical later command is reviewed again.
	Allowed bool
	// Reason is the reviewer's short rationale. On a deny it is folded (clamped)
	// into the message the child model sees and into the operator audit line; on
	// an allow it rides the audit line.
	Reason string
}

type ChildAskReviewRequest struct {
	// Ask is the child's pending permission ask under review.
	Ask session.PendingAsk
	// Isolated reports whether the command would run inside an isolated,
	// throwaway worktree/fork (its filesystem effects confined to a disposable
	// copy of the workspace; the process, network, and absolute paths are NOT
	// isolated). A reviewer may weigh this when judging filesystem-mutating
	// commands.
	Isolated bool
}

type ChildAskReviewer interface {
	Review(ctx context.Context, req ChildAskReviewRequest) (ChildAskReview, error)
}

type Compactor interface {
	Compact(ctx context.Context, conv *session.Conversation) (compacted []session.Message, summary string, err error)
}

type DelegationTightening struct {
	Tools                    []string `json:"tools,omitempty"`
	RemainingDelegationDepth *int     `json:"remaining_delegation_depth,omitempty"`
	FileSystem               *bool    `json:"filesystem,omitempty"`
	DirectWrite              *bool    `json:"direct_write,omitempty"`
}

type Deps struct {
	// LLM is the model-call seam.
	LLM port.LLMProvider
	// Catalog is the tool registry; the loop reads Specs(mode) and Lookup(name).
	Catalog *tool.Catalog
	// Policy evaluates each tool call (deny → ask → allow).
	Policy port.PermissionPolicy
	// AuthorityEvaluator authorizes executions for sessions carrying a derived
	// authority set. Bound sessions require an evaluator; composition selects either
	// enforcement or the explicit noop evaluator when it mints bound sessions.
	AuthorityEvaluator port.AuthorityEvaluator
	// Hooks runs the PreToolUse / PostToolUse lifecycle hooks.
	Hooks port.HookRunner
	// Store persists session state (optional; nil disables persistence).
	Store port.SessionStore
	// SessionLiveness is the optional lifecycle-exclusion seam for engine-owned
	// child sessions. The parent run registers each delegation child before it can
	// queue or drive and releases it on every terminal or pre-start-abort path.
	// Composition may back it with both process-local tracking and SessionLease;
	// registration failure prevents the child from becoming runnable.
	SessionLiveness port.SessionLiveness
	// Clock supplies wall time for tool-call timing (optional; nil → no timing).
	Clock port.Clock
	// ToolCallRecorder records tool-execution observability — the tool-call audit
	// seam (optional; nil → no recording).
	ToolCallRecorder port.ToolCallRecorder
	// Sink, when non-nil, also receives every Event the loop emits, in addition
	// to the Run.Events() channel which is always the primary surface.
	Sink port.EventSink
	// EnableDurableEvidence emits debugger-only request manifests and accepts
	// sanitized provider-attempt observations. It is opt-in because constructing
	// that evidence requires hashing/counting, contexts, maps, and slices; hosts
	// should enable it only when their relay persists events to a durable EventLog
	// for later inspection. Sink presence is not a durability signal.
	EnableDurableEvidence bool
	// Diagnostics is the general-purpose operational logging seam (optional; nil →
	// port.NopDiagnostics, applied in NewEngine, so the engine never nil-panics and
	// stays silent when no sink is injected). It is DISTINCT from ToolCallRecorder
	// (the per-tool audit seam) and Sink (the model's conversation stream).
	Diagnostics port.Diagnostics
	// LearningMode and LearningObserver install the optional completed-trajectory
	// observation seam. Observation is synchronous and runs once after each eligible
	// clean completion. The zero mode, Off, or a nil observer is inert.
	LearningMode     learning.Mode
	LearningObserver learning.Observer
	// Compactor compresses history at the threshold; nil → HeuristicCompactor.
	Compactor Compactor
	// TokenCounter estimates history size for the compaction trigger (and is
	// shared with the Compactor); nil → HeuristicTokenCounter.
	TokenCounter TokenCounter
	// Instructions assembles the project-instruction messages recorded once at
	// the start of a run; nil → prompt.RootAssembler (root-only AGENTS.md /
	// CLAUDE.md, the v1 default).
	Instructions prompt.InstructionAssembler
	// CommandExpander rewrites a raw user prompt into the text the model sees,
	// expanding slash-command invocations (e.g. "/review foo.go") against the
	// workspace before the prompt is recorded; nil → prompt.NoopExpander (no
	// expansion, the v1 default).
	CommandExpander prompt.CommandExpander
	// PromptConfig seeds the cache-stable system prompt (role/tone/safety). The
	// loop fills in Tools and the volatile Env per turn.
	PromptConfig prompt.Config
	// PromptBuilder assembles the layered system prompt each turn. nil →
	// prompt.Build (the v1 default: coding-agent role/tone/safety + tool
	// inventory), byte-identical to v0.0.1. A host that needs a fully host-owned
	// system prompt (e.g. a non-coding agent) supplies a prompt.Builder here; it
	// receives the same Config the loop builds (Tools + volatile Env and live
	// operator profile filled per turn) and returns the Layered prompt. Only the
	// MAIN loop's buildRequest routes through this field — the compaction summarizer
	// (cascade.go) builds its own prompt.Layered directly and is unaffected.
	PromptBuilder prompt.Builder
	// OperatorProfileSource supplies full durable user facts. When non-nil it is
	// read before every model request; failures are fail-soft and retain the last
	// good snapshot within the run.
	OperatorProfileSource prompt.OperatorProfileSource

	// Model is the provider model identifier sent on every request.
	Model string
	// ContextWindow returns the model's context window in tokens, resolved LIVE at
	// the point of use (the compaction check / Engine.ContextWindow) rather than
	// frozen at construction — so a post-construction live-catalog refresh self-
	// corrects on the next turn without rebuilding the engine. A nil closure OR a
	// <=0 return DISABLES compaction (preserving the old "zero disables"). The
	// closure is a stdlib func value; it is built in composition (internal/app)
	// over the FIXED (provider, model) so the engine itself imports no adapter.
	ContextWindow func() int
	// CompactionRatio overrides defaultCompactionRatio when in (0,1].
	CompactionRatio float64

	// Role is the operator-facing label this engine logs under in diagnostics: the
	// empty string for the MAIN engine (correlated by session only), or a non-empty
	// role for a child/subagent engine (e.g. "task" for the Subagent tool, a team
	// member's name, or a fork-branch label) so interleaved child diagnostics are
	// readable. It is read once per run when binding the run-scoped Diagnostics (see
	// drive): empty → only the "session" key; set → "session"+"agent" keys. It is
	// NOT plumbed into Sink/ToolCallRecorder (those stay off for children) and never
	// reaches the model.
	Role string

	// MaxNoProgressNudges bounds how many times the loop injects a continuation
	// ("please continue") user message after a completed turn that produced NEITHER a
	// tool call NOR meaningful assistant text (a reasoning-only / empty turn). It is
	// the blast-radius knob for the no-progress handler. Semantics (applied in
	// NewEngine): a ZERO value (the default; existing Deps built without it) uses the
	// safety-net default defaultNoProgressNudges (2); a NEGATIVE value DISABLES nudging
	// entirely (a no-progress turn terminates immediately with StopNoProgress, the old
	// behaviour minus the silent StopEndTurn mislabel); a positive value overrides the
	// default. It is a loop concern, exactly like CompactionRatio — NOT a
	// port.LLMRequest field (the request stays provider-neutral). Composition plumbs it
	// from Config so it is operator-tunable; children inherit the default.
	MaxNoProgressNudges int

	// Interactive reports whether a HUMAN approver is attached to this engine's runs:
	// true for the bidi Converse / HTTP-SSE surfaces where a client can answer a
	// permission ask, false for a headless/in-process run (the demo, a RunTeam with no
	// attached client). It is composition's knowledge of whether an approval UI exists,
	// set on the MAIN engine only and read once per run (drive) to (a) install the
	// child-ask router so a subagent's ask can be SURFACED to the human, and (b) tell a
	// subagent posture whether to surface (interactive) or auto-deny (headless). It is a
	// plain bool — NOT a port.LLMRequest field and never reaches the model. Child engines
	// leave it false (a child never surfaces further). DEFAULT false (fail-safe: a run
	// with no declared approver auto-denies a subagent ask rather than hanging).
	Interactive bool

	// PlanModeAutoApprove is an OPT-IN, OPERATOR-TIER-ONLY, DEFAULT-OFF flag that
	// tells the engine to SURFACE a plan-approval ask (PresentPlan) even when headless
	// (no human approver attached), so the composition layer's Service can auto-resolve
	// it via ApprovePlan without operator interaction. It is DELIBERATELY ONLY the
	// PresentPlan gate — a non-plan ask (policy/hook) is still headless-auto-denied.
	// DEFAULT false (fail-safe: a headless plan ask is auto-denied like every other ask).
	// It is a plain bool — NOT a port.LLMRequest field and never reaches the model.
	// Child engines inherit it from the parent (so a Subagent/team child's plan ask also
	// parks rather than auto-denies), allowing composition to auto-approve at the Service
	// layer.
	PlanModeAutoApprove bool

	// ChildAskReviewer, when non-nil, reviews a child agent's (subagent / team
	// member / parallel branch) permission ask that the harness could not resolve
	// statically and that no attached human can answer — instead of blanket-denying
	// it. It is consulted ONLY for a headless run with no interactive approver, and
	// never for a deliberately-configured "ask" rule (that always demands a human).
	// An allow grants the one call only (nothing is learned); a deny — or any review
	// failure, timeout, or ambiguous verdict — keeps the call denied, so a reviewer
	// is fail-safe and never load-bearing for safety. Reviews are bounded by a
	// 30-second deadline and serialised through a per-run consecutive-failure
	// breaker (ChildAskReviewMaxDenies). DEFAULT nil: a headless ask is
	// blanket-denied, the long-standing behaviour. Set this on the engine whose runs
	// have no human approver; an engine whose runs surface asks to a client leaves
	// it unused (the surface path wins).
	ChildAskReviewer ChildAskReviewer

	// ChildAskReviewMaxDenies is the per-run circuit-breaker threshold for
	// ChildAskReviewer: after this many CONSECUTIVE non-allow review outcomes (deny
	// verdicts, failures, timeouts, ambiguous verdicts — an abstention via
	// ErrNotReviewable does not count) within one run, further asks skip the reviewer
	// and fall through to auto-deny, bounding reviewer spend. An allow resets the
	// count. <=0 (the default) uses a built-in threshold of 3. Only consulted when
	// ChildAskReviewer is set.
	ChildAskReviewMaxDenies int

	// MaxRunTokens is the loop-level cumulative TOKEN ceiling for a single run: when
	// the run's accumulated session.Usage (input+output, via Usage.TotalTokens) crosses
	// this value, the loop terminates CLEANLY at the next turn boundary with
	// session.StopBudget. It is the shared runaway brake the AGENT-TEAMS-SPIKE named the
	// missing token budget — checked in drive Step 2, so it serves EVERY engine: main +
	// Subagent + Team member + lead synthesis + Fork branch. Semantics: 0 (the default;
	// existing Deps built without it) DISABLES the budget (behaviour byte-identical to
	// before); a positive value is the ceiling. It is a turn-BOUNDARY check (never a
	// mid-stream abort), so an in-flight turn always completes and
	// no-replay-after-first-chunk holds; the terminal is non-error, so the session ends
	// COMPLETED and stays Reopen-recoverable (mirrors StopNoProgress exactly). It is a
	// loop concern, like CompactionRatio / MaxNoProgressNudges — NOT a port.LLMRequest
	// field (the request stays provider-neutral). Composition plumbs it from Config so it
	// is operator-tunable; children INHERIT it (childEngineDepsForProvider keeps it) and a
	// per-call override may only TIGHTEN it.
	MaxRunTokens int

	// SubagentModelRouter, when non-nil, is the OPT-IN semantic model router (ADR
	// 0031, the Phase 5 headline feature): given a Subagent call's (model-authored,
	// untrusted) task prompt it returns the ALREADY-RESOLVED concrete model id to mint
	// the child on, plus the category label it classified into, plus the classifier's
	// session.Usage (which the dispatch-path routeTask closure folds into the parent
	// sess.Usage so classifier spend counts against --max-run-tokens — the #92 fix).
	// It is a composition closure — the engine layer is model-string-only (the layering
	// rule): composition owns the classifier engine, the category taxonomy, and the
	// category→model mapping (aliases/slots/the allowlist cap), and hands the engine
	// only func(ctx, string)(string, string, session.Usage, string, bool) (the trailing
	// string is the miss REASON — issue #287, logged VERBATIM at the dispatch chokepoint
	// on a miss; empty on a hit). The reason is OPERATOR-DIAGNOSTIC detail: it also rides
	// the delegation-start event's RoutingReason field, but ONLY after the engine's
	// event-safe allowlist (routingReasonPayload) confines it to the harness/composition
	// metadata constants — an external composition returning a provider error body,
	// classifier output, or a task excerpt sees it substituted with a generic label on the
	// wire (gauntlet #7), while the verbatim text stays in the diagnostics channel. It is consulted by
	// the Subagent run() hook ONLY for a plain default delegation (no per-call model,
	// no agent, no fork, no resume) and is FAIL-SOFT throughout: ok=false (any
	// classifier failure, an unknown category, the breaker open) → the call falls
	// through to the inherited default explorer model, byte-identically to a deployment
	// with no router. DEFAULT nil: no router, the long-standing behaviour. Set on the
	// MAIN engine only (a child has no Subagent tool, so structurally no router);
	// childEngineDepsForProvider forces it nil (the no-nesting recursion guard). Like
	// ChildAskReviewer, the router is built into the per-call parentCaps.routeTask
	// closure in Engine.parentCaps, never called directly by the loop, so it is NOT a
	// port.LLMRequest field and never reaches a request.
	//
	// The ctx is the RUN's ctx (threaded down via parentCaps.routeTask), NOT
	// context.Background(): a Run.Cancel between the breaker's hardAbort check and the
	// classifier call must propagate into RunModelRouter so the classifier turn dies
	// with the run instead of running out its 30s clock (issue #94 — the
	// cancellation-propagation gap the hardAbort TOCTOU otherwise leaves). Fail-soft
	// holds regardless: a cancelled ctx yields StopCancelled → ok=false → inherit the
	// default model, exactly the existing miss path.
	SubagentModelRouter func(ctx context.Context, taskPrompt string) (category, model string, usage session.Usage, missReason string, ok bool)

	// ProgressiveTools, when true, enables progressive tool disclosure
	// (pattern 9): the per-turn request advertises lightweight specs for tools
	// implementing tool.Disclosable plus a built-in ToolSearch tool the model
	// uses to hydrate a full spec on demand. The DEFAULT (false) sends every
	// tool's full spec every turn, exactly as v1 does. The ToolSearch tool is
	// registered into the catalog by NewEngine only when this is enabled.
	ProgressiveTools bool

	// DeliveryQueue, when non-nil, is the DURABLE per-session pending-delivery queue
	// the loop's turn-boundary drain reads (ADR 0075 decision #3, fire-result-delivery
	// Scenario 4). The fire path (composition) enqueues a rendered fire-result note
	// for an origin session that is BUSY or AWAITING (it cannot drive a delivery run
	// without colliding); the loop drains the pending notes at Step 2a, BEFORE
	// BeginTurn — the SAME turn-boundary seam injectBackgroundNotice uses — recording
	// each as an ordinary harness-framed user continuation (recordContinuation) and
	// marking it delivered via MarkDelivered (the session-scoped exactly-once ledger).
	//
	// The drain is registered on the MAIN + per-session engines ONLY — never on child
	// engines (a child origin degrades to pull-only with a WARN at the fire path). nil
	// (the default) is the byte-identical no-delivery path: nothing drains, the
	// fire path's enqueue is a no-op against a nil queue. It is a port (port.DeliveryQueue),
	// so the agent package imports no concrete adapter.
	DeliveryQueue port.DeliveryQueue

	// EnableSteer, when true, arms each Run with an in-memory, best-effort
	// steer inbox (steer-while-running, issue #512): an operator-supplied
	// instruction enqueued mid-run that the loop drains at the next turn
	// boundary (Step 2a, the same seam injectBackgroundNotice /
	// drainPendingDelivery use) and records as an ordinary user continuation
	// via recordContinuation, so it replays to the model and flows through
	// compaction / session.ValidateToolPairing / ADR-0038 rehydration
	// unchanged. It is a plain loop-concern bool — NOT a port.LLMRequest field
	// and never reaches the model as anything but an ordinary recorded user
	// message. DEFAULT false (the zero value): no inbox is armed and the drain
	// is a strict no-op, byte-identical to the pre-steer posture. Composition
	// plumbs it from Config; child engines inherit the shared deps.
	// A pending (un-drained) steer is in-memory only and lost with the run —
	// never persisted (see steer.go).
	EnableSteer bool
}

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

type EngineAskReviewerOption func(*engineAskReviewer)

type EngineJudgeOption func(*engineJudge)

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

type HeuristicCompactor struct {
	// MaxToolBodyChars overrides maxToolBodyChars when > 0.
	MaxToolBodyChars int
	// KeepLastTurns overrides keepLastTurns when > 0.
	KeepLastTurns int
}

type HeuristicTokenCounter struct {
	// CharsPerToken overrides charsPerToken when > 0.
	CharsPerToken int
}

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

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

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

type ManualCompactionResult struct {
	Changed bool
	Archive []session.Message
	Summary string
}

type MemberBuild struct {
	// Engine is the member's loop engine. It must be non-nil; AddMember rejects a
	// nil Engine with ErrNilEngine.
	Engine *Engine
	// Mode is the optional per-member permission mode. Empty => the team default.
	Mode session.PermissionMode
	// Limits are the OPTIONAL per-member, per-round stop conditions resolved from the
	// member's agent definition (its maxTurns/maxToolCalls). A zero Limits field means
	// "use the supervisor's team default" (s.limits / WithTeamLimits) for THAT field,
	// exactly as an empty Mode falls back to s.mode — the factory is the only place
	// that resolves a def to limits, so the mapping stays in the composition layer and
	// the supervisor stays agnostic of agent definitions. A wholly zero Limits leaves
	// the member on the team default, unchanged.
	Limits session.Limits
	// Close, if non-nil, tears down resources the factory opened for THIS member —
	// specifically the inline per-agent MCP manager(s) connected for the member's
	// agent definition (a reference entry opens nothing, so it contributes no Close).
	// The supervisor composes it with the member's fork cleanup so it runs on every
	// teardown path (cleanupAll, a failed/stopped member, a rejected enrolment).
	Close func() error
	// MCPToolNames are the names of MCP tools the factory added to this member's
	// catalog (from its def's mcpServers). MCP tools report ReadOnly()==false but
	// touch only the remote server, never the workspace, so the supervisor EXEMPTS
	// them from the read-only-member workspace-mutating-tool backstop — exactly like
	// the team coordination tools. Empty when the def scopes no MCP servers.
	MCPToolNames []string
	// IsolateReadOnly tells the supervisor this is a NON-mutating member that the
	// factory nonetheless gave Bash (i.e. it put a workspace-mutating shell into a
	// read-only member's catalog because a read-only forker is available). When true
	// the supervisor runs the member in an isolated git WORKTREE (via s.roForker) so
	// its mutating-classified Bash lands in a throwaway checkout, never the shared
	// base — and the read-only-member workspace-mutating-tool backstop EXEMPTS it
	// (the guard gates on base-sharing, and an isolated member is not base-sharing).
	// It is false for a base-sharing read-only member (no shell) and for a Mutating
	// member (the Mutating flag already drives its force-copy fork). The factory must
	// set it true ONLY when it actually added Bash to a non-mutating catalog AND a
	// read-only forker is available; setting it without a wired forker trips
	// ErrReadOnlyShellNoForker.
	IsolateReadOnly bool
}

type MemberDisposition string

type MemberEngine func(spec MemberSpec, routedModel string) MemberBuild

type MemberOutcome struct {
	// Name is the member name.
	Name string
	// LastText is the member's most recent terminal assistant text.
	LastText string
	// Stopped reports whether the supervisor descheduled the member before the team
	// finished (its last run failed or was cancelled, or it exhausted its lifetime turn
	// budget), so it ran no further rounds.
	Stopped bool
	// Disposition is the member's TERMINAL disposition (done / stopped). It is the
	// closed-enum form of Stopped: Disposition == DispositionStopped iff Stopped.
	Disposition MemberDisposition
	// Reason is WHY a stopped member stopped (error / cancelled / budget); empty for a
	// done member.
	Reason MemberStopReason
	// ErrorRounds is how many of this member's rounds ended in session.StopError,
	// whether it was RETRIED through them or finally benched by them (issue #318 /
	// ADR 0200). It is the disposition-HONESTY signal: a bounded retry means
	// a member can fail a round and still finish, and such a member reports
	// DispositionDone with no Reason — so without this count a transient failure would
	// be invisible to the caller and the run would read as silently clean. It is a
	// COUNT, deliberately not a new MemberDisposition value: the disposition is a closed
	// enum mirrored on the proto wire, and "done" is still the honest terminal.
	//
	// It is INDEPENDENT of the terminal: it counts errored rounds over the member's whole
	// LIFETIME (the counter is monotonic — that monotonicity is the retry cap's
	// termination proof), so it does NOT follow from Reason and Reason does not follow
	// from it. 0 exactly when the member never had an errored round. A member benched by
	// its errors has >=1 alongside Stopped/StopReasonError, but so can one benched for
	// cancellation or budget: a member that failed round 1, was recovered and retried,
	// then was cancelled in round 2 reports Reason "cancelled" with ErrorRounds 1. Read
	// the two together, never one from the other.
	ErrorRounds int
	// Completed holds this member's completed-task descriptions (clamped), captured in
	// outcome() from the shared task list. It feeds the ledger-rich deliverable
	// fallback so a degraded report can state what each member actually finished — the
	// "honest gaps" data the incident wanted. Empty for a member that completed no task.
	Completed []string
	// Lead reports whether this member is the coordinating lead. The structured
	// deliverable fallback SKIPS the lead's LastText: after the synthesis turn the
	// lead's last words ARE the synthesis (empty, truncated, or the rejected refusal
	// the fallback exists to replace), so echoing them would re-surface the very text
	// the fallback discarded. The lead's disposition still appears.
	Lead bool
}

type MemberSpec struct {
	// Name is the unique member handle peers address messages to.
	Name string
	// AgentType is the optional agent-definition name this member adopts; passed
	// through to the engine factory and recorded on the team roster.
	AgentType string
	// Lead marks the coordinating member. The lead is NOT auto-assigned tasks (it
	// coordinates); it runs on its initial prompt and whenever it has messages.
	Lead bool
	// Mutating requests a self-contained force-copied fork (own `.git`) for this
	// member, with Edit/Write/Bash. A read-only member (the default) either runs in
	// an isolated git WORKTREE with a shell for inspection (when a read-only forker is
	// wired — the factory sets MemberBuild.IsolateReadOnly) or, failing that, shares
	// the base workspace with no shell. See the package "Workspace policy" doc.
	Mutating bool
	// InitialPrompt is the member's first-turn input, run in round 0 (typically the
	// lead's top-level task, or a teammate's role briefing).
	InitialPrompt string
}

type MemberStopReason string

type ModelRouteCategory struct {
	// Name is the routing key the classifier must echo back as its verdict (and the
	// key composition maps to a concrete model). A verdict naming a category NOT in
	// the request's list is a hallucination → ok=false (fail-soft).
	Name string
	// Description is the one-line summary the classifier reads to choose. Operators
	// are told to make these clear and distinct (the classifier's only signal).
	Description string
}

type ModelRouteRequest struct {
	// TaskPrompt is the Subagent call's `prompt` — model-authored and possibly
	// peer-injected → UNTRUSTED. It is wrapped in a governance.UntrustedFence (framing
	// neutralised) by buildModelRoutePrompt so it can neither forge the verdict nor
	// fabricate a fresh classifier instruction.
	TaskPrompt string
	// Categories are the routing choices (name + description), rendered in the CLEAR
	// (operator-authored, trusted). A verdict must name one of these.
	Categories []ModelRouteCategory
	// Default is the category name the classifier is told to choose when no category
	// clearly fits. It is advisory to the classifier; the caller's own fallback (the
	// inherited model on ok=false) is the real safety net.
	Default string
}

type ParallelOption func(*ParallelTool)

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

type PreservedForkStore interface {
	// Preserve records a winning fork under an opaque artifact handle and retains
	// its private cleanup capability until eviction. The handle is safe to surface;
	// the physical root remains private to the Environment and cleanup closure.
	Preserve(handle ArtifactHandle, cleanup func() error)
}

type ReflectionLimits struct {
	InputBytes           int
	Events               int
	Existing             int
	Candidates           int
	EvidencePerCandidate int
	OutputBytes          int
	Tokens               int
	Timeout              time.Duration
}

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

type RunRequest struct {
	// Text is the (possibly empty) text of the user prompt. Command expansion and the
	// UserPromptSubmit hook operate on Text only; the media Parts pass through untouched
	// and are recorded verbatim on the user message. Text may be empty when Parts
	// carries the content.
	Text string
	// Parts carries non-text media (image/audio) alongside Text. nil for a text-only
	// prompt. The media passes through to the engine untouched.
	Parts []session.Content
	// MaxRunTokensOverride, when > 0, is a per-run TIGHTEN-ONLY override of the engine's
	// Deps.MaxRunTokens budget: the effective ceiling for THIS run is the lower of the
	// two non-zero values (a per-call ceiling may make the run stricter than the operator
	// default, never looser — mirroring the per-call limit tighten-only discipline). 0
	// (the default) inherits the engine's Deps.MaxRunTokens unchanged.
	MaxRunTokensOverride int
	// ExtraTools are run-scoped tools layered OVER the engine's catalog for THIS run
	// only: their specs are advertised to the model this run and they are dispatchable,
	// but they are never registered into the shared catalog (so concurrent runs of the
	// same engine never see them, and the engine is not mutated). A name collision with a
	// catalog tool resolves to the EXTRA tool (the run-scoped overlay wins) for THIS run.
	// The Subagent tool uses this to inject the synthetic SubmitResult deliverable tool for a
	// structured-output child. Every ExtraTool MUST be ReadOnly (it is dispatched on the
	// read-parallel path); a structured-output SubmitResult records into a per-run sink
	// and performs no workspace mutation, so it is read-only.
	ExtraTools []tool.Tool
	// RunID is the opaque, host-minted identity of THIS run (ADR 0249).
	//
	// It does two things and nothing else. Every event this run emits is stamped
	// with it at Run.emit/emitOrAbort, beside the existing Seq stamp, so no relay,
	// transport, or persistence path downstream can omit it. And when
	// AskIDDiscriminator is empty it also SUPPLIES the ask discriminator, which
	// is what ADR 0044 always meant by "a durable host passes its own RunID" —
	// so a durable host sets ONE field, not two carrying the same value.
	//
	// HOST CONTRACT (inherited from AskIDDiscriminator, because it feeds it): the
	// value must be UNIQUE per run-ATTEMPT and STABLE across processes for the
	// SAME attempt, or the CWE-863 askID replay guard weakens. It should be
	// colon-free; a colon-bearing value still stamps events fine but cannot serve
	// as an ask discriminator (the askID grammar would be ambiguous), so the run
	// falls back to the process-global serial for asks and logs a WARN.
	//
	// Empty (the zero value) is the legacy behaviour exactly: events carry an
	// empty RunID and asks use the process-global serial. mecatui, mecademo, and
	// tests pass nothing and are unaffected.
	//
	// The loop's licence over this value is deliberately narrow: STAMP it, and
	// DERIVE the ask discriminator from it. It must never be branched on, logged,
	// sent to a provider, or used to reach storage — see ADR 0249's consequences.
	RunID string
	// AskIDDiscriminator, when non-empty, REPLACES the trailing process-global
	// "r<serial>" component of every askID minted this run (see agent.newAskID),
	// making the askID reconstructable across processes from persisted state. The
	// askID format is "<sessionID>:<n>:<callID>:<discriminator>". HOST CONTRACT:
	// the host MUST supply a value that is (a) UNIQUE per run-ATTEMPT and (b)
	// STABLE across processes for the SAME attempt — this preserves the CWE-863
	// replay guard the process-global serial provides (the Interrupt/re-mint
	// scenario documented on newAskID): a stale verdict for a retracted ask must
	// never resolve a re-minted ask of a different attempt. (c) It MUST be
	// colon-free to keep the askID grammar unambiguous; a value containing a colon
	// is IGNORED and the run falls back to the process-global "r<serial>" (a WARN
	// is logged) rather than minting an ambiguous id. Empty (the zero value) keeps
	// the legacy "r<serial>" behavior with no change — mecatui, tests, and
	// in-memory hosts pass nothing and are unaffected. A durable host (e.g. a downstream consumer)
	// passes its own RunID. Same opt-in RunRequest seam pattern as
	// MaxRunTokensOverride/ExtraTools. See ADR-0044.
	//
	// FOOTGUN GUARD: after startRun the RESOLVED value (this when valid, else the
	// "r<serial>" fallback) lives on Run.askDiscriminator. askID minting (newAskID,
	// in authorize) MUST read r.askDiscriminator — NEVER this raw, un-validated
	// r.req.AskIDDiscriminator, which may be empty or colon-bearing and would
	// bypass the colon/empty fallback.
	AskIDDiscriminator string
}

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

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

type SteerOutcome string

type SubagentOption func(*SubagentTool)

type SubagentStatusTool struct{}

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

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

type SupervisorOption func(*Supervisor)

type TeamEvent struct {
	// Member is the name of the member whose session produced Event.
	Member string
	// MemberSessionID is the producing member's child SESSION id (MemberSessionID:
	// "team-<teamID>-<member>") — the uniform cancel/inspect handle, forwarded onto
	// the team.member projection so a client can address the member (CancelChild)
	// without deriving the id grammar. The same for every event of a given member.
	MemberSessionID string
	// MemberIncarnation binds internal durable event correlation to this member lifetime.
	MemberIncarnation session.IncarnationID
	// Event is the underlying session Event (turn.start, tool.call, result, ...).
	Event session.Event
	// ContextWindow is the producing member engine's context window in tokens
	// (Engine.ContextWindow), the denominator for the per-member context meter. It
	// is the same for every event of a given member; projectTeamEvent forwards it
	// onto the turn.end projection (0 when the member's engine has no window set).
	ContextWindow int
}

type TeamMemberArg struct {
	// Name is the member's unique handle peers address messages to.
	Name string `json:"name"`
	// Role is the member's role briefing — its first-turn instruction. It becomes
	// the member's InitialPrompt.
	Role string `json:"role"`
	// Mutating requests a self-contained copied workspace (own `.git`) with
	// edit/write/shell tools (Edit/Write/Bash). A read-only member (the default,
	// false) runs in an isolated throwaway git worktree with full shell for
	// INSPECTION (git log/show, cat, build, test) but no Edit/Write. Neither tier is
	// merged back into the base.
	Mutating bool `json:"mutating,omitempty"`
}

type TeamMemberEngineFactory func(t *team.Team, spec MemberSpec, routedModel string) MemberBuild

type TeamOption func(*TeamTool)

type TeamOutcome struct {
	// Rounds is the number of scheduling rounds that ran work.
	Rounds int
	// Quiescent reports whether the team reached genuine completion (all tasks
	// done, mailboxes empty, no member still working) versus stopping because a
	// round planned no work while tasks remained (a stuck dependency / deadlock).
	Quiescent bool
	// Members holds each member's terminal summary in enrolment order.
	Members []MemberOutcome
	// Report is the LEAD's consolidated synthesis — the team's deliverable, produced
	// by a final synthesis turn in Run after the scheduling loop. It is the value the
	// Team tool returns as its ToolResult. It is empty when synthesis could not run
	// (no lead, lead stopped, or the lead produced no text); the caller then renders
	// the degraded joinTeamFallback concatenation instead.
	Report string
	// Findings is the team's findings ledger at the end of the Run, snapshotted in
	// append order — the PRIMARY deterministic, member-authored data the degraded
	// deliverable leads with. It is the same data buildSynthesisSources reads
	// (s.team.Findings()), captured onto the outcome so BOTH the Team-tool deliverable
	// path and the gRPC RunTeam consumer get the rich fallback without reaching into
	// the live *team.Team. Bodies are clamped identically to the wire/observability
	// projection (projectTeamFindingsSnapshot).
	Findings []session.TeamFindingSnapshot
	// BudgetExhausted reports that the team-wide token budget (WithTeamTokenBudget)
	// crossed at a round boundary and no further round was scheduled — the in-flight
	// round and the lead's synthesis still completed. false when no budget was set or it
	// never crossed.
	BudgetExhausted bool
	// Usage is the supervisor-accumulated team total — Σ per-drive EvResult.Usage across
	// all members and rounds, synthesis included; equal by construction to the TeamTool
	// sink's turn.end sum, which remains authoritative for the EvTeamEnd payload.
	Usage session.Usage
}

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

type TokenCounter interface {
	// Count returns the estimated token count of a single string.
	Count(text string) int
	// CountMessages returns the estimated token count of a conversation slice,
	// summing each message's text/reasoning/tool bodies plus the per-message and
	// per-role framing overhead the provider adds on the wire.
	CountMessages(msgs []session.Message) int
}

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