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
	// Provider is the concrete provider used by this specialist.
	Provider 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 ApprovalResolution struct {
	AskID    string
	ReviewID string
	Kind     session.GuardrailApprovalKind
	Verdict  session.ApprovalVerdict
}

type ArtifactHandle string

type AskResolution uint8

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, usage session.AuxiliaryUsage, 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
	// ProviderModel is the exact provider/model selected for the tier-4 call.
	ProviderModel session.ProviderModelID
	// 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, session.AuxiliaryUsage, error)
}

type Compactor interface {
	Compact(ctx context.Context, conv *session.Conversation) (compacted []session.Message, summary string, usage session.AuxiliaryUsage, 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
	// ToolReviewer performs contextual action and inbound review when configured.
	ToolReviewer ToolReviewer
	// ReviewEvidencePreparer mints authority-bound finite evidence inventories for
	// each contextual review. A nil preparer yields an explicitly incomplete inventory.
	ReviewEvidencePreparer ReviewEvidencePreparer
	// ReviewDetails receives bounded live-only human review detail.
	ReviewDetails ReviewDetailSink
	// ReviewTaskWindow selects the last K accepted genuine root prompts supplied as
	// principal task facts. Values are clamped to 1..3; zero defaults to 1.
	ReviewTaskWindow int
	// PlanApprovals owns process-local, single-use plan approval receipts.
	PlanApprovals PlanApprovalStore
	// 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
	ProjectInstructionMaxBytes int
	// 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
	// ProviderModel is the exact immutable provider/model identity selected by
	// composition for this engine's primary LLM calls. Utility-result collection uses
	// it to attribute this engine's main usage; nested auxiliary usage retains its
	// producer's own attribution. The request itself remains provider-neutral.
	ProviderModel session.ProviderModelID
	// 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 token ceiling for one run: when lifetime main
	// usage since the Run's immutable baseline 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 delegated-model
	// router. Its configured backend, classifier model, and optional threshold remain
	// available when pin/fork/resume/family gates skip Route. Route returns a typed
	// backend-neutral result: Category and Model are validated candidates, OK says
	// whether the route was accepted, Confidence is optional backend-native evidence,
	// and Usage is folded into the parent session on every classifier call.
	//
	// Composition owns the classifier, taxonomy, category-to-model mapping, and
	// same-provider target construction. The engine owns routing eligibility, the
	// per-run three-miss breaker, bounded delegation-start evidence, and fail-soft
	// fallback. Candidate fields never assert which model actually ran; the enclosing
	// delegation payload's Model and accepted-route fields remain authoritative.
	// DEFAULT nil means no configured router and produces no RoutingDecision. Child
	// engines force it nil (the no-nesting recursion guard). The callback receives the
	// run context so cancellation bounds classification; it is never a port.LLMRequest
	// field.
	SubagentModelRouter *SubagentModelRouter

	// 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 (fire-result delivery). 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 / event-log 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 GuardrailReviewFailure interface {
	GuardrailReviewFailureCode() ReviewFailureCode
}

type GuardrailReviewTerminalFailure interface {
	GuardrailReviewTerminalFailure() bool
}

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
	// Provider is the concrete provider backing Engine.
	Provider string
	// 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 Shell (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 Shell 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 Shell 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).
	// 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/Shell. 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
	// Selector is the composition-validated explicit target, if one was requested.
	Selector *ResolvedModelSelector
}

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 ModelRouteResult struct {
	Category   string
	Provider   string
	Model      string
	Usage      session.AuxiliaryUsage
	Reason     string
	OK         bool
	Confidence *float64
}

type ModelTarget struct {
	Provider string
	Model    string
}

type ParallelOption func(*ParallelTool)

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

type PermissionReviewPolicyProvider interface {
	GuardrailPermissionReviewEligible(session.ToolCall) bool
}

type PlanApprovalReceipt struct {
	// Ref is the opaque, non-empty receipt identity.
	Ref string
	// SessionID binds the receipt to exactly one session.
	SessionID session.SessionID
	// Call identifies the PresentPlan call the operator approved.
	Call session.ToolCallID
	// TargetMode is the successfully entered execution mode.
	TargetMode session.PermissionMode
}

type PlanApprovalStore interface {
	RecordPlanApproval(PlanApprovalReceipt)
	ConsumePlanApproval(session.SessionID) (PlanApprovalReceipt, bool)
}

type PreparedReviewEvidence struct {
	Source   ReviewEvidenceSource
	Evidence []ReviewEvidenceMeta
	Complete bool
	Close    func()
}

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

type PreparedRunTransition string

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 ResolvedModelSelector struct {
	Target                 ModelTarget
	ActualProvider         string
	ProviderBearing        bool
	ExplicitRouterCategory string
}

type ResumeApprovalOptions struct {
	// CanPresentAuthorization permits this resumed main run to present a newly
	// required external authorization. The zero value fails closed.
	CanPresentAuthorization bool
}

type ReviewAssessment string

type ReviewCaller struct {
	Role         string
	Isolated     bool
	Capabilities []string
}

type ReviewCapacity struct {
	MaxEvidenceHandles int
	MaxEvidenceBytes   int64
	MaxTrajectoryFacts int
	MaxTrajectoryBytes int64
}

type ReviewConcern struct{ Ref, Category, Rationale, SourceRef string }

type ReviewDetail struct {
	RootSessionID, SessionID                     session.SessionID
	ReviewID, Concern, SourceDisplay, NextAction string
}

type ReviewDetailSink interface {
	PublishReviewDetail(context.Context, ReviewDetail)
}

type ReviewEvidence struct {
	Handle, Kind, Version string
	Continuation          string
	Complete              bool
	Content               string
}

type ReviewEvidenceMeta struct {
	Handle, Kind, Display, Version string
	// Continuation is the next opaque handle for the same versioned evidence
	// object. Empty means this page is final.
	Continuation string
	Complete     bool
}

type ReviewEvidencePreparation struct {
	Request     ToolReviewRequest
	Environment tool.Environment
	Owner       *session.Principal
	Result      *session.ToolResult
	// Authorize verifies one evidence-source call against the originating run's
	// effective catalog, mode, and bound authority. Preparers must call it before
	// touching backend metadata or content; model/reviewer input cannot replace it.
	Authorize func(context.Context, session.ToolCall) error
}

type ReviewEvidencePreparer interface {
	PrepareReviewEvidence(context.Context, ReviewEvidencePreparation) (PreparedReviewEvidence, error)
}

type ReviewEvidenceRequest struct{ ReviewID, Handle, Version string }

type ReviewEvidenceSource interface {
	ReadReviewEvidence(context.Context, ReviewEvidenceRequest) (ReviewEvidence, error)
}

type ReviewEvidenceUse struct {
	Handle, Version string
	Supports        []string
}

type ReviewFailureCode string

type ReviewFailureRecorder interface {
	RecordGuardrailReviewFailure(ToolReviewResult, error)
}

type ReviewGrantStore interface {
	GrantDigest(request ToolReviewRequest) (digest string, eligible bool)
	AllowsGrant(digest string) bool
	ArmGrant(digest, sessionID string)
}

type ReviewJob string

type ReviewMetadataProvider interface {
	GuardrailReviewMetadata(toolName string, job ReviewJob) (ruleID, ruleOrigin, providerID, modelID string)
}

type ReviewMissingEvidence struct{ Ref, Kind, Handle, Reason string }

type ReviewPolicyProvider interface {
	GuardrailReviewPolicy(toolName string, job ReviewJob, operationalFailure bool) (applies, enforce bool)
}

type ReviewPrincipalFact struct {
	Kind, Ref, Statement string
	PositiveVerdict      bool
}

type ReviewTarget struct{ Kind, Display, DestinationID string }

type ReviewTrajectoryFact struct {
	Call                                                    session.ToolCallID
	Ref, Direction, DataClass, TargetID, Decision           string
	SessionID, Tool, ApprovalOrigin, ApprovalKind, ReviewID string
}

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

type RunOutcome int32

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
	// CanPresentAuthorization permits this main run to present a required external
	// authorization. The zero value fails closed.
	CanPresentAuthorization bool
	// 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.
	//
	// 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 "a durable host passes its own RunID" means —
	// 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.
	RunID string
	// AskIDDiscriminator, when non-empty, supplies the colon-free HOST namespace
	// of every askID minted this run. Live issuance appends a per-run `.aN`
	// occurrence token to the opaque call component, making repeated approvals for
	// one call distinct while retaining the exact host suffix and four-component
	// colon grammar. The host value remains reconstructable from persisted state.
	// 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.
	//
	// 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
	// contains filtered or unexported fields
}

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

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

type ShellStatusTool struct{}

type ShellTool struct{}

type SteerOutcome string

type SubagentModelRouter struct {
	Backend           string
	ClassifierModel   string
	MinimumConfidence *float64
	Route             func(context.Context, string) ModelRouteResult
}

type SubagentOption func(*SubagentTool)

type SubagentSelectorResolver func(provider, model string) (ResolvedModelSelector, error)

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/Shell). 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"`
	// Agent optionally names a configured specialist definition.
	Agent string `json:"agent,omitempty"`
	// Provider and Model form this member's optional explicit selector.
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,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 ToolReviewRequest struct {
	ReviewID               string
	Job                    ReviewJob
	Event                  governance.HookEvent
	EffectiveCall          session.ToolCall
	PrincipalFacts         []ReviewPrincipalFact
	PrincipalFactsComplete bool
	Caller                 ReviewCaller
	Environment            session.EnvironmentRef
	Target                 ReviewTarget
	Evidence               []ReviewEvidenceMeta
	EvidenceComplete       bool
	Trajectory             []ReviewTrajectoryFact
	TrajectoryComplete     bool
	Capacity               ReviewCapacity
}

type ToolReviewResult struct {
	Assessment ReviewAssessment
	Concerns   []ReviewConcern
	Evidence   []ReviewEvidenceUse
	Missing    []ReviewMissingEvidence
}

type ToolReviewer interface {
	Review(context.Context, ToolReviewRequest, ReviewEvidenceSource) (ToolReviewResult, session.AuxiliaryUsage, error)
}

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