feat(task): expose subagent token consumption to primary agent

[arsham]

Primary agent now receives token consumption data from subagents via task_metadata, enabling smarter delegation decisions based on remaining context capacity.

The task_metadata now includes:

• Token breakdown (input, output, reasoning, cache read/write)
• Context limit (model's max context window)
• Context percentage (how much capacity is used)
• Cumulative cost

Example

<task_metadata>
session_id: ses_557a4d402ffe73PZcaOCWS06V8
tokens_input: 11
tokens_output: 285
tokens_reasoning: 0
tokens_cache_read: 17234
tokens_cache_write: 2622
cost: 0
context_limit: 200000
context_percentage: 10
</task_metadata>

Why

Previously, task_metadata only returned session_id. The primary had no visibility into how much context a subagent had consumed, making it impossible to know when to spawn a fresh session vs continue with an existing one.

Primary can now check context_percentage and decide to continue with the same subagent or start fresh when context is running low.

[arsham]

Side note - noticed something in processor.ts

While working on this, I came across something in session/processor.ts (around line 249-250) that feels a bit odd:

case "finish-step":
  input.assistantMessage.cost += usage.cost      // accumulates
  input.assistantMessage.tokens = usage.tokens   // replaces

Cost uses += (accumulates across steps) but tokens uses = (overwrites with latest step).

Is this intentional? My guess is tokens represents "current context window state" while cost is "total spent" - but wanted to flag it in case this was an oversight. If a single message has multiple finish-step events, only the last step's tokens would be retained.

Not blocking this PR on it, just curious if anyone knows the reasoning here.

[rekram1-node]

yes that’s intentional

[rekram1-node]

for your token consumption stuff, is this a problem you were running into? Also note that child sessions work like any other so it automatically prunes tool calls and automatically compacts if needed so it is rare thatd itd run out of context

[arsham]

Not a problem. This is an improvement over the session_id additions. This is the scenario I am utilising this for:

The primary agent delegates to some agents. My subagents return the confidence level of what they are doing, but the only measurement they don't have is the context consumption.

On the next turn, the primary looks at the confidence level and other metrics including the session_id, then makes a decision to reuse the same agent. This helps by reducing duplicate work and also if we get lucky and before cache invalidation, we get to reuse the cached prompt from the API side.

[github-actions]

Closing this pull request because it has had no updates for more than 60 days. If you plan to continue working on it, feel free to reopen or open a new PR.