Link teammate subagent transcripts spawned by the Agent tool

claude_code_log/cache.py

@@ -2011,6 +2011,14 @@ def _is_cache_version_compatible(self, cache_version: str) -> bool:
             # earlier have the caveat text baked into first_user_message
             # for affected sessions.
             "1.4.0": "1.5.0",
+            # 1.6.1 fixed the teammate prompt-hash fallback, which only
+            # looked at ``Task`` tool_uses and so never fired for the
+            # ``Agent`` spawn tool current Claude Code uses. Every cache
+            # built up to and including 1.6.0 has the *unlinked* entry
+            # list baked in — the subagent transcripts are simply absent
+            # from them, and nothing about the source files changes to
+            # trigger a reparse.
+            "1.6.0": "1.6.1",
         }
 
         cache_ver = version.parse(cache_version)

claude_code_log/converter.py

@@ -934,21 +934,27 @@ def _link_subagents_by_prompt_hash(
 ) -> None:
     """Link teammate subagent JSONLs whose agentId isn't in the main transcript.
 
-    Teammate-spawned Tasks sometimes produce tool_results that don't carry a
+    Teammate-spawned Tasks/Agents sometimes produce tool_results that don't carry a
     structured ``agentId`` — the linking info only appears in the Markdown
     metadata tail (parsed separately) or is absent altogether. Older
     transcripts predate the tail too. For these we fall back to matching
-    the Task tool_use's ``prompt`` input against each unmatched
+    the spawn tool_use's ``prompt`` input against each unmatched
     ``subagents/agent-*.jsonl`` file's first-entry content. When the first
     entry wraps the prompt in ``<teammate-message teammate_id="team-lead">``,
     that body is compared; otherwise the raw text is.
 
+    Matching runs in two passes. Teammates routinely share a
+    byte-identical prompt, so the prompt alone does not identify one;
+    the first pass additionally requires the spawn's ``input.name`` to
+    equal the sidecar's ``name``, and only what that leaves over falls
+    through to prompt-only matching.
+
     On a match, the agent id is added to *agent_ids* (so the existing loader
     picks the file up) and the corresponding tool_result entry's ``agentId``
     field is back-patched (so ``_integrate_agent_entries`` anchors the
     subagent DAG-line to the right place).
 
-    No-op when the subagents dir doesn't exist or every Task is already
+    No-op when the subagents dir doesn't exist or every spawn is already
     linked; safe to call unconditionally.
     """
     unresolved = _collect_unresolved_task_results(messages)
@@ -964,10 +970,13 @@ def _link_subagents_by_prompt_hash(
     # normalized prompt would re-match an already-patched entry, wiping
     # the first match (concrete repro: team-lead sends identical
     # instructions to multiple teammates in parallel).
-    remaining: list[tuple[str, UserTranscriptEntry]] = [
-        (_normalize_prompt(prompt), entry) for prompt, entry in unresolved
+    remaining: list[tuple[str, Optional[str], UserTranscriptEntry]] = [
+        (_normalize_prompt(prompt), name, entry) for prompt, name, entry in unresolved
     ]
 
+    # Collect the candidate files first, so matching can run name-aware
+    # before it falls back to prompt-only (see the two passes below).
+    candidates: list[tuple[str, str, Optional[str]]] = []
     for agent_file in sorted(subagents_dir.glob("agent-*.jsonl")):
         candidate_agent_id = agent_file.stem[len("agent-") :]
         if not candidate_agent_id or candidate_agent_id in agent_ids:
@@ -982,29 +991,80 @@ def _link_subagents_by_prompt_hash(
         if not candidate_norm:
             continue
 
-        for i, (norm_prompt, result_entry) in enumerate(remaining):
+        candidates.append(
+            (candidate_agent_id, candidate_norm, _read_sidecar_name(agent_file))
+        )
+
+    def _claim(candidate_agent_id: str, index: int) -> None:
+        agent_ids.add(candidate_agent_id)
+        remaining[index][2].agentId = candidate_agent_id
+        remaining.pop(index)
+
+    # Pass 1 — teammate name. A prompt is NOT a discriminator for
+    # teammates: a team-lead fanning the same instructions out to N
+    # teammates gives every one of them a byte-identical body, and then
+    # prompt-only matching pairs them by filename sort order against
+    # message order, which is arbitrary. Measured over one real archive:
+    # 7 of 12 teammate sessions contained such a group (15 groups, the
+    # largest with 11 members), and prompt-only matching anchored 23
+    # spawns (~12% of those it linked) to the WRONG teammate — a
+    # permutation within each group. That is worse than not linking at
+    # all: an absent transcript invites a re-run, a confidently
+    # mis-attributed one invites a wrong conclusion.
+    #
+    # Both sides carry the discriminator. The spawn's ``input.name``
+    # (``TaskInput.name``, populated when a team-lead spawns a named
+    # teammate) and the sidecar's own ``name`` are the same string.
+    unmatched: list[tuple[str, str, Optional[str]]] = []
+    for candidate_agent_id, candidate_norm, candidate_name in candidates:
+        if candidate_name is None:
+            unmatched.append((candidate_agent_id, candidate_norm, candidate_name))
+            continue
+        for i, (norm_prompt, spawn_name, _entry) in enumerate(remaining):
+            if norm_prompt == candidate_norm and spawn_name == candidate_name:
+                _claim(candidate_agent_id, i)
+                break
+        else:
+            unmatched.append((candidate_agent_id, candidate_norm, candidate_name))
+
+    # Pass 2 — prompt only, unchanged behaviour. Covers every spawn that
+    # carries no name (plain ``Task`` sub-agents, older transcripts) and
+    # any teammate whose name didn't pair, so a missing or renamed
+    # sidecar degrades to the previous result rather than to no link.
+    for candidate_agent_id, candidate_norm, _candidate_name in unmatched:
+        for i, (norm_prompt, _spawn_name, _entry) in enumerate(remaining):
             if norm_prompt == candidate_norm:
-                agent_ids.add(candidate_agent_id)
-                result_entry.agentId = candidate_agent_id
-                remaining.pop(i)
+                _claim(candidate_agent_id, i)
                 break
 
 
 def _collect_unresolved_task_results(
     messages: list[TranscriptEntry],
-) -> list[tuple[str, UserTranscriptEntry]]:
-    """Return (prompt, tool_result_entry) for Task results lacking an agentId."""
-    task_prompts: dict[str, str] = {}
+) -> list[tuple[str, Optional[str], UserTranscriptEntry]]:
+    """Return (prompt, spawn name, tool_result_entry) for spawn results lacking an agentId.
+
+    Covers both spawn tool names: ``Task`` (sub-agents) and ``Agent``
+    (teammates). The teammate flow this fallback exists for is spelled
+    ``Agent`` in current Claude Code, so gating on ``Task`` alone turns
+    the whole fallback into a no-op for teammate sessions.
+    """
+    task_prompts: dict[str, tuple[str, Optional[str]]] = {}
     for msg in messages:
         if not isinstance(msg, AssistantTranscriptEntry):
             continue
         for item in msg.message.content:
-            if isinstance(item, ToolUseContent) and item.name == "Task":
+            if isinstance(item, ToolUseContent) and item.name in ("Task", "Agent"):
                 prompt = item.input.get("prompt")
                 if isinstance(prompt, str) and prompt:
-                    task_prompts[item.id] = prompt
+                    spawn_name = item.input.get("name")
+                    task_prompts[item.id] = (
+                        prompt,
+                        spawn_name
+                        if isinstance(spawn_name, str) and spawn_name
+                        else None,
+                    )
 
-    unresolved: list[tuple[str, UserTranscriptEntry]] = []
+    unresolved: list[tuple[str, Optional[str], UserTranscriptEntry]] = []
     for msg in messages:
         if not isinstance(msg, UserTranscriptEntry):
             continue
@@ -1013,13 +1073,35 @@ def _collect_unresolved_task_results(
         for item in msg.message.content:
             if not isinstance(item, ToolResultContent):
                 continue
-            prompt = task_prompts.get(item.tool_use_id)
-            if prompt is not None:
-                unresolved.append((prompt, msg))
+            entry = task_prompts.get(item.tool_use_id)
+            if entry is not None:
+                prompt, spawn_name = entry
+                unresolved.append((prompt, spawn_name, msg))
                 break
     return unresolved
 
 
+def _read_sidecar_name(agent_file: Path) -> Optional[str]:
+    """The teammate ``name`` from ``agent-<id>.meta.json``, if present.
+
+    Only the prompt-hash fallback needs this, so it is read here rather
+    than widened into the memoized ``_subagent_meta_map`` (whose value
+    type the sidecar path depends on). Returns None for a plain
+    ``Task`` sub-agent sidecar, which carries ``description`` instead —
+    those reach this code only when they also lack a ``toolUseId``, and
+    a None simply routes them to the prompt-only pass.
+    """
+    meta_path = agent_file.with_name(agent_file.stem + ".meta.json")
+    try:
+        raw: Any = json.loads(meta_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    name = cast("dict[str, Any]", raw).get("name")
+    return name if isinstance(name, str) and name else None
+
+
 def _read_first_message_text(agent_file: Path) -> Optional[str]:
     """Return the textual content of the first entry's ``message.content``.
 

dev-docs/teammates.md

@@ -349,13 +349,23 @@ whose stem isn't in the agent-id set, and for each:
    block (the canonical teammate-spawn shape), extract the body via
    `find_team_lead_body`. Otherwise use the raw text.
 3. Normalize via `_normalize_prompt`: collapse whitespace, lowercase.
-4. Compare against each unresolved Task tool_use's `prompt` input
+4. Compare against each unresolved spawn tool_use's `prompt` input
    (similarly normalized). Exact match wins.
-5. Back-patch the Task tool_result's `agentId` field, add to the agent-id
+5. Back-patch the spawn tool_result's `agentId` field, add to the agent-id
    set, and **remove the matched entry from the unresolved pool** so a
    second candidate file with the same prompt can't claim it (this last
    step was a CodeRabbit-driven fix on PR #117 — see commit `cc9951d`).
 
+> **Both spawn tool names count.** `_collect_unresolved_task_results`
+> gathers prompts from `Task` *and* `Agent` tool_uses. Teammates are
+> spawned by `Agent` in current Claude Code, and the sidecar
+> `agent-<id>.meta.json` it writes for an `in_process_teammate` carries
+> no `toolUseId` — so for a modern teammate session the prompt-hash
+> fallback is the *only* link, and gating it on `Task` alone silently
+> dropped every teammate transcript (the subagent JSONLs were never
+> opened). Pinned by
+> `test_prompt_hash_fallback_covers_both_spawn_tool_names`.
+
 Pre-normalized prompts are computed once up front to avoid quadratic
 work in the inner loop.
 

test/test_cache.py

@@ -675,9 +675,14 @@ def test_minor_version_increase_is_compatible(self, temp_project_dir):
         assert cache_manager._is_cache_version_compatible("1.0.5") is True
 
     def test_major_version_increase_is_compatible(self, temp_project_dir):
-        """Test that major version increases are compatible by default."""
+        """Test that major version increases are compatible by default.
+
+        The cache version has to sit *above* every declared breaking
+        boundary, otherwise this exercises a breaking rule rather than
+        the default path (1.6.0 became such a boundary in 1.6.1).
+        """
         cache_manager = CacheManager(temp_project_dir, "2.0.0")
-        assert cache_manager._is_cache_version_compatible("1.5.0") is True
+        assert cache_manager._is_cache_version_compatible("1.6.1") is True
 
     def test_version_downgrade_is_compatible(self, temp_project_dir):
         """Test that version downgrades are compatible by default."""