Sub-Agent Context
Confining generate filters to the top-level agent
Overview
The filter option accepted by every agent in this package runs on every bridged model request the agent makes — not just the top-level agent’s own turns. When an agent delegates work to a sub-agent (a Claude Code Task agent, a Codex spawned agent, an OpenCode Task-tool agent, …), the sub-agent’s model requests flow through the same bridge and the same filter. The same is true of internal machinery calls an agent makes on its own behalf (context compaction, approval review, title generation). A filter that injects steering, counts turns, or ends an episode early is almost always written with the top-level agent’s own thread in mind, so it should actively confine itself to that thread rather than firing for delegated or internal traffic too.
Every agent in inspect_swe classifies each bridged request into inspect_ai’s ambient AgentBridgeContext before your filter runs, so you can gate on it directly.
For claude_code and codex_cli, the transcript places each generation in the span of the agent the classification names. Requests with no single named agent go in the top-level agent’s span. Classification reads the request as it reaches the bridge. If your filter returns a rewritten GenerateInput or edits the messages in place, the generation still lands where the request was classified; it is not re-attributed from the changed messages. Agents that the generation spawns are tracked as children of the agent the classification named. This also holds when your filter runs nested bridged requests of its own.
If your filter calls model.generate itself, that generation is placed the same way, including after a nested bridged request the filter awaited first. Agents spawned in its output are tracked only if the filter returns that output. A ModelEventSink you installed around the agent (use_model_event_sink) still receives the filter’s generations, already placed, and records them as it chooses. One limit remains: when your filter returns its own output, inspect_ai records any bridged host-tool events for that output in the current span, not the sub-agent’s.
Confining a Filter to the Root Agent
Use is_root_agent() at the top of your filter to skip anything that isn’t the top-level agent’s own thread:
from inspect_swe import is_root_agent
async def my_filter(model, messages, tools, tool_choice, config):
if not is_root_agent():
return None # never steer a sub-agent or utility thread
...is_root_agent() is a permissive gate: it returns False only for requests attributed to a "subagent" or "utility" thread, and True for everything else (including "root", "unknown", and code running outside a bridged request at all) — so steering logic keeps working on agents or requests that can’t be attributed, rather than silently disabling itself.
Agent Context
current_agent_bridge_context() reads the classification attached to the request currently in flight. Its kind is one of:
| Kind | Meaning |
|---|---|
"root" |
The top-level agent’s own thread — the request you’re almost always trying to steer. |
"subagent" |
A delegated agent with its own goal and conversation thread (e.g. a Claude Code Task agent or a Codex spawned agent). |
"utility" |
Machinery calls serving the main agent’s own plumbing — compaction, approval review, title generation, or another internal helper model — with no delegated goal or thread of its own. |
"unknown" |
The classifier couldn’t attribute this request to any of the above. |
A "subagent" context can also say which sub-agent made the request: subagent_id is stable across one sub-agent’s requests and distinct between sub-agents (use it to keep per-sub-agent state such as turn counts), and subagent_type is the CLI’s name for the kind of sub-agent (e.g. "Explore"). Either is None when the agent can’t tell, which, like "unknown", is an honest answer; both are always None for other kinds. The table below says what each agent fills in.
AgentBridgeContext and current_agent_bridge_context are re-exported from inspect_swe for convenience, along with is_root_agent and the narrower is_sub_agent (True only for "subagent" — note it’s False for "utility", so prefer is_root_agent() for steering gates).
Per-Agent Guarantees
How each agent tells "subagent" and "utility" traffic apart from "root" differs by backend, reflecting what each CLI actually exposes on the wire:
| Agent | Sub-agent detection | Utility detection | Notes | Sub-agent id / type |
|---|---|---|---|---|
claude_code |
Structural: the requested model carries the synthetic subagent slug (CLAUDE_CODE_SUBAGENT_MODEL), including custom agents defined via front-matter model:. A request with an unrecognized slug is also "subagent" when Claude Code’s billing header marks it cc_is_subagent=true. Failing both, a request that carries a running Task’s prompt in its opening user messages (e.g. after a <system-reminder>) is "subagent". Once Claude Code has sent the flag, a request without it (e.g. the main thread, or the auto-mode permission classifier) is not matched by prompt and stays out of sub-agent spans, unless it carries the subagent slug. |
Only when haiku_model is configured distinct from the presented model — otherwise the small-fast slug is indistinguishable from main-thread traffic. |
A drift canary logs a warning (once) if Claude Code ever stops honoring the subagent slug this classification depends on. A second one warns (once) if a subagent-slug request’s billing header stops carrying cc_is_subagent=true. |
subagent_type: the Task call’s subagent_type. subagent_id: the Task call’s tool_use id, when the request’s opening user messages (everything before its first reply) carry exactly one running Task’s prompt. A foreground Task runs until its result returns. A Task Claude Code runs in the background (Claude Code 2.1.311 launches Agent calls this way) runs until Claude Code reports it finished, not when the launch result returns. Parallel Tasks with prompts that can’t be told apart (identical, or one containing the other) get None for both, still "subagent". So does a request that also carries the prompt of a Task that has already finished (it may have been resumed or continued). Such requests are placed in the top-level agent’s transcript span, not in a span of one of the matching Tasks. Tasks in an output your filter returns itself are tracked too. |
codex_cli |
Structural: tracks spawned sub-agent threads via spawn_agent tool calls (including those in an output your filter returns itself) and agent_message recipient routing. Under Multi-Agent V2 any inbound agent_message addressed to a path other than /root is a sub-agent, including a child resumed by followup_task after its final answer. A resumed child continues in a new transcript span with the same name, and the agents it spawns nest under that span. The span closes on the child’s next final answer. Codex’s final answers carry no id, so after the receiving agent compacts its history (dropping the earlier answer), an answer with the same text as the earlier one is recognized as new only by position: it follows Codex’s compaction summary in the first history after the agent’s observed compaction request, or a summary unlike the one before. Two limits follow. If Codex’s summary text isn’t recognized, such a repeated answer leaves the span open (a later followup then continues in it). If a compaction doesn’t replace the history (e.g. it fails) and the next request has no assistant turn after the earlier summary, an earlier answer there closes the span early. |
The guardian (auto_review) model slug, plus Codex’s own local-compaction request marker when it starts the request’s latest user message. The same text earlier in a conversation doesn’t make later requests utility. |
An unattributed call while sub-agents are open resolves to "unknown" rather than guessing “root”. Under Multi-Agent V1 that includes the delegating thread itself when its own prompt contains the delegated text: a request carrying the spawn call is never attributed to the spawned agent. |
subagent_id: under Multi-Agent V2 the agent’s path (e.g. /root/worker), the same on every request including after followup_task; under V1 the spawn_agent call id. subagent_type: the spawn’s agent_type argument, None when the spawn omits it. Under V2 a spawn is tied to a path only by its spawn result, or by the exact path Codex gives it (the spawning request’s own path, i.e. its single agent_message recipient, plus task_name). The transcript span is never used, so a same-named agent under another parent, or a resumed finished agent, keeps its own type. A request with no agent_message is taken as root’s (only root’s early requests lack one), so root’s spawns bind from their child’s first call. Codex’s local compaction also drops agent_messages, so a compacted sub-agent’s spawn gets a root-level path it doesn’t own; because a path whose agent has finished is never re-bound by expected path, such a spawn binds only from its spawn result, and its subagent_type and transcript nesting appear once that arrives (its subagent_id, its own path, is there from its first request). Under V1 both are None when a prompt matches more than one open spawn (that request is "unknown" anyway) or also matches a finished spawn’s prompt. A finished V1 agent resumed with send_input can’t be identified and classifies "unknown" as long as its request still carries its spawn prompt, as a whole user message or (for prompts of 16 characters or more) inside one. That holds even while a later spawn with the same prompt is running, and the request stays in the top-level agent’s transcript span. The same rule makes root "unknown" if its history has lost the spawn call (e.g. after compaction) while still carrying that prompt. V2 paths are distinct between live agents; whether Codex reuses a finished agent’s path for a new spawn with the same task name isn’t verified, and would give both the same id. |
opencode |
Structural, but only for the three built-in (general/explore/scout) sub-agents — routed to a distinct sentinel model via injected per-agent config — and only when opencode_model is an anthropic/ model, the one provider whose sentinel id is live-verified against OpenCode’s model catalog (a catalog-rejected sentinel hard-fails the sub-agent’s Task call, so unverified providers skip injection and log once: requests under the primary slug, including the built-in sub-agents’, classify "root", and any other slug "unknown"). Custom Task-tool agents aren’t covered: one left at the default model inherits the primary slug and classifies "root" (it would be steered — the harmful direction); one configured with its own model: gets a slug in neither map and classifies "unknown". |
Best-effort only: small_model is set to a small-model sentinel, but OpenCode (1.18.15) was observed to ignore it for title generation, so utility traffic classifies "root" in practice. Per-agent title/summary/compaction overrides are deliberately not injected (unverified, and on an install where those names aren’t reserved they would create spawnable agents that misclassify as "utility"). |
Sentinel selection avoids colliding with the caller’s own primary model slug; a collision (e.g. opencode_model="anthropic/claude-haiku-4-5-20251001") omits the sub-agent override so that traffic degrades to "root" rather than falling back to an unverified id. Built-in sub-agents are served by the same model as the primary slug: a model_aliases entry for the bare primary id (e.g. "claude-sonnet-4-6") also applies to the sub-agent sentinel unless you alias that id yourself. |
Both None. The three built-in sub-agents share one sentinel model, so the slug can’t tell them apart; OpenCode sends per-session headers, but bridge requests don’t expose headers yet (#189). |
gemini_cli |
None — gemini-cli’s own subagent feature has no reserved model slug, so sub-agent traffic isn’t distinguishable from root by slug alone. | Known internal utility calls (loop detection, web search/fetch, edit correction, next-speaker checks, some compaction variants) resolve to a small, known set of concrete model slugs. | Two compaction aliases resolve to the same slug as the presented model, so those specific calls are honestly under-attributed as "root", not misclassified. Likewise when gemini_model is a primary alias (auto, pro, flash, …), or a concrete id gemini-cli promotes before the wire (e.g. gemini-3.1-flash-lite → gemini-3.5-flash-lite, gemini-3.5-flash → gemini-3.8-flash): every slug it can resolve to is treated as root, so utility calls landing on the same slug are under-attributed rather than the root thread being mislabeled "utility". |
Both None (no sub-agent detection). |
kimi_code |
None — Kimi Code has no delegation feature. | Its own auto-compaction summarizer is matched by a fixed marker string carried in the request. | Everything else classifies "root". |
Both None (no delegation). |
mini_swe_agent / antigravity |
None — neither agent supports delegation. | None. | Every bridged request classifies "root". |
Both None (no delegation). |
ACP variants (interactive_claude_code, interactive_codex_cli, interactive_gemini_cli) |
Slug-only, via the same static root/subagent/utility slug maps their native counterparts use for their structural signal. interactive_codex_cli also recognizes a Multi-Agent V2 sub-agent from an inbound agent_message addressed to a path other than /root. |
Slug-only, same maps. | No JSONL/event-stream consumer is available in the ACP path to drive the richer, stateful attribution the native agents layer on top — so ACP classification is exactly as good as the underlying agent’s slug signal alone (e.g. gemini_cli’s “no subagent slug” gap, codex_cli’s guardian slug). In particular interactive_codex_cli detects sub-agents only under Multi-Agent V2, where a sub-agent’s request carries an inbound agent_message addressed to its own path; under V1, Codex’s spawn_agent takes no per-agent model, so its sub-agents request the primary slug and classify "root" (they would be steered). interactive_claude_code presents sub-agents under a synthetic <presented>-subagent slug (aliased to the primary model when subagent_model is unset, exactly as the native claude_code does), so Task sub-agent traffic is attributable out of the box; utility detection still requires a haiku_model distinct from the presented/opus/sonnet models, since an unset one shares the primary slug. |
interactive_codex_cli under V2: subagent_id is the agent’s path, as for codex_cli. Otherwise both None (slug-only classification can’t tell sub-agents apart). |
A Note on “unknown”
"unknown" is a first-class, honest answer, not a bug: some classifiers fall back to it deliberately rather than guess at an attribution they can’t support — an unattributed codex_cli call while sub-agents are open, or a claude_code call whose requested slug matches no known role while sub-agents are pending (it could be the main thread or an unattributed sub-agent call; the classifier can’t tell, so it says so rather than guessing "root"). is_root_agent() treats "unknown" — and having no context at all — as root, precisely so that turn-counting and early-stop logic keeps working on agents (or agent versions) that a classifier can’t fully attribute, rather than silently going dark. Consumers that need a positive confirmation that a request belongs to the top-level agent, rather than merely “not known to belong to a sub-agent or utility thread”, should check current_agent_bridge_context() for kind == "root" explicitly instead of relying on is_root_agent().
See Also
See the Inspect AI Agent Context documentation for the underlying AgentBridgeContext API, how bridge implementers set it, and how it composes with in-process (non-inspect_swe) scaffolds.