Subagent Family Tracking

Sub-Agent Family Tracking

When you spawn sub-agents, you create a family tree: you are the parent, your spawned agents are children, and your children's spawned agents are grandchildren. If you do not track this tree explicitly, three failure modes are common:

1. Lost child — you spawn an agent, lose track of its task_id, and never read its result.
2. Sibling duplication — two children of yours do the same work, wasting tokens.
3. Lingering child — you move on to the next sub-task, leaving an old child running in the background, burning context budget.

This Skill codifies a family-tracking file so these failures are visible, not hidden.

When to use

Activate when any of these is true:

• You are about to call task and the result of that call is "fire and wait," not "do it inline." (Inline calls don't need a tree.)
• You have already spawned one or more sub-agents in this session.
• The task description suggests a tree: "X has sub-tasks", "for each of A/B/C, ...", "the migration has 5 stages, each stage can be parallelised."
• A user asks "what's your sub-agent doing right now?" and you don't have an immediate answer.

When NOT to use

• The sub-task is so cheap you would just inline it. (No sub-agent → no tree.)
• The harness already exposes a live dashboard of running sub-agents. (Use that instead.)
• You are the child, not the parent. Children don't track siblings; they only see their own parent.

Process

1. Pick a single, predictable path. Default (illustrative; actual on-disk path is host-internal): <host-agents-root>/<thread-id>/subagents.md. The mcode 0.2.4 public surface does not document a family-file path. The Skills below use <host-agents-root> as a conceptual placeholder; the host determines the actual root. Different from the goal file (which is "what we are doing") and the world-state file (which is "where we are"); this is "who is working for us."

2. Initialise the file on the first spawn in this exact shape:

   # Sub-agent family — <short task name>
   
   **Parent (you)**: <thread-id>
   **Last updated**: <ISO timestamp>
   
   ## Children
   
   | id | spawned_at | brief | status | result_summary |
   |----|------------|-------|--------|----------------|
   | <task_id> | <ISO> | <one-line brief> | open | (pending) |
   

3. On every spawn, add a row with status: open and a one-line brief.

4. On every sub-agent completion, update the row:

   • status: closed (or closed-failed if it didn't meet its pass condition)
   • result_summary: <one line>

5. If a sub-agent spawns its own children, append a sub-section for that child:

   | <task_id> | <ISO> | <one-line brief> | open | (pending) |
     ## Children of <task_id>
     | grandchild-id | spawned_at | brief | status | result_summary |
     |---------------|------------|-------|--------|----------------|
   

6. At every context-pressure-compact, the compact summary must reference the family file by path, not duplicate it. The file is the ground truth.

7. At the end of a fan-out aggregation (see parallel-fanout), include a one-line "all children closed" check. If any are still open, surface that to the user — the aggregation is not safe to declare done while children are running.

Output contract

The user sees:

• The family file's contents (full) at the start of any multi-agent task.
• A one-line status update per spawn / completion (e.g. "spawned task-7a3f for OIDC review," "task-7a3f closed with PASS").
• A "all children closed" check at the end of any fan-out.

Example

The path to the family file in the example below is illustrative; the actual on-disk path is host-internal. The thread-7c2b value is a placeholder for the calling session's thread id (on mcode 0.2.4 the relevant lifecycle identifier for a sub-agent is the task_id returned by task(...)). The file shape is what the calling agent maintains in its own bookkeeping.

# Sub-agent family — Auth refactor (OIDC alongside SAML)

**Parent (you)**: thread-7c2b *(placeholder for the calling session's thread id)*
**Last updated**: 2026-08-23T23:55:00Z

## Children

| id | spawned_at | brief | status | result_summary |
|----|------------|-------|--------|----------------|
| task-3f1a | 23:40:00Z | Audit /repo/server/Cargo.toml for CVEs | closed | No critical CVEs; 2 moderate, listed in SECURITY-REPORT.md |
| task-4d2b | 23:40:00Z | Audit /repo/web/package.json for CVEs | closed | 1 critical CVE (CVE-2024-xxxx); surfaced immediately, did not wait for others |
| task-5e3c | 23:40:00Z | List licenses of /repo/server and /repo/web direct deps | open | (pending) |

After task-5e3c finishes:

| task-5e3c | 23:40:00Z | List licenses of /repo/server and /repo/web direct deps | closed | 47 deps; 1 AGPL, 4 Apache-2.0, rest MIT — full table in SECURITY-REPORT.md |

If task-5e3c spawned a grandchild (e.g. for cross-checking an ambiguous license):

| task-5e3c | 23:40:00Z | List licenses of /repo/server and /repo/web direct deps | closed | 47 deps; 1 AGPL, 4 Apache-2.0, rest MIT |
  ## Children of task-5e3c
  | task-5e3c-1 | 23:42:00Z | Cross-check `foo-1.0.0` license classification | closed | Confirmed AGPL-3.0 via SPDX registry |

Common pitfalls

• Do not skip the file "because it's only one sub-agent." You will spawn another before you know it, and then you will not know which results came from which.
• Do not put full sub-agent output in the table. The table is the index. The full output lives in the sub-agent's own response (or a file it wrote). The table points to it.
• Do not let the file grow unbounded. A 500-line family file is no longer a tracking file. If it grows past ~80 lines, summarise closed children into a "Completed (summary)" section.
• Do not confuse "open" with "running". A sub-agent can be open and waiting on user input, or open and silently failed. "Closed" means the result was received and processed, not that the work succeeded.
• Do not declare fan-out done while children are still open. A parallel-fanout aggregation must wait for all children to close. The check is mechanical, not visual.
• Do not let a child spawn grand-children without recording it. If you do not capture the grandchild relationship, you cannot tell which child is responsible for which grandchild's result.

Verification checklist

• Is the family file at a single, predictable path?
• Is it initialised with the full table shape on the first spawn?
• Does every spawn add a row with status: open?
• Does every completion update the row to status: closed?
• Are grand-children recorded in a sub-section under their parent?
• Is the file < ~80 lines? (Summarise old entries if not.)
• At every context-pressure-compact, is the file referenced by path (not duplicated)?
• At the end of any fan-out, is the "all children closed" check explicit?