session

type ApprovalPayload struct {
	// AskID is the id of the resolved permission ask (the same id carried on the
	// EvPermissionAsk that preceded this verdict and on the wire ResumeApproval).
	AskID string
	// Verdict is the resolution as a STRING passthrough: VerdictStringAllowOnce,
	// VerdictStringAllowAlways, or VerdictStringDeny (the EvNoProgress/StopBudget
	// precedent — no proto enum). It is the human/policy decision, never tool
	// content.
	Verdict string
	// Tool is the NAME of the tool the ask gated (e.g. "Bash"). It is the tool
	// name ALONE — never the call's args.
	Tool string
	// Call is the id of the gated ToolCall. It is an OPAQUE identifier, NOT secret
	// content — it is already implicitly encoded inside AskID (see agent.newAskID) —
	// so surfacing it directly opens no new leak surface. It is the durable,
	// grammar-free correlation handle a 3b permstore-replay consumer uses to find the
	// gated ToolCall in the loaded conversation and re-derive its rule from the real
	// args (which stay in the session history, never on this event).
	Call ToolCallID
	// AllowAlways mirrors (Verdict == VerdictStringAllowAlways): the verdict ASKED
	// the harness to learn a per-session allow rule. It is deliberately NOT named
	// "Learned": Policy.Learn no-ops on an unlearnable call (compound/substituted
	// Bash with no targetable pattern), so an allow-always verdict can set this
	// true even when NO rule was actually recorded. It honestly reflects the
	// VERDICT, not the policy outcome. A 3b permstore-replay consumer filtering on
	// this must re-derive the real rule from the conversation (the metadata-only
	// event never carries enough to reconstruct a pattern), so AllowAlways is a
	// filter hint, never a durable rule record.
	AllowAlways bool
}

type ApprovalVerdict int

type AskOrigin int

type Authority struct {
	CapabilitySet      governance.CapabilitySet `json:"capability_set"`
	Provenance         string                   `json:"provenance"`
	DefinitionIdentity string                   `json:"definition_identity,omitempty"`
}

type BlockKind string

type CompactionArchivePayload struct {
	// Replaced is the pre-compaction conversation — the exact Messages slice that
	// ReplaceHistory replaced, captured before the mutation. It is the full
	// pre-compaction history (a superset of the dropped span), so the dropped turns
	// are always recoverable from it regardless of how the Compactor split the cut.
	// See the LOG-GROWTH COST note above for why the full slice (not a delta) is kept.
	Replaced []Message
}

type Content struct {
	// BlockKind discriminates the block variant; "" = legacy media part. Set
	// for tool-result blocks (BlockText/BlockImage/BlockAudio/BlockResourceLink/
	// BlockEmbeddedResource/BlockStructuredContent).
	BlockKind BlockKind `json:"block_kind,omitempty"`
	// Kind discriminates the media kind (image / audio) for legacy media parts
	// and the BlockImage/BlockAudio block variants.
	Kind MediaKind
	// MIMEType is the IANA media type of the part (image, audio, resource).
	MIMEType string
	// Data is the inline content bytes; nil when the part is URL-sourced. For
	// BlockEmbeddedResource it is the binary blob form (exactly one of Text/Data
	// populated); the provider summarizes it, this does NOT base64-dump.
	Data []byte
	// URL is the remote reference; "" when the part is inline. For
	// BlockResourceLink it is the resource URI (a reference, NOT fetched here).
	URL string
	// Text carries the text form for BlockText and BlockStructuredContent, and
	// the text form of a BlockEmbeddedResource (exactly one of Text/Data set).
	Text string `json:"Text,omitempty"`
	// Name is the resource name for a BlockResourceLink.
	Name string `json:"Name,omitempty"`
	// Title is the resource title for a BlockResourceLink.
	Title string `json:"Title,omitempty"`
	// Description is the resource description for a BlockResourceLink.
	Description string `json:"Description,omitempty"`
	// Size is the resource byte size for a BlockResourceLink (advisory).
	Size int64 `json:"Size,omitempty"`
	// Audience is the advisory intended-audience list for a resource block.
	//
	// SECURITY: this is UNTRUSTED SERVER SELF-ATTESTATION (CWE-345). An MCP
	// server (or any tool-result producer) asserts who may view a resource; the
	// harness MUST NOT treat this as authoritative. It is carried through for
	// operator/model visibility ONLY — it NEVER suppresses model-visible
	// content and NEVER gates access control. Enforcement lives in the
	// permission layer, not here.
	Audience []string `json:"Audience,omitempty"`
	// Priority is carried through for a resource block; not consumed in v1.
	Priority float64 `json:"Priority,omitempty"`
	// LastModified is carried through for a resource block; not consumed in v1.
	LastModified string `json:"LastModified,omitempty"`
}

type Conversation struct {
	// Messages is the ordered history sent to the model.
	Messages []Message
}

type Counters struct {
	// Turns is the number of model calls begun.
	Turns int
	// ToolCalls is the total number of tool invocations recorded.
	ToolCalls int
	// ConsecutiveFailures is the current run of back-to-back tool failures; it
	// resets to zero on any successful tool result.
	ConsecutiveFailures int
}

type EnvironmentKind string

type EnvironmentRef struct {
	// Kind names the backend family (local / mem / nofs / …).
	Kind EnvironmentKind
	// ID is the opaque backend identity the adapter that minted the
	// Environment owns. It is never parsed by the session package.
	ID string
	// Revision pins the exact provider inventory generation.
	Revision string
}

type Event struct {
	// Type is the event kind.
	Type EventType
	// Seq is a monotonically increasing sequence number within a run.
	Seq int64
	// Turn is the turn index this event belongs to.
	Turn int
	// Text carries streamed or final text where applicable.
	Text string
	// ToolCall is set on EvToolCall.
	ToolCall *ToolCall
	// ToolResult is set on EvToolResult.
	ToolResult *ToolResult
	// Ask is set on EvPermissionAsk.
	Ask *PendingAsk
	// ModelRetry is set on EvModelRetry and carries the prior failed terminal's
	// typed facts for durable reconstruction without parsing Text.
	ModelRetry *ModelRetryPayload
	// RequestManifest is set on EvRequestManifest. It is log-only structural
	// evidence about the final request and contains no model-visible bodies.
	RequestManifest *RequestManifestPayload
	// NetworkAttempt is set on EvNetworkAttempt. It is log-only sanitized
	// transport/provider evidence emitted by the loop from the resilience observer.
	NetworkAttempt *NetworkAttemptPayload
	// Result is set on EvResult.
	Result *ResultPayload
	// TurnEnd is set on EvTurnEnd (this turn's usage + elapsed time).
	TurnEnd *TurnEndPayload
	// Hook is set on EvHook: the structured phase/tool/decision so clients render
	// hook notices distinctly (and colour blocked ones) rather than parsing Text.
	Hook *HookPayload
	// Approval is set on EvApproval: the resolved verdict (tool name + verdict
	// string + askID + learned flag). It carries NO raw args and NO deny-reason
	// body (gauntlet #7); see ApprovalPayload.
	Approval *ApprovalPayload
	// CompactionArchive is set on EvCompactionArchive: the pre-compaction
	// conversation that ReplaceHistory replaced (the durable non-destructive
	// archive). It is the parent's own history, so it opens no leak surface; see
	// CompactionArchivePayload.
	CompactionArchive *CompactionArchivePayload
	// UserPrompt is set on EvUserPrompt: the user-role message just recorded (Text +
	// Parts). It is the durable record of what the user asked (and the harness's own
	// synthetic continuations), consumed by the EventLog and reconstructed by an
	// event-sourced fold; it is log-only (skipped on the live client wire). See
	// UserPromptPayload.
	UserPrompt *UserPromptPayload
	// Usage is set on usage-bearing events. On EvResult it is the cumulative run
	// total; turn.end carries its per-turn usage in TurnEnd, NOT here.
	Usage *Usage
	// Subagent is set on the three subagent.* events: the REDACTED observability
	// projection of a Subagent child run (metadata only, never child content).
	Subagent *SubagentPayload
	// Team is set on the team.* events (start / member / tasks / end): the BOUNDED
	// observability projection of an in-process team run (fuller-but-bounded; member
	// content is capped and permission.ask is dropped, and never enters the parent
	// conversation).
	Team *TeamPayload
	// Parallel is set on the parallel.* events (start / branch / end): the REDACTED,
	// metadata-only observability projection of a Parallel fork-join run (group-level
	// join/winner facts + per-branch metadata + fork paths, never branch content).
	Parallel *ParallelPayload
	// RunID is the opaque, host-minted identity of the run that emitted this event
	// (ADR 0249). It is STAMPED BY THE LOOP, at Run.emit/emitOrAbort, beside the
	// existing Seq stamp — every event a run emits carries it, so no relay,
	// transport, or persistence path can omit it.
	//
	// It is NOT derive-at-append like Actor, and the difference is deliberate.
	// Actor can be stamped at the server's appendEvent chokepoint because it is
	// log-only; RunID must ALSO reach the client wire (an SDK resolves a started
	// run on the first run-ID-bearing event, and a watch filters envelopes by
	// run), and the wire path never passes through appendEvent. Stamping it "at
	// the relay" would mean stamping it at roughly nine sites by hand.
	//
	// Seq is monotonic WITHIN a run and restarts every run, so it cannot
	// distinguish two runs of one session; RunID is what makes an event
	// attributable to a specific run across restarts and across processes.
	//
	// EMPTY IS MEANINGFUL, not a bug: it means "session-scoped, not run-scoped".
	// The schedule.* lifecycle events are emitted from composition outside any
	// loop and legitimately have no run. The set of event types permitted to carry
	// an empty RunID is CLOSED and enforced by a test, so a new run-less emitter is
	// a visible decision rather than a silent gap. An ergonomic attachment filters
	// to one run and therefore never contains run-less events; a session activity
	// stream includes them, which is why the two are separate operations.
	//
	// A host that supplies no RunID emits events with an empty one, byte-identical
	// to the behaviour before ADR 0249. Like Actor, it is not a reconstruction
	// input: eventsource.Fold ignores it.
	RunID string
	// Actor is the verified caller who ACTED — who drove the request this event
	// belongs to (ADR 0204 decision 5). It is LOG-ONLY and DERIVE-AT-APPEND: every
	// emit site — the loop included — leaves it nil (the loop is storage-agnostic
	// and knows nothing about principals), and the server relay's single appendEvent
	// chokepoint stamps it from the CONTEXT PRINCIPAL just before the durable
	// Append. It never reaches the client wire (toProto has no field for it) and it
	// is not a reconstruction input: eventsource.Fold ignores it, so a folded
	// session keeps the owner its caller restored from the snapshot.
	//
	// Actor is NOT the session's Owner, and the two routinely differ: this phase
	// ships no authorization, so any authenticated caller may act on any session.
	// The owner answers "whose is this?" and remains the identity of record; the
	// actor answers "who did this?". Deriving it from the owner would stamp the
	// owner onto every event of a run somebody else drove — repudiation in both
	// directions, worst on EvApproval, where the record IS a human granting a tool
	// permission. The denormalization is deliberate: an event read in isolation
	// names its actor. A request with no verified caller records a nil Actor;
	// absence is never fabricated.
	Actor *Principal
	// Schedule is set on the schedule.* events (fired / skipped / failed): the
	// scheduler lifecycle projection emitted from composition (the scheduler), NOT
	// the loop. Client-visible (unlike the log-only EvApproval /
	// EvCompactionArchive / EvUserPrompt). See SchedulePayload.
	Schedule *SchedulePayload
	// Steer is set on EvSteer: the committed operator steer the turn-boundary
	// drain just recorded (the authoritative echo). Client-visible. See
	// SteerPayload.
	Steer *SteerPayload
}

type EventType string

type GrantType string

type HookDecision string

type HookPayload struct {
	// Phase is the lifecycle point the hook fired at (e.g. "PreToolUse"); empty
	// when not applicable.
	Phase string
	// Tool is the tool the hook relates to for the per-tool phases; empty
	// otherwise.
	Tool string
	// Decision is the outcome (info / blocked / modified).
	Decision HookDecision
	// CallID is the id of the tool call this hook fired against, for the per-tool
	// phases (PreToolUse / PostToolUse); empty for non-tool phases (e.g. Stop,
	// SessionStart) and for tool phases where no call is in scope. It lets a client
	// address the hook notice to the originating tool card (e.g. mark that exact
	// tool_call as failed) instead of falling back to a free-standing note.
	CallID ToolCallID
}

type IncarnationID string

type Limits struct {
	// MaxTurns caps the number of model calls; 0 disables.
	MaxTurns int
	// MaxToolCalls caps the total tool invocations; 0 disables.
	MaxToolCalls int
	// MaxConsecutiveFailures caps back-to-back tool failures; 0 disables.
	MaxConsecutiveFailures int
}

type MediaKind string

type Message struct {
	// Role is the author of this message.
	Role Role
	// Text is the message body (assistant text, user prompt, etc.).
	Text string
	// ToolCalls holds the tool invocations requested by an assistant message.
	ToolCalls []ToolCall
	// ToolResult holds the result carried by a tool-role message; nil otherwise.
	ToolResult *ToolResult
	// Reasoning is the provider's opaque reasoning REPLAY blob (e.g. OpenAI's
	// reasoning-item encrypted_content, or Anthropic's (thinking,signature) pair),
	// replayed back verbatim on subsequent calls and never interpreted or displayed
	// by the harness. The STRUCTURE is provider-neutral (one opaque blob per
	// message); the CONTENTS are provider-private — each adapter packs/unpacks its
	// own wire shape, so the domain value object stays a bare string (do NOT widen
	// it). It is distinct from the human-readable reasoning SUMMARY surfaced via
	// reasoning.delta events for display: that prose is never stored here.
	Reasoning string
	// ProviderPhase is the OpenAI Responses API's opaque phase marker on an
	// assistant message ("commentary" for intermediate output, "final_answer" for
	// the final answer), replayed back verbatim on subsequent calls and never
	// interpreted or displayed by the harness. For store:false manual-replay apps
	// OpenAI requires preserving and resending it, or GPT-5.x models treat preambles
	// as final answers / stop early. The STRUCTURE is provider-neutral (one opaque
	// phase string per message); the CONTENTS are provider-private (the harness
	// never branches on or validates the value — do NOT widen it). Empty string
	// means "no phase". Same discipline as Reasoning. (Named ProviderPhase, not
	// Phase, to disambiguate from the governance/hook-lifecycle Phase concept, which
	// is interpreted — the opposite contract.)
	ProviderPhase string
	// ReasoningItemID is the OpenAI Responses API's opaque reasoning-item id
	// (the "rs_…" id on the item whose encrypted_content rides Message.Reasoning),
	// replayed back verbatim on subsequent stateless (store:false) calls and never
	// interpreted or displayed by the harness. For store:false manual-replay apps
	// the SDK serialises the assistant reasoning item with its id, and a strict
	// gateway rejects an empty-string id ("id":""), so the id must be preserved
	// alongside the blob or the replay 400s. The STRUCTURE is provider-neutral (one
	// opaque id per message); the CONTENTS are provider-private (the harness never
	// branches on or validates the value — do NOT widen it). Empty string means
	// "no id captured" (e.g. Anthropic, or a pre-fix session). Same discipline as
	// Reasoning/ProviderPhase.
	ReasoningItemID string
	// Parts carries non-text media (image/audio) on a USER message; it is nil for
	// assistant/tool/system messages. Text remains the flattened text body
	// (embedded-text resources collapse into it); Parts carries only the binary or
	// URL-referenced media that rides alongside the text. Do not mutate Parts (or a
	// Part's Data) after construction.
	Parts []Content
}

type ModelRetryPayload struct {
	Disposition RetryDisposition
	Progress    StreamProgress
}

type NetworkAttemptPayload struct {
	SessionID         SessionID `json:"session_id"`
	RunSerial         int64     `json:"run_serial"`
	Turn              int       `json:"turn"`
	Attempt           int       `json:"attempt"`
	MaxAttempts       int       `json:"max_attempts"`
	ElapsedMs         int64     `json:"elapsed_ms"`
	RetryDisposition  string    `json:"retry_disposition"`
	StreamProgress    string    `json:"stream_progress"`
	Decision          string    `json:"decision"`
	SuppressionReason string    `json:"suppression_reason,omitempty"`
	BackoffMs         int64     `json:"backoff_ms"`
	FailureClass      string    `json:"failure_class"`
	HTTPStatus        int       `json:"http_status,omitempty"`
	InBandStatus      int       `json:"in_band_status,omitempty"`
	CorrelationKind   string    `json:"correlation_kind,omitempty"`
	CorrelationDigest string    `json:"correlation_digest,omitempty"`
}

type ParallelEventKind string

type ParallelPayload struct {
	// ParentCallID is the parent's Parallel tool-call id; it is the GROUP key (one
	// Parallel call = one group) and attributes every parallel.* event to the
	// originating Parallel card. Set on all kinds.
	ParentCallID string
	// Kind discriminates the per-branch lifecycle transition (branch_start /
	// branch_tool / branch_end). Set on EvParallelBranch only; empty on the run-level
	// start/end events.
	Kind ParallelEventKind

	// Join is the normalized join strategy ("all" / "first" / "judge"). Set on
	// EvParallelStart and EvParallelEnd (run-level).
	Join string
	// BranchCount is the number of branches in the run. Set on EvParallelStart and
	// EvParallelEnd (run-level).
	BranchCount int

	// BranchIndex is the 0-based branch index — the stable per-branch group key within
	// a Parallel call. Set on every EvParallelBranch kind. (The index is the row key;
	// ChildID below is the ADDRESSING handle.)
	BranchIndex int
	// ChildID is the branch's child SESSION id ("parallel-<callID>-<i>") — the uniform
	// per-child cancel/inspect handle (the same single-handle convention as
	// SubagentPayload.ChildID / the Team member session id), surfaced so a client can
	// address a branch (CancelChild) WITHOUT deriving the id grammar. Set on the
	// branch_start and branch_end kinds. It is an id, never branch content.
	ChildID string
	// ChildIncarnation is internal durable correlation metadata, never projected.
	ChildIncarnation IncarnationID
	// BranchLabel is the humanized 1-based branch label ("branch-1" …). Set on the
	// branch_start kind.
	BranchLabel string
	// Goal is a short, plain-text label for the branch's task (a truncation of the
	// model-authored branch prompt — the parent's own instruction, NOT branch content).
	// Set on the branch_start kind. Clamped identically to SubagentPayload.Goal.
	Goal string
	// RoutedCategory / RoutedModel are the OPT-IN semantic model router's classification
	// for this branch (ADR 0031 / ADR 0034): the chosen CATEGORY label and the concrete
	// MODEL id the branch was minted on. Set on the branch_start kind ONLY when the router
	// was wired AND classified this branch (both empty otherwise — no router, a fail-soft
	// miss that inherited the default branch model, or a branch cancelled before it started).
	// Like SubagentPayload.RoutedCategory/RoutedModel they are BARE METADATA — a category
	// label and a model id, never the branch prompt or the classifier's reasoning — so they
	// are gauntlet-#7 safe (no branch content, no model-influenced free text crosses). They
	// ride the proto/client wire end-to-end (parallel.branch_start: Parallel.routed_category
	// = field 19 / routed_model = field 20), surfaced via the server mapper — see ADR 0034.
	RoutedCategory string
	RoutedModel    string
	// RoutingReason names WHY the router did NOT classify this branch (branch_start kind
	// only): EMPTY on a routed hit (RoutedCategory/RoutedModel set), otherwise one of the
	// RoutingReason* gate constants (router-disabled, or aborted for a branch cancelled
	// before it started) or a static miss code from the classifier (the RouterMiss* values)
	// or composition. Open callback detail is reduced before emission. It is BARE METADATA
	// — a bounded harness/composition reason code, never the branch prompt or classifier
	// reasoning — so it is gauntlet-#7 safe (no branch content crosses). Clamped at the
	// emit site.
	RoutingReason string
	// Model is the concrete MODEL id the branch ACTUALLY ran on (branch_start kind only),
	// set unconditionally — inherited default branch model or the opt-in router —
	// independent of whether the router fired. It is BARE METADATA — a model id, never
	// branch content — so it is gauntlet-#7 safe (no branch content crosses). When the
	// router classified this branch, Model == RoutedModel. It rides the proto/client wire
	// end-to-end (parallel.branch_start: Parallel.model = field 21), surfaced via the
	// server mapper — see ADR 0035.
	Model string

	// ToolName is the name of a branch's child tool that just ran. Set on the
	// branch_tool kind only. It is the tool NAME alone — never branch args/result.
	ToolName string
	// IsError reports whether that branch tool call failed. Set on branch_tool only.
	IsError bool
	// ToolCount is the running (branch_tool) or final (branch_end) number of a branch's
	// child tool calls observed.
	ToolCount int
	// Text is a BOUNDED preview of the branch's message/result text — control-byte
	// scrubbed and rune-capped by clampPreview in engine/agent, never the raw,
	// unbounded body. Set on the branch_tool kind for the message.delta / result
	// inner kinds when a preview is available.
	Text string
	// Detail is a BOUNDED preview of a branch tool call's args (tool.call) or a
	// tool result's body (tool.result) — control-byte scrubbed and rune-capped by
	// clampPreview in engine/agent, never the raw, unbounded args/result body. Set
	// on the branch_tool kind for the tool.call / tool.result inner kinds when a
	// preview is available.
	Detail string
	// InnerKind discriminates which inner branch event kind the preview came from
	// (message.delta / tool.call / tool.result / result). Set on the branch_tool
	// kind alongside Text / Detail. A branch's permission.ask is never projected.
	InnerKind EventType

	// Failed reports whether the branch's child run failed (StopError / cancelled /
	// fork failure). Set on the branch_end kind.
	Failed bool

	// Stop is the branch's terminal stop reason (branch_end) or the run-level stop
	// (EvParallelEnd; the winner's stop for join=first/judge, zero/omitted for join=all).
	Stop StopReason
	// Usage is the branch's cumulative usage (branch_end) or the run TOTAL (EvParallelEnd,
	// summed across branches).
	Usage Usage
	// DurationMs is the branch's wall-clock duration in milliseconds. Set on branch_end.
	DurationMs int64

	// Winner is the branch index of the selected winner on EvParallelEnd — a real
	// BranchIndex for join=first/judge, or -1 for join=all and none-succeeded. Set on
	// EvParallelEnd only.
	Winner int
}

type PendingAsk struct {
	// AskID correlates the ask with the client's resolution.
	AskID string
	// Tool is the name of the tool awaiting approval.
	Tool string
	// Args is the proposed tool-call argument payload.
	Args json.RawMessage
	// Reason explains why approval is required.
	Reason string
	// Call is the id of the gated ToolCall this ask pauses on. It is the
	// REQUEST-half twin of ApprovalPayload.Call (the verdict half): an OPAQUE
	// identifier, NOT secret content — it is already implicitly encoded inside
	// AskID (see agent.newAskID) — so surfacing it directly opens no new leak
	// surface. It is durable, grammar-free correlation data: a host that pauses
	// on a PendingAsk reads Call instead of parsing the AskID grammar. Unlike the
	// run-scoped ConfiguredAsk/FlooredConfiguredAllow below, it round-trips in the
	// snapshot (it is correlation data, not run-scoped policy state).
	Call ToolCallID `json:"call,omitempty"`
	// ConfiguredAsk carries governance.PermissionDecision.ConfiguredAsk onto the
	// pending ask: the Ask came from a deliberately-configured rule (above the
	// built-in floor). An approval layer keys "never auto-approve a configured
	// Ask" on it. It is purely run-scoped state — never serialized to a snapshot
	// (an old snapshot deserializing false is harmless: an ask is never resumed
	// from one). Mutually exclusive with FlooredConfiguredAllow.
	ConfiguredAsk bool
	// FlooredConfiguredAllow carries
	// governance.PermissionDecision.FlooredConfiguredAllow onto the pending ask:
	// the Ask exists only because of the substitution floor, and the command is
	// one the configured policy already allows with provably read-only
	// substitution contents — so an approval layer may relax the floor without
	// surfacing it. Same run-scoped, never-serialized posture as ConfiguredAsk.
	// Mutually exclusive with it (a third RUN-SCOPED ask-provenance signal would
	// warrant collapsing these two into a single enum on both this value object and
	// the governance decision; HookOriginated below is NOT that third signal — it is
	// a different, SERIALIZED axis, see its note).
	FlooredConfiguredAllow bool
	// HookOriginated marks an ask that arose from a PreToolUse hook BLOCK refined
	// into an approval (governance.HookOutcome.AskApproval; ADR 0062), NOT from the
	// permission policy. It is SERIALIZED (json:"hook_originated,omitempty") and is
	// DELIBERATELY a bool, NOT folded into an AskOrigin enum with
	// ConfiguredAsk/FlooredConfiguredAllow: those two are RUN-SCOPED policy hints that
	// are never serialized (an old snapshot deserializing false is harmless because a
	// policy ask is never resumed from one), whereas HookOriginated is CROSS-PROCESS
	// LOAD-BEARING — the awaiting-resume path (Engine.ResumeApproval →
	// resolvePendingCall) runs in a FRESH process and keys the skip-preHook branch on
	// it (an Allow must EXECUTE the tool WITHOUT re-running the PreToolUse hook, which
	// would re-block / re-ask). Collapsing a serialized correctness marker into an
	// enum with two ephemeral hints would conflate two different lifetimes and
	// serialization contracts — so it stays its own bool. Its plan-approval sibling
	// PlanOriginated (issue #206) is the SECOND serialized provenance bit: the two
	// bools are now the serialized contract, and the read-time Origin() accessor
	// derives the single provenance from them.
	HookOriginated bool `json:"hook_originated,omitempty"`
	// PlanOriginated marks an ask that arose from a plan-approval gate (the
	// operator was asked to approve a presented plan; issue #206), NOT from the
	// permission policy or a hook. It is SERIALIZED (json:"plan_originated,omitempty")
	// and CROSS-PROCESS LOAD-BEARING — the awaiting-resume path
	// (Engine.ResumeApproval → resolvePendingCall) runs in a FRESH process and keys
	// the plan-flip branch on it (an Allow flips the session out of plan mode and
	// drives the turn through the completed path with StopPlanApproved; the resumed
	// call is NOT re-presented). It is deliberately a bool sibling of HookOriginated
	// rather than folded into a single enum with ConfiguredAsk/FlooredConfiguredAllow:
	// those two are RUN-SCOPED policy hints that are never serialized, whereas
	// PlanOriginated (like HookOriginated) is a serialized correctness marker that
	// must survive a process restart. The read-time provenance is surfaced via Origin.
	PlanOriginated bool `json:"plan_originated,omitempty"`
}

type PermissionMode string

type PlacementMetadata struct {
	Kind     string `json:"kind,omitempty"`
	Label    string `json:"label,omitempty"`
	Branch   string `json:"branch,omitempty"`
	Revision string `json:"revision,omitempty"`
}

type Principal struct {
	// Issuer is the IdP that minted the token (the canonical `iss` claim).
	Issuer string
	// Subject is the caller id within that issuer (the `sub` claim).
	Subject string
	// GrantType is how the caller authenticated.
	GrantType GrantType
	// Name is an optional human-readable display label. It is never part of
	// identity — display only.
	Name string
}

type RequestManifestPayload struct {
	Provider        string                   `json:"provider,omitempty"`
	Model           string                   `json:"model,omitempty"`
	ReasoningEffort string                   `json:"reasoning_effort,omitempty"`
	ContextWindow   int                      `json:"context_window,omitempty"`
	ToolNames       []string                 `json:"tool_names"`
	ToolDecisions   []RequestToolDecision    `json:"tool_decisions"`
	MessageCount    int                      `json:"message_count"`
	MessageBytes    int                      `json:"message_bytes"`
	Prompt          []RequestPromptComponent `json:"prompt"`
}

type RequestPromptComponent struct {
	Kind       string `json:"kind"`
	Provenance string `json:"provenance"`
	Bytes      int    `json:"bytes"`
}

type RequestToolDecision struct {
	Name     string `json:"name"`
	Source   string `json:"source"`
	Decision string `json:"decision"`
}

type ResultPayload struct {
	// Stop is the reason the run ended.
	Stop StopReason
	// Text is the final assistant text, if any.
	Text string
	// Usage is the cumulative token accounting for the run.
	Usage Usage
	// Error carries the failure detail when Stop is StopError (empty otherwise).
	// It surfaces the error the loop would otherwise drop so callers (the demo,
	// API clients) can see why a run failed instead of an opaque "error".
	Error string
	// Permanent is the compatibility projection of Disposition==Permanent.
	Permanent bool
	// Disposition classifies whether replaying the failed model request is safe.
	Disposition RetryDisposition
	// Progress records how far the terminal model stream advanced semantically.
	Progress StreamProgress
}

type RetryDisposition uint8

type Role string

type SchedulePayload struct {
	// ScheduleName is the schedule that fired / was skipped / failed (the
	// ScheduleSpec.Name foreign key).
	ScheduleName string
	// FireID is the per-fire session id (the same id ScheduleFire.ID and
	// ScheduleFire.SessionID carry — the fire's id IS its session id on the wire,
	// the FireNowResponse.fire_id == session_id contract).
	FireID string
	// SessionID is the session the fire ran as. It equals FireID for a fired
	// fire; it is empty for a skipped fire (no session was created).
	SessionID SessionID
	// Kind is the event kind: "fired" / "skipped" / "failed". String passthrough.
	Kind string
	// Stop is the terminal stop reason of the fire's run (a StopReason). Empty
	// for a skipped fire (no run happened) and for a fired fire that has not yet
	// completed.
	Stop StopReason
	// Err is the error string if the fire's run failed (Kind="failed"), empty
	// otherwise. It is a flat string (no structured error crosses) so a consumer
	// can render it without importing the run's error types.
	Err string
}

type Session struct {
	// ID identifies this session.
	ID SessionID
	// State is the current lifecycle state.
	State State
	// Mode is the permission posture.
	Mode PermissionMode
	// Conversation is the model-visible history.
	Conversation *Conversation
	// Limits are the configured stop conditions.
	Limits Limits
	// Counters are the running totals for stop-condition evaluation.
	Counters Counters
	// Usage is the CUMULATIVE token accounting for the logical run. It is the value
	// the MaxRunTokens budget brake (StopBudget) is evaluated against, so it is
	// persisted into the snapshot and the brake reads it DIRECTLY (the loop keeps a
	// separate zero-based per-run delta for the EvResult figure; there is no seed) —
	// the budget therefore survives reopen/restart instead of re-granting a full
	// fresh allowance every time the session continues. Mutate it through RecordUsage
	// (accumulate) or ResetUsage (the explicit fresh-allowance reset). CRITICAL:
	// unlike Counters, it is NOT cleared by resetToIdle (see the comment there).
	Usage Usage
	// EnvironmentRef is the sole durable identity of the execution environment.
	// It is minted by the placement provider and must be valid before persistence
	// or execution. Resolution to live capabilities belongs to composition.
	EnvironmentRef EnvironmentRef
	// Placement is safe display-only metadata minted by the placement provider.
	// It is persisted for public inventory projection but never used to bind or
	// reattach an environment.
	Placement PlacementMetadata
	// Profile is an opaque tool-surface profile label (e.g. "" for the default
	// filesystem profile, "no-fs" for the no-filesystem one). The aggregate STORES
	// it but never interprets it: the meaning lives entirely in composition, like
	// ProviderID and ModelID. It is a write-once creation label set by the
	// composition root after New (no mutator); persisting it lets a restarted
	// process rebuild the same tool surface. The exact EnvironmentRef remains the
	// sole placement identity.
	Profile string
	// ProviderID and ModelID are the opaque neutral provider+model selector pair
	// this session was bound to. The aggregate STORES them but never interprets
	// them — the ProviderSelector type and all resolution stay in composition; only
	// these two opaque strings cross into the domain. Persisting them lets a
	// restarted process re-derive the same per-session engine via the factory
	// instead of falling to the default-provider floor. They are write-once
	// creation labels set by composition after New (no mutator). The empty pair
	// means "server default".
	ProviderID string
	ModelID    string
	// ReasoningEffort is the opaque neutral reasoning-effort token (ADR 0055) this
	// session was bound to ("" = unset, the provider default). The aggregate STORES
	// it but never interprets it — the neutral vocabulary, normalisation, per-provider
	// clamp, and adapter re-mint all live in composition; only this opaque string
	// crosses into the domain (the same inert-label posture as ProviderID/ModelID).
	// Persisting it lets a restarted process re-mint the SAME per-session engine via
	// the factory instead of falling to the operator default. Write-once creation
	// label set by the composition root after New (no mutator).
	ReasoningEffort string
	// DebugMCPServers and DebugMCPTools are inert, durable labels for a debug
	// session's explicitly selected server-global MCP mount. DebugMCPTools is the
	// exact creation-time tool-name ceiling; rehydration requires exact equality
	// with the selected servers' current direct tool set.
	DebugMCPServers []string
	DebugMCPTools   []string
	// DebugTargetFingerprint binds a debug session to the target incarnation that
	// was authorized at creation. It is internal evidence only and is never
	// projected to clients or the model.
	DebugTargetFingerprint string
	// Title is a human-readable session label seeded ONCE from the first genuine
	// user prompt (via SetTitle, called from the loop's recordPrompt), clamped to
	// maxTitleRunes (120) runes. Subsequent prompts do NOT overwrite it (set-once).
	// It is persisted in the snapshot (an inert stored label, like Profile), and
	// read-time consumers (the lazy ListSessions/GetSession fallback, the
	// event-sourced Fold) use session.IsGenuineUserPrompt to derive it when empty.
	// It is "" for a session with no genuine prompt yet (lazy display-time
	// fallback applies). The aggregate never interprets it.
	Title string
	// TitleProvenance records whether Title came from the first genuine prompt or
	// an explicit operator rename. The zero value means legacy/unknown.
	TitleProvenance TitleProvenance
	// Owner is the verified caller this session is attributed to, or nil when the
	// session is ownerless (a pre-ship snapshot, or a deployment with no identity
	// verifier wired). It is a WRITE-ONCE label stamped through RestoreLabels —
	// never a public setter, and never fabricated when identity is absent
	// (ADR 0204 decision 4). The aggregate STORES it and never interprets it: no
	// enforcement, no filtering, display + audit only.
	Owner *Principal
	// Authority is the derived authority payload stamped through BindAuthority
	// before the first runnable state. The private marker distinguishes a bound
	// empty capability set from a genuinely pre-feature legacy session.
	Authority Authority
	// Kind classifies the trusted producer and continuation posture. New creates
	// main sessions; delegated/scheduled producers use the validated constructors.
	Kind SessionKind
	// Relationship carries kind-specific durable lineage. It is empty for main
	// and legacy unknown sessions.
	Relationship SessionRelationship
	// CreatedAt is the creation timestamp.
	CreatedAt time.Time
	// contains filtered or unexported fields
}

type SessionID string

type SessionKind string

type SessionRelationship struct {
	ScheduleName           string        `json:"schedule_name,omitempty"`
	OriginSessionID        SessionID     `json:"origin_session_id,omitempty"`
	OriginIncarnation      IncarnationID `json:"origin_incarnation,omitempty"`
	ParentSessionID        SessionID     `json:"parent_session_id,omitempty"`
	ParentIncarnation      IncarnationID `json:"parent_incarnation,omitempty"`
	CallID                 ToolCallID    `json:"call_id,omitempty"`
	BranchIndex            *int          `json:"branch_index,omitempty"`
	TeamID                 string        `json:"team_id,omitempty"`
	MemberName             string        `json:"member_name,omitempty"`
	DebugTargetID          SessionID     `json:"debug_target_id,omitempty"`
	DebugTargetIncarnation IncarnationID `json:"debug_target_incarnation,omitempty"`
}

type State string

type SteerPayload struct {
	// Text is the committed steer text, byte-identical to the user message
	// recorded into history and replayed to the model (the recorded == streamed
	// == model-view invariant).
	Text string
	// Parts carries the committed non-text media in fragment order.
	Parts []Content
}

type StopReason string

type StreamProgress uint8

type SubagentPayload struct {
	// ParentCallID is the parent's Subagent tool-call id, used by clients to attribute
	// this event to the originating Subagent card. Set on all three kinds.
	ParentCallID string
	// ChildID is the child session id, distinguishing concurrent subagents. Set on
	// all three kinds.
	ChildID string
	// ChildIncarnation is internal durable correlation metadata. It is persisted in
	// the event log but deliberately omitted from client/model projections.
	ChildIncarnation IncarnationID
	// Goal is a short, plain-text label for the delegated task (the Subagent call's
	// description, or a truncation of its prompt). Set on EvSubagentStart only.
	Goal string
	// Background marks a detached-delivery child (`background: true` on the Subagent
	// call): the tool call returned an immediate started-result and the child keeps
	// working while the parent continues; its result is collected via
	// SubagentStatus. Set on EvSubagentStart only. NOT a fourth delegation family —
	// one boolean on subagent.* (the ChildActivity trip-wire stands).
	Background bool
	// RoutedCategory / RoutedModel are the OPT-IN semantic model router's classification
	// for this child (ADR 0031): the chosen CATEGORY label and the concrete MODEL id the
	// child was minted on. Set on EvSubagentStart ONLY when the router was wired AND
	// classified this delegation (both empty otherwise — no router, or a fail-soft miss
	// that inherited the default model). They are BARE METADATA — a category label and a
	// model id, never the task prompt or the classifier's reasoning — so they are
	// gauntlet-#7 safe (no child content, no model-influenced free text crosses). They
	// surface end-to-end: the session struct + a per-classification INFO (dispatch-path
	// `routeTask` closure) + a Build-once "router ACTIVE" fact + the proto/client wire
	// (`routed_category`/`routed_model` on the `Subagent` event payload, relayed through
	// the gRPC + HTTP relays and the mecatui client).
	RoutedCategory string
	RoutedModel    string
	// RoutingReason names WHY the router did NOT classify this delegation (EvSubagentStart
	// only): EMPTY on a routed hit (RoutedCategory/RoutedModel set), otherwise one of the
	// RoutingReason* gate constants (pinned-model / agent-def-pinned-model / resume / fork /
	// router-disabled / breaker-open / aborted) or a static miss code from the classifier
	// (the RouterMiss* values) or composition (e.g. category-selector-empty). Open callback
	// detail is reduced to a static/generic code before emission. It is BARE METADATA — a
	// bounded harness/composition reason code, never the task prompt
	// or the classifier's reasoning — so it is gauntlet-#7 safe (no child content, no
	// model-influenced free text crosses). Clamped at the emit site.
	RoutingReason string
	// Model is the concrete MODEL id the child ACTUALLY ran on (EvSubagentStart only),
	// set unconditionally — inherited default, agent-def pin, per-call `model` override,
	// or the opt-in router — independent of whether the router fired. It is BARE METADATA
	// — a model id, never child content — so it is gauntlet-#7 safe (no child content
	// crosses). When the router classified this delegation, Model == RoutedModel. It rides
	// the proto/client wire end-to-end (subagent.start: Subagent.model = field 13),
	// surfaced via the server mapper — see ADR 0035.
	Model string
	// ToolName is the name of a child tool that just ran. Set on EvSubagentTool
	// only. It is the tool NAME alone — never the child's tool args or result.
	ToolName string
	// IsError reports whether the child tool call failed. Set on EvSubagentTool
	// only.
	IsError bool
	// ToolCount is the running (EvSubagentTool) or final (EvSubagentEnd) number of
	// child tool calls STARTED. It is CUMULATIVE and stamped on EVERY projection, so
	// a client assigns it (never sums) with no InnerKind guard — it is always current,
	// never 0-after-positive. (Counted at the call, not the result, because a result
	// may never arrive on a cancel.)
	ToolCount int
	// Text is a BOUNDED preview of the child's message/result text — control-byte
	// scrubbed and rune-capped by clampPreview in engine/agent, never the raw,
	// unbounded body. Set on EvSubagentTool for the message.delta / result inner
	// kinds when a preview is available.
	Text string
	// Detail is a BOUNDED preview of a child tool call's args (tool.call) or a
	// tool result's body (tool.result) — control-byte scrubbed and rune-capped by
	// clampPreview in engine/agent, never the raw, unbounded args/result body. Set
	// on EvSubagentTool for the tool.call / tool.result inner kinds when a preview
	// is available.
	Detail string
	// InnerKind discriminates which inner child event kind the projection came from
	// (message.delta / tool.call / tool.result / result / turn.end) and which preview
	// fields it populates (Text/Detail). A turn.end projection carries NO Text/Detail;
	// it only advances Usage. A child's permission.ask is never projected.
	InnerKind EventType
	// Usage is the child run's cumulative provider-reported token accounting. Like
	// ToolCount it is CUMULATIVE and stamped on EVERY projection (zero until the
	// first turn.end), so a client assigns it with no InnerKind guard and a dropped
	// frame cannot drift the figure. It is provider truth only — the issue-#82
	// display-only estimate is never folded in.
	Usage Usage
	// Stop is the child run's terminal stop reason. Set on EvSubagentEnd only.
	Stop StopReason
	// Cause carries the child run's failure detail when Stop is StopError (empty
	// otherwise) — the mirror of ResultPayload.Error for the delegation projection.
	// Set on EvSubagentEnd ONLY.
	//
	// It is HARNESS/PROVIDER metadata — a transport or loop error string, or (for a
	// failure BEFORE the child run started, e.g. workspace isolation) the harness's own
	// error text — NOT child-authored model output, so it is gauntlet-#7 safe on the
	// same footing as Stop/Usage.
	//
	// It is LINE-ORIENTED by contract: every emit site normalises it through one helper
	// (whitespace collapsed to single spaces, then rune-clamped), because its consumers
	// are single-line surfaces — a fleet-roster row, an ACP status line, a log line — and
	// a provider error body routinely carries real newlines. A consumer renders it as-is
	// rather than re-deriving the collapse. (The MODEL-facing failure body keeps its
	// newlines; that is prose in a conversation, not a row.)
	Cause string
	// DurationMs is the child run's wall-clock duration in milliseconds
	// (best-effort). Set on EvSubagentEnd only.
	DurationMs int64
}

type TeamFindingSnapshot struct {
	// Member is the name of the member that recorded the finding.
	Member string
	// Body is a BOUNDED preview of the finding text (capped like every other
	// member-derived preview).
	Body string
}

type TeamMemberDisposition struct {
	// Name is the member name (matches a roster entry by name).
	Name string
	// Disposition is "done" / "stopped".
	Disposition string
	// Reason is "error" / "cancelled" / "budget"; empty when done.
	Reason string
	// ErrorRounds is how many of this member's rounds ended in a run-level error. It is
	// a plain COUNT of supervisor verdicts (no member content, no cap needed), and it is
	// what keeps the disposition HONEST now that a member's errored round is bounded-
	// retried rather than always terminal (issue #318): such a member finishes
	// Disposition "done" with no Reason, so the count is the only signal a client has
	// that the run was not clean.
	//
	// It is INDEPENDENT of Disposition/Reason: it counts errored rounds over the member's
	// whole LIFETIME, so it is 0 exactly when the member never had an errored round —
	// NOT when it ended cleanly. A member that failed a round, was recovered and retried,
	// and was then cancelled reports Reason "cancelled" with ErrorRounds 1. Render the
	// two together; do not derive either from the other.
	ErrorRounds int
}

type TeamMemberSpec struct {
	// Name is the member's unique handle.
	Name string
	// Role is the member's short role label (the model-supplied role string).
	Role string
	// Mutating reports whether the member runs in an isolated fork with
	// workspace-mutating tools (true) or shares the base read-only (false).
	Mutating bool
	// Lead marks the coordinating member.
	Lead bool
	// RoutedCategory / RoutedModel are the OPT-IN semantic model router's classification
	// for this member (ADR 0031 / ADR 0034): the chosen CATEGORY label and the concrete
	// MODEL id the member's engine was minted on. Set on the EvTeamStart roster entry ONLY
	// when the router was wired AND classified this member (both empty otherwise — no
	// router, a fail-soft miss that inherited the default member model, or a DEFINED member
	// whose agent def pinned its own model so the router never fired). Like the Subagent and
	// Parallel routed fields they are BARE METADATA — a category label and a model id, never
	// the member's role/prompt or the classifier's reasoning — so they are gauntlet-#7 safe
	// (no member content crosses). They ride the proto/client wire end-to-end (team.start
	// roster: TeamMemberSpec.routed_category = field 5 / routed_model = field 6), surfaced
	// via the server mapper — see ADR 0034.
	RoutedCategory string
	RoutedModel    string
	// RoutingReason names WHY the router did NOT classify this member (EvTeamStart roster
	// entry only): EMPTY on a routed hit (RoutedCategory/RoutedModel set), otherwise one of
	// the RoutingReason* gate constants (agent-def-pinned-model for a DEFINED member,
	// router-disabled when no router is wired) or a static miss code from the classifier
	// (the RouterMiss* values) or composition. Open callback detail is reduced before
	// emission. It is BARE METADATA — a bounded harness/composition reason code, never the
	// member's role/prompt or classifier reasoning — so it is gauntlet-#7 safe (no member
	// content crosses). Clamped at the emit site.
	RoutingReason string
	// Model is the concrete MODEL id the member's engine ACTUALLY runs on (EvTeamStart
	// roster entry only), set unconditionally — inherited default member model, agent-def
	// pin, or the opt-in router — independent of whether the router fired. It is BARE
	// METADATA — a model id, never member content — so it is gauntlet-#7 safe (no member
	// content crosses). When the router classified this member, Model == RoutedModel. It
	// rides the proto/client wire end-to-end (team.start roster: TeamMemberSpec.model =
	// field 7), surfaced via the server mapper — see ADR 0035.
	Model string
}

type TeamPayload struct {
	// ParentCallID is the parent's Team tool-call id, attributing every team.*
	// event to the originating Team card. Set on all three kinds.
	ParentCallID string
	// TeamID is the team id, distinguishing concurrent teams. Set on all kinds.
	TeamID string
	// Roster is the team's membership as the model formed it. Set on EvTeamStart
	// only. It carries only member metadata, never member content.
	Roster []TeamMemberSpec
	// Member is the name of the member whose activity this event projects. Set on
	// EvTeamMember only.
	Member string
	// MemberSessionID is the producing member's child SESSION id (MemberSessionID:
	// "team-<teamID>-<member>") — the uniform per-child cancel/inspect handle (the
	// same single-handle convention as SubagentPayload.ChildID), surfaced so a client
	// can address a member (CancelChild) WITHOUT deriving the id grammar. Set on
	// EvTeamMember only. It is an id, never member content.
	MemberSessionID string
	// MemberIncarnation is internal durable correlation metadata, never projected.
	MemberIncarnation IncarnationID
	// InnerKind is the member's underlying session event kind being projected
	// (e.g. "message.delta", "tool.call", "tool.result", "turn.end", "result").
	// Set on EvTeamMember only. permission.ask is never projected.
	InnerKind EventType
	// Text is the member's message/result text or a BOUNDED preview of it. Set on
	// EvTeamMember for message.delta / result inner kinds.
	Text string
	// ToolName is the name of a member tool that was called. Set on EvTeamMember
	// for tool.call / tool.result inner kinds.
	ToolName string
	// Detail is a BOUNDED preview of a member tool call's args (tool.call) or
	// result body (tool.result) — capped at maxTeamPreview runes. It is never the
	// raw, unbounded args/result body. Set on EvTeamMember for tool.* inner kinds.
	Detail string
	// IsError reports whether a member tool.result failed. Set on EvTeamMember for
	// the tool.result inner kind.
	IsError bool
	// Rounds is the number of scheduling rounds that ran work. Set on EvTeamEnd
	// only.
	Rounds int
	// Stop is the team run's terminal stop reason. Set on EvTeamEnd only.
	Stop StopReason
	// Usage is the member's per-event usage (EvTeamMember turn.end/result) or, on
	// EvTeamEnd, the TEAM TOTAL — the sum of every member's per-turn usage.
	Usage Usage
	// ContextUsed is the member's CURRENT context occupancy — the most recent
	// turn's input-token count (Usage.InputTokens of the turn just ended), i.e.
	// what the next turn would carry into the model, not a cumulative sum. Set on
	// EvTeamMember turn.end; 0 when unknown. It feeds the per-member context meter
	// in the ctrl+a agents overlay (the team analogue of the main context meter).
	ContextUsed int64
	// ContextWindow is the producing member engine's context window in tokens (the
	// meter's denominator). Set on EvTeamMember turn.end; 0 when unknown (no meter
	// is drawn in that case).
	ContextWindow int64
	// Tasks is a snapshot of the team's SHARED TASK LIST in creation order. It is
	// set on an EvTeamTasks event (emitted on change, de-duped, from the Team tool's
	// member-event sink) and on EvTeamEnd (the terminal snapshot, so the final task
	// state always lands). It feeds the ctrl+a agents task sub-view; it carries only
	// task metadata, never member content.
	Tasks []TeamTaskSnapshot
	// Findings is a snapshot of the team's SHARED FINDINGS LEDGER in append order. It
	// is set on an EvTeamFindings event (emitted on change, de-duped) and on EvTeamEnd
	// (the terminal snapshot). It feeds the ctrl+a agents findings view; each entry
	// carries the recording member's name and a BOUNDED body preview, never the raw
	// finding.
	Findings []TeamFindingSnapshot
	// Dispositions is a per-member TERMINAL disposition snapshot, set ONLY on EvTeamEnd
	// (parallel to the terminal Tasks/Findings snapshots). It lets a client render a
	// stopped member distinctly from a clean one without recomputing "done". Each entry
	// carries closed-enum supervisor verdicts only, never member content. Empty on
	// every other kind.
	Dispositions []TeamMemberDisposition
	// Cause carries the member run's per-round FAILURE DETAIL when that round's
	// EvResult.Stop is StopError (empty otherwise) — the mirror of
	// ResultPayload.Error for the team-member projection. Set on EvTeamMember with
	// InnerKind=EvResult ONLY, and ONLY when the round failed; empty on every other
	// inner kind and on EvTeamEnd's disposition snapshot.
	//
	// It is HARNESS/PROVIDER metadata — a transport or loop error string, or (for a
	// failure BEFORE the member run started) the harness's own error text — NOT
	// member-authored model output, so it is gauntlet-#7 safe on the same footing as
	// Stop/Usage.
	//
	// It is LINE-ORIENTED by contract: the ONE emit site (projectTeamEvent) normalises
	// it through subagentCausePayload (whitespace collapsed to single spaces, then
	// rune-clamped to maxSubagentCausePreview), because its consumers are single-line
	// surfaces — a mecatui roster/focus row, an ACP status line, a log line — and a
	// provider error body routinely carries real newlines. A consumer renders it
	// as-is rather than re-deriving the collapse. The terminal EvTeamEnd disposition
	// stays the closed-enum reason; Cause is per-round, so a retried member's failed
	// rounds each surface their own cause. Mirrors SubagentPayload.Cause.
	Cause string
}

type TeamTaskSnapshot struct {
	// ID is the stable task identifier.
	ID string
	// Description is a BOUNDED preview of the work to do (capped like every other
	// member-derived preview).
	Description string
	// State mirrors team.TaskState: "pending" / "in_progress" / "completed".
	State string
	// Assignee is the member name that claimed the task, or empty if unclaimed.
	Assignee string
	// Deps lists the task ids that must complete before this task is claimable.
	Deps []string
}

type TitleProvenance string

type ToolCall struct {
	// ID pairs this call with its ToolResult.
	ID ToolCallID `json:"ID"`
	// Name is the tool name as registered in the catalog.
	Name string `json:"Name"`
	// Args is the raw, tool-specific argument payload, validated against the
	// tool's JSON schema by the Tool itself.
	Args json.RawMessage `json:"Args"`
	// ItemID is the provider-assigned item-level unique identifier for this
	// function_call output item (e.g. the "id" field in the OpenAI Responses
	// API, distinct from ID which carries "call_id"). Carried opaquely — same
	// discipline as Message.Reasoning and Message.ProviderPhase — so the adapter
	// can round-trip it for store:false stateless multi-turn replay. Empty string
	// means "no item id" and the field is wire-omitted on replay. The STRUCTURE
	// is provider-neutral; the CONTENTS are provider-private — do NOT interpret
	// or validate this value in domain code.
	ItemID string `json:"item_id,omitempty"`
}

type ToolCallID string

type ToolResult struct {
	// CallID is the ID of the ToolCall this result answers.
	CallID ToolCallID
	// Content is the result body, already token-shaped/truncated by the tool.
	Content string
	// IsError reports whether the tool failed; an error result is still fed
	// back to the model so it can recover.
	IsError bool
	// Parts carries typed tool-result blocks (text/image/audio/resource). Empty
	// for the legacy string-only path; when non-empty, consumers prefer Parts
	// over Content. Distinct from Message.Parts (which is media-only for user
	// messages) — providers read ToolResult.Parts, not Message.Parts, for tool
	// results.
	Parts []Content `json:"Parts,omitempty"`
}

type Turn struct {
	// Index is the zero-based position of this turn in the session.
	Index int
	// Assistant is the assistant message produced by the model call.
	Assistant Message
	// Results holds the results of the tools the assistant requested.
	Results []ToolResult
	// Usage is the token accounting for this turn's model call.
	Usage Usage
}

type TurnEndPayload struct {
	// Usage is THIS turn's model-call usage (not the cumulative run total).
	Usage Usage
	// Estimated is true when Usage.InputTokens is a conversation-size ESTIMATE
	// rather than a provider-reported figure — the issue-#82 zero-usage fallback
	// fired because the turn produced no usage frame (a stalled/usage-less turn).
	// It is DISPLAY-ONLY: the estimate never feeds the cumulative run total or a
	// token budget (those stay on provider truth), only the context meter, which a
	// client may flag with a "~" hint. False for an ordinary provider-reported turn.
	Estimated bool
	// DurationMs is the elapsed milliseconds for the turn's model call; 0 when no
	// Clock is injected.
	DurationMs int64
	// TTFTMs is the time-to-first-token: the elapsed milliseconds from the start
	// of the model stream to the FIRST observable output (text, reasoning, a
	// reasoning replay item, or a tool call) of the turn. It is 0 when no Clock is
	// injected OR when the turn produced no observable output at all (a genuinely
	// empty turn) — a 0 here is "not measured", never a real zero, so telemetry
	// must guard against recording bogus zeros.
	TTFTMs int64
	// InterTokenMeanMs is the per-turn MEAN gap, in milliseconds, between
	// consecutive streaming content deltas (text or reasoning) within the turn —
	// the typical streaming smoothness. It feeds the mecatl.inter_token histogram.
	// It is 0 when fewer than two streaming content deltas were observed (no gap
	// exists) or no Clock is injected. A tool call or reasoning replay blob is NOT a
	// streaming delta and never contributes a gap.
	InterTokenMeanMs int64
	// InterTokenMaxMs is the per-turn WORST (largest) single gap, in milliseconds,
	// between consecutive streaming content deltas within the turn — the jitter
	// spike users feel. It feeds the mecatl.inter_token.max histogram. It is 0 under
	// the same <2-delta / no-Clock conditions as InterTokenMeanMs.
	InterTokenMaxMs int64
}

type Usage struct {
	// InputTokens is the number of prompt tokens billed for this call,
	// including any tokens served from cache.
	InputTokens int
	// OutputTokens is the number of completion tokens generated.
	OutputTokens int
	// CacheReadTokens is the number of input tokens served from the prompt
	// cache (a subset of InputTokens).
	CacheReadTokens int
	// CacheWriteTokens is the number of input tokens written into the prompt
	// cache on this call.
	CacheWriteTokens int
	// ReasoningTokens is the number of output tokens spent on internal
	// reasoning (a subset of OutputTokens — providers bill reasoning as part of
	// the inclusive output total; this is the breakdown, not an addend).
	ReasoningTokens int
}

type UserPromptPayload struct {
	// Text is the flattened user-message text (the prompt body, or a harness-authored
	// continuation/notice).
	Text string
	// Parts carries any non-text media (image/audio) that rode alongside the text on
	// the user message; nil for a text-only prompt. It mirrors Message.Parts so the
	// reconstructed user Message is faithful.
	Parts []Content
}