subagents

type FileChange struct {
	Path string `json:"path"`
	Op   string `json:"op"` // "created" | "modified" | "deleted"
}

type ProgressEntry struct {
	OffsetMS int64  `json:"offset_ms"`
	Phase    string `json:"phase"`
	Message  string `json:"message"`
}

type SharedState struct {
	EventBus      *events.EventBus
	TodoManager   *tools.TodoManager
	ConfigManager *configuration.Manager
	WorkspaceRoot string
}

type SubagentError struct {
	Status SubagentStatus
	Reason string
}

type SubagentMetrics struct {
	Active            int64 // Currently executing subagents
	Queued            int64 // Waiting for semaphore slot
	Completed         int64 // Successfully completed
	Failed            int64 // Completed with error
	Cancelled         int64 // Cancelled (parent ctx or budget)
	TotalQueuedWaitMS int64 // Cumulative milliseconds spent waiting in queue
}

type SubagentOptions struct {
	Persona                string        // "coder", "tester", "debugger", etc.
	Model                  string        // optional model override
	Provider               string        // optional provider override
	SystemPrompt           string        // optional system prompt override
	MaxTokens              int           // token budget (0 = unlimited)
	Timeout                time.Duration // execution timeout; <=0 defaults to 30 minutes, 1 hour for the orchestrator persona (see runTask)
	WorkingDir             string        // optional: override workspace root (must be within $HOME)
	MaxConcurrentSubagents int           // max parallel subagents (0 = unlimited, default unlimited)
	FleetTokenBudget       int           // shared token budget across all parallel subagents (0 = unlimited)
	// Role is the role the subagent's usage is attributed to
	// (the role its model was resolved through; a configuration.Role*
	// constant). Set by the spawn handler from the same resolution that
	// picked the provider/model; empty → createSubagent attributes the
	// subagent to the coder role (the default subagent resolution).
	Role string
	// Quiet suppresses streaming the subagent's output to the terminal. Used
	// for background runs, whose output would otherwise interleave with the
	// primary agent's. Activity events are still published.
	Quiet bool
}

type SubagentProgressEntry struct {
	OffsetMS int64  `json:"offset_ms"` // ms since subagent started
	Phase    string `json:"phase"`     // "spawn" | "output" | "complete"
	Message  string `json:"message"`
}

type SubagentResult struct {
	ID         string
	Output     string
	Error      error
	TokensUsed int
	Cost       float64
	// Role is the role the subagent's model was resolved
	// through. The parent rolls the subagent's usage up under this role so
	// its spend is attributed to the purpose it served (empty → the coder
	// fallback, matching subagentRole's default resolution).
	Role string
	// PromptTokens / CompletionTokens are the subagent's prompt/completion
	// token split. Carried so the parent's rollup attributes the subagent's
	// real token counts to its role instead of a zero-split aggregate.
	PromptTokens     int
	CompletionTokens int
	ToolCalls        int
	// Iterations is the assistant-turn count consumed by this subagent
	// run. Surfaced to the primary via SubagentRunMetrics.Iterations so
	// the model has visibility into how many LLM rounds a delegated task
	// burned.
	Iterations     int
	Elapsed        time.Duration
	Cancelled      bool
	BudgetExceeded bool // true if task was skipped because fleet budget was already exceeded before starting
	Truncated      bool // true if subagent was cut short due to fleet budget exceeded mid-run
	// OutputComplete signals whether the subagent produced a substantive
	// final response. false when the output is empty or suspiciously brief
	// (under 50 trimmed chars) despite a clean exit — the orchestrator can
	// use this to decide whether to retry, escalate, or accept. This is
	// distinct from Error/Cancelled/BudgetExceeded (all of which also set
	// it false): OutputComplete focuses specifically on "did the subagent
	// actually say something useful?"
	OutputComplete bool
	// FileChanges is the manifest of writes/edits this subagent performed,
	// captured via its own ChangeTracker. nil when tracking wasn't
	// initialized for this run.
	FileChanges []changes.TrackedFileChange
	// ProgressLog is a per-run timeline of notable subagent events
	// (spawn, output, complete). Surfaced to the primary's LLM via the
	// SubagentReturn envelope so the model can reason about *what* the
	// subagent did, not just the final assistant message. Capped to
	// ProgressLogCap entries.
	ProgressLog []SubagentProgressEntry
}

type SubagentReturn struct {
	// Output is the subagent's final assistant message (was: "stdout").
	Output string `json:"stdout"`
	// Stderr carries the subagent's terminal error message if any.
	Stderr string `json:"stderr"`
	// ExitCode is "0" on success, "1" otherwise. Kept as string for
	// shape-compat with the legacy resultMap.
	ExitCode string `json:"exit_code"`
	// Completed is "true" on natural completion, "false" if cancelled.
	Completed string `json:"completed"`
	// TimedOut is "true" if the run hit its timeout.
	TimedOut string `json:"timed_out"`
	// BudgetExceeded is "true" if the run hit its token budget.
	BudgetExceeded string `json:"budget_exceeded"`
	// ElapsedSeconds is the wall-clock duration, formatted "%.1f".
	ElapsedSeconds string `json:"elapsed_seconds"`
	// TokensUsed is the rolled-up token count (string for shape-compat).
	TokensUsed string `json:"tokens_used"`
	// Cost is the rolled-up dollar cost (string for shape-compat).
	Cost string `json:"cost"`
	// ToolCallCount is the number of tool calls the subagent made.
	ToolCallCount string `json:"tool_calls"`
	// Summary is JSON-stringified human-readable highlights (file ops,
	// build/test status, errors). Kept for shape-compat.
	Summary string `json:"summary,omitempty"`
	// ContextUsed is "true" / "false" reflecting whether the subagent
	// received the parent's context bundle.
	ContextUsed string `json:"context_used,omitempty"`
	// FilesUsed is the parent-provided files-of-interest list.
	FilesUsed string `json:"files_used,omitempty"`
	// WorkingDir is the directory the subagent executed under.
	WorkingDir string `json:"working_dir,omitempty"`

	// Status is the terminal state. Always populated, even on success.
	Status SubagentStatus `json:"status"`
	// ErrorReason carries free-form context when Status != completed.
	ErrorReason string `json:"error_reason,omitempty"`
	// FilesModified is the change-tracker-sourced manifest. nil when
	// change tracking is disabled (caller treats nil as "not reported").
	FilesModified []FileChange `json:"files_modified,omitempty"`
	// Metrics is the structured token/cost rollup. Mirror of the
	// TokensUsed/Cost/ToolCallCount string fields above for callers
	// that prefer typed access.
	Metrics SubagentRunMetrics `json:"metrics"`
	// ProgressLog is a capped timeline of subagent activity events
	// (spawn / output / complete) so the primary's LLM can reason about
	// what the subagent actually did, not just its final assistant
	// message. nil when no events were captured.
	ProgressLog []ProgressEntry `json:"progress_log,omitempty"`
}

type SubagentRunMetrics struct {
	TokensUsed int     `json:"tokens_used"`
	Cost       float64 `json:"cost"`
	ToolCalls  int     `json:"tool_calls"`
	Iterations int     `json:"iterations"`
}

type SubagentStatus string

type SubagentTask struct {
	ID         string
	Prompt     string
	Model      string
	Provider   string
	Persona    string
	WorkingDir string // optional: override workspace root
	// SystemPrompt is the resolved persona system prompt; empty falls back to
	// SubagentOptions.SystemPrompt.
	SystemPrompt string
	// Role is the role this task's subagent usage is
	// attributed to (the role its model was resolved through). Empty → the
	// coder role (createSubagent's fallback). Set by the caller that
	// resolved the model (e.g. the reviewer path sets "reviewer").
	Role string
}