Subagent Context Lifecycle

How Comis prepares, runs, and captures results from sub-agent sessions

When a parent agent spawns a sub-agent, Comis does more than just start a new conversation. It prepares a structured context packet with everything the sub-agent needs, enforces depth and concurrency limits, manages the sub-agent’s execution, condenses the result so it fits back into the parent’s context window, and formats it for clarity. This lifecycle runs automatically whenever an agent calls sessions_spawn.

How it works

The subagent context lifecycle is a pipeline that begins when the parent agent calls sessions_spawn and ends when the condensed result is injected back into the parent’s conversation.

Each stage has its own configuration options and graceful fallback behavior. If any stage encounters an error, the pipeline degrades safely rather than crashing — the parent always receives a result, even if it is a structured error message.

Worked example: parent spawns a research subagent

Say a primary agent named Atlas is asked to compile a brief on quantum computing. Atlas decides it needs background research before writing, so it spawns a sub-agent.

The parent invokes the sessions_spawn tool:

{
  "tool": "sessions_spawn",
  "agent_id": "researcher",
  "task": "Search the web and summarize the three biggest quantum-computing breakthroughs of the last 12 months. Return a Markdown bullet list with sources.",
  "objective": "Provide background facts for a 500-word brief.",
  "artifact_refs": [],
  "include_parent_history": "none"
}

Comis builds a spawn packet (next section), runs the sub-agent in its own session, and returns a condensed result like this:

[Subagent Result: research-quantum-2026-04]
Status: Completed
Condensation: Level 1 (passthrough)

- Researchers at Google demonstrated... (source: nature.com/...)
- IBM unveiled the Heron R2 processor... (source: research.ibm.com/...)
- A team at Caltech reported... (source: caltech.edu/...)

---
Runtime: 18.4s | Steps: 4 | Tokens: 6200 | Cost: $0.0186
Condensation: Level 1 | Original: 6200 tokens | Ratio: 1.00
Full result: ~/.comis/subagent-results/{session}/{runId}.json
Session: subagent:researcher:abc123

Atlas then reads the bullet list back into its own context and writes the brief. The full unredacted research output is on disk if Atlas needs to look back at sources later.

The key benefit: Atlas’s main session never carries the raw web search transcript. It only carries the curated three-bullet summary, which keeps the parent’s context budget under control.

Spawn packets

A spawn packet is the structured context bundle passed to a sub-agent. When sessions_spawn is called, Comis assembles a packet containing everything the sub-agent needs to understand its task, constraints, and environment.

Field	Description
task	The task description from the parent’s sessions_spawn call
artifactRefs	File paths the sub-agent should reference (from artifactRefs parameter)
domainKnowledge	Domain knowledge extracted from the parent’s system prompt
toolGroups	Tool profile groups the sub-agent is allowed to use
objective	An objective statement that survives context compaction
parentSummary	A condensed summary of the parent conversation (when includeParentHistory is "summary")
workspaceDir	The workspace directory inherited from the parent agent
depth	The current spawn depth (0 for top-level agents)
maxDepth	The maximum allowed depth from configuration
graphSharedDir	Path to the shared pipeline folder (only present for graph/pipeline nodes)

The spawn packet is injected into the sub-agent’s context as structured sections — domain knowledge, artifact references, and the objective each get their own clearly labeled section so the sub-agent can distinguish between its task, its reference material, and its constraints.

When a sub-agent is spawned as part of an execution graph, the spawn packet also includes the path to a shared pipeline folder. This directory is created per-graph and gives all nodes read-write access for exchanging files and artifacts. See Pipelines: Shared Data Folder for the full lifecycle.

The objective field is special: it survives context compaction through objective reinforcement. Even if the sub-agent’s conversation grows long enough to trigger compaction, the objective is re-injected so the sub-agent never loses sight of what it was asked to do.

Spawn limits

Two limits prevent runaway sub-agent recursion and resource exhaustion:

maxSpawnDepth (default: 3) — Controls how deep the spawn chain can go. A depth of 3 means parent, child, and grandchild. If a sub-agent at the maximum depth tries to spawn another sub-agent, it receives a structured error explaining the limit — no crash, no silent failure.

maxChildrenPerAgent (default: 5) — Controls how many active children a single parent can have at once. If a parent already has 5 active sub-agents and tries to spawn a sixth, the spawn is rejected with a structured error.

Execution graph (pipeline) nodes bypass the per-agent children limit but still respect depth limits. This allows complex pipeline orchestrations while preventing unbounded recursion.

Result condensation

When a sub-agent finishes, its result goes through a three-level condensation pipeline. The goal is to give the parent agent a useful summary without overwhelming its context window.

Level	Name	When applied	What happens
1	Passthrough	Result under maxResultTokens threshold	Wrapped in a result envelope without transformation
2	LLM Condensation	Result over threshold, model available	LLM summarizes into structured JSON with conclusions, file paths, actionable items, errors, key data, and a summary
3	Head+Tail Truncation	LLM fails or no model available	60% head / 40% tail split with an omission marker in the middle

Level 1 is the most common path — most sub-agent results are concise enough to pass through unchanged. Level 2 produces the highest quality condensation by using an LLM to extract the most important information into a structured format. Level 3 is a last-resort fallback that ensures the parent always receives something, even when LLM condensation is unavailable.

Regardless of condensation level, the full result is always written to disk at ~/.comis/subagent-results/{sessionKey}/{runId}.json. Results are retained for 24 hours by default (configurable via resultRetentionMs), after which they are automatically swept.

Narrative casting

After condensation, the result is formatted with a tagged prefix and metadata footer so the parent agent can clearly distinguish sub-agent output from its own conversation. This prevents role confusion when the parent has multiple active sub-agents.

Here is an example of a narrative-cast result:

[Subagent Result: research-task]
Status: Completed
Condensation: Level 2 (LLM summary)

Summary: The research task identified three candidate libraries...

Conclusions:
- Library A has the best performance profile
- Library B has the most active community

File Paths:
- /workspace/research/comparison.md

---
Runtime: 12.3s | Steps: 5 | Tokens: 4500 | Cost: $0.0135
Condensation: Level 2 | Original: 15000 tokens | Ratio: 0.30
Full result: ~/.comis/subagent-results/{session}/{runId}.json
Session: {sessionKey}

The [Subagent Result: {label}] tag at the top makes it easy for the parent agent to reference specific sub-agent outputs when coordinating multiple concurrent tasks. The metadata footer provides observability into cost, runtime, and condensation effectiveness.

Objective reinforcement

When a sub-agent’s conversation grows long enough to trigger the context engine’s compaction step (see Compaction), there is a risk that the sub-agent loses track of its original objective. Objective reinforcement prevents this.

After compaction produces a summary of the older messages, a [Objective Reinforcement] message is injected immediately after the compaction summary. This message contains the sub-agent’s original objective from its spawn packet, ensuring the sub-agent re-reads what it was asked to do before continuing.

This is enabled by default (objectiveReinforcement: true) and uses dual detection — both a flag and a text pattern match — to identify compaction events regardless of which layer triggered them.

Objective reinforcement is especially valuable for long-running sub-agents that go through multiple compaction cycles. Without it, a sub-agent could drift from its original task after the conversation is summarized.

Lifecycle hooks

The subagent context lifecycle provides two hooks for managing resources and emitting observability events:

prepareSpawn — Called before the sub-agent begins execution. Creates the disk directory for result storage (~/.comis/subagent-results/{sessionKey}/) and returns a rollback handle. If the spawn fails for any reason (limit rejection, configuration error), the rollback handle cleans up the created directory so no orphaned files are left behind.

onEnded — Called after the sub-agent finishes and its result has been condensed and narrative-cast. Emits a session:sub_agent_lifecycle_ended event with the full lifecycle metadata (end reason, runtime, token counts, condensation level, disk path). Plugins and monitoring systems can subscribe to this event for observability.

Both hooks degrade gracefully: if a hook fails, the spawn proceeds with fallback behavior and a WARN-level log is emitted. Hooks never block or crash the sub-agent lifecycle.

Configuration

All subagent context settings live under security.agentToAgent.subagentContext in your config file. The defaults work well for most setups — you only need to configure values you want to change.

~/.comis/config.yaml

security:
  agentToAgent:
    enabled: true
    allowAgents: ["coder", "researcher"]
    subAgentMaxSteps: 50
    subAgentToolGroups: ["coding"]
    subagentContext:
      # -- Spawn limits --
      maxSpawnDepth: 3             # max depth: parent -> child -> grandchild
      maxChildrenPerAgent: 5       # max concurrent active children per parent

      # -- Result handling --
      maxResultTokens: 4000        # token threshold for condensation
      resultRetentionMs: 86400000  # full result retention (24 hours)
      condensationStrategy: "auto" # auto | always | never
      errorPreservation: true      # keep error details in condensed results

      # -- Parent context --
      includeParentHistory: "none" # none | summary
      parentSummaryMaxTokens: 1000 # token limit for parent summary

      # -- Context management --
      objectiveReinforcement: true # re-inject objective after compaction
      artifactPassthrough: true    # pass artifact refs to sub-agent
      autoCompactThreshold: 0.95   # context fill ratio for auto-compaction

      # -- Narrative casting --
      narrativeCasting: true              # format results with tags
      resultTagPrefix: "Subagent Result"  # tag prefix for result formatting

The autoCompactThreshold field is present in the schema but its runtime effect on the context engine compaction trigger is being refined in a future release. The default value of 0.95 is safe to leave unchanged.

See the Config YAML Reference for the full list of all security.agentToAgent options.

Steering a running sub-agent

The subagents tool’s steer action redirects a sub-agent that is already running, and it is distinct from kill:

• kill terminates the child and tears it down cleanly. The run ends with the killed end reason and its in-flight work is discarded.
• steer sends a high-priority steering message to the child. How that message is delivered is gated behind security.agentToAgent.steerInject (default false):
  • Flag off (default) — steer falls back to kill + respawn: the running child is killed and a fresh run is spawned with the steering message as its new task. The prior transcript and progress are discarded, and the run gets a new runId. This is today’s behavior, unchanged.
  • Flag on — steer injects the message into the running child’s live session, preserving its transcript and progress (no kill, no respawn; the same runId continues).

Next-step-boundary semantics (inject mode). An injected steer is not a mid-tool-call interrupt. The child finishes its current step, the transcript for that step commits, and the steering message then lands as a user turn in the child’s next context assembly. The child keeps everything it had done up to that boundary — the steer adjusts course without throwing away work. (When the child is mid-stream the inject rides the streaming path; when it is idle it lands as a follow-up turn. The subagent:steered event records which via its mode field — counts/ids/mode only, never the message body.)

A steer is a message, not a privilege grant. A steered child’s tool set is fixed at spawn time, so it cannot be steered into using a tool on the sub-agent tool denylist — a steered request for a denied tool is still refused with denied to ALL sub-agents -- the parent must perform this step, and the child’s sandbox posture is unchanged. The steer text cannot widen what the child is allowed to do; it can only redirect what the child works on within its existing governance. See subagent.steer for the RPC surface and its discriminated-union response.

steer targets a running child. If the target run has already completed/failed or is still queued, steer fails fast with Run <id> is not running (status: <status>) -- cannot steer; use kill+respawn instead. (mirroring kill’s precondition error) rather than attempting an inject against a child that has no live session.

steer is intentionally ungated, unlike kill. kill requires an explicit confirmation (it discards the child’s in-flight work, a destructive teardown). steer has no confirmation gate: in inject mode it is non-destructive (the transcript and progress are preserved), and even in the flag-off kill+respawn fallback it is a course-correction, not a bare teardown. A steer is a steering message, so the asymmetry is deliberate.

End reasons

When a sub-agent’s lifecycle ends, one of six end reasons is recorded:

Reason	Description
completed	The sub-agent finished its task normally
failed	An unrecoverable error occurred during execution
killed	The sub-agent was force-terminated. The kill is attributed via killedBy (parent | health_monitor | operator | system) on the failure record, the subagent:killed event, and the run status the parent polls — a daemon health-monitor stuck-kill (no observed tool/LLM progress past stuckKillThresholdMs) never reads as a parent kill, and it delivers an LLM-free failure notification to the announce channel
swept	The sub-agent’s result files were removed by the retention sweep after resultRetentionMs expired
watchdog_timeout	The sub-agent exceeded its wall-clock timeout and was force-failed by the watchdog timer. See Resilience.
ghost_sweep	The sub-agent was stuck in “running” state past the grace period and was force-failed by the periodic ghost sweep. See Resilience.

The end reason is included in the session:sub_agent_lifecycle_ended event and in the narrative-cast metadata, giving the parent agent and operators full visibility into how each sub-agent run concluded.

Related

Sessions Tool Reference

Parameters and usage for sessions_spawn, sessions_kill, and other session tools.

Compaction

How the context engine manages conversation length, including the compaction that triggers objective reinforcement.

Config YAML Reference

Full configuration reference for all subagentContext options and other security settings.

Event Bus

Developer guide for subscribing to lifecycle events like session:sub_agent_lifecycle_ended.

Resilience

Timeout guards, provider health monitoring, and dead-letter queue.