---
name: subagent-family-tracking
description: |
  Track parent/child thread tree of spawned sub-agents with Open/Closed status.
  USE WHEN: spawned one or more sub-agents, task description suggests a tree (sub-tasks, "for each of A/B/C", "5 stages"), user asks "what's your sub-agent doing right now" / "子 agent 都在干嘛", sub-agent may fan out, want to know "还在跑吗" / "还有几个没关", before declaring fan-out done (all children closed check).
  TRIGGER PHRASES: "子 agent 都在干嘛", "sub-agent", "子任务", "family tree", "who is running", "还在跑吗", "还有几个没关", "what's your sub-agent doing", "subagent family", "subagent tree", "all children closed".
  SKIP WHEN: sub-task is so cheap you'd just inline it, harness already exposes live sub-agent dashboard, you are the child not the parent.
license: Apache-2.0
compatibility: Targets MiniMax Code 0.2.4. **Conceptual reference only.** The family-file path is **host-internal** on mcode 0.2.4; the mcode public surface does not document a family-file path. The Skills below use `<host-agents-root>/<thread-id>/subagents.md` as a conceptual placeholder; the host determines the actual root. The `<thread-id>` placeholder is the calling session's thread id; on mcode 0.2.4, sub-agent lifecycles are tracked by `task_id` (returned by `task(...)`) and any cross-sub-agent parent/child bookkeeping is the calling agent's responsibility.
metadata:
  author: antianqi
  version: "0.1.2"
  inspired-by: https://github.com/openai/codex/blob/main/codex-rs/agent-graph-store/
  changes-from-v0.1.1: "v1.0.5 amendment (PR #33 round-12, hetaoBackend CHANGES_REQUESTED on head 5a4e3fc): the previous body pinned a literal `.minimax/agents/<thread-id>/subagents.md` path and a `Requires MiniMax Code with Agent Plugins 1.0 support.` compatibility string with no mcode 0.2.4 contract backing. The body now wraps the family-file path in a `<host-agents-root>/<thread-id>/subagents.md` placeholder with an `illustrative; actual path is host-internal` annotation, and the `compatibility` frontmatter field explicitly states the conceptual-reference nature of the layout."
---

# 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:

   ```markdown
   # 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:

   ```markdown
   | <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.

```markdown
# 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:

```markdown
| 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):

```markdown
| 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?