SubagentHandle class final

A retained subagent handle: the parent (and the user) can query status, send follow-up messages, and observe the child's transcript at any time.

Constructors

SubagentHandle({required String id, required String name, required String agentType, required String sessionId, required String createdAt, String task = '', String context = ''})
SubagentHandle.fromJson(Map<String, dynamic> json)
Reconstructs a handle from a persisted JSON map.
factory

Properties

agentType → String
The agent type (task/explore/review/discovered type).
final
compactions ↔ int
Completed proactive compactions (issue #439).
getter/setter pair
context → String
The batch context the child was spawned with (issue #222 review): the resume path re-renders it into the child's system prompt — the JSONL transcript does not carry the system prompt, so the handle persists it. Empty for children spawned without a batch context.
final
contextPressureText → String?
~NN% context pressure for status lines, or null when unknown.
no setter
createdAt → String
Creation timestamp (ISO 8601).
final
error ↔ String?
Error message when status is SubagentStatus.failed.
getter/setter pair
estTokens ↔ int?
Last-known context pressure of the child (issue #439): the executor stamps the estimated request tokens and the effective window at every turn boundary, so task_status can surface the wall before it is hit. Null until the child's first turn.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
id → String
Unique id (== agent:// id == the id allocated by TaskExecutor).
final
isTerminal → bool
True when the child has finished (success or failure).
no setter
isWaitingForInput → bool
True when the child is waiting for input (e.g. an ask tool answer).
no setter
lastActivity ↔ String
Last activity timestamp (ISO 8601), updated on each spawn/message.
getter/setter pair
lastCompactionAt ↔ String?
When the most recent compaction ran (ISO 8601), or null.
getter/setter pair
lastCompactionFreed ↔ int
Tokens freed by the most recent compaction (see compactions).
getter/setter pair
lastCompactionText → String?
One-line last-compaction summary, or null when never compacted.
no setter
lastReply ↔ String?
The child's explicit reply text (Phase 3b), if it sent one before completing. Null means the child finished without an explicit reply — the parent gets a completed_without_reply notice with the final-text preview instead (prime-agent semantics).
getter/setter pair
liveRequests ↔ int
In-flight provider request count of the current run (see liveTokens).
getter/setter pair
liveTokens ↔ int
In-flight provider usage of the CURRENT run (issue #383 heartbeat): the executor touches it on every completed provider response so the parent's digest shows live request/token counts. The lifetime totals above only land at completion; a running child adds these on top.
getter/setter pair
modelId ↔ String?
The model id used for this child.
getter/setter pair
name → String
Display name (from the agent type or item description).
final
pendingMessages → List<SubagentMessage>
Inter-agent messages addressed to this child and not yet consumed (Phase 3b pending queue). Bounded by the manager's size guard.
final
requests ↔ int
Number of model requests made.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sessionId ↔ String
The child session id (JSONL path in the parent's session repo). Placeholder <parentId>/<id> until the executor attaches the real session at child completion (SubagentManager.attachSession).
getter/setter pair
status ↔ SubagentStatus
Current lifecycle state.
getter/setter pair
statusLine → String
no setter
supersedes ↔ String?
The id of the previous same-named handle this child supersedes (issue #222): an explicit fresh respawn after a failure links back to the old child so UIs can collapse the chain into one logical entry. Null for the first generation (the resume path — task_resume — continues the same handle and never sets this).
getter/setter pair
task → String
The initial task prompt.
final
tokens ↔ int
Token usage (input, output, total).
getter/setter pair
windowTokens ↔ int?
The window estTokens was measured against (see estTokens).
getter/setter pair

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toJson() → Map<String, dynamic>
Converts to a JSON map for persistence in the parent session.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited