Warn against a named extraction subagent (#2847)

CHANGELOG.md

@@ -4,6 +4,8 @@ Full release notes with details on each version: [GitHub Releases](https://githu
 
 ## 0.9.63 (2026-09-16)
 
+- Fix: the `/graphify` skill's Step B2 now warns against dispatching an extraction subagent with the `name` parameter. A named Agent call's report can return only through `SendMessage`; when that path is unavailable the caller gets a bare idle notification with zero findings — indistinguishable from a chunk that silently failed, so Part C's merge quietly proceeded with missing nodes (#2847, thanks @turtoirazvan).
+
 - Feature: Elixir `alias`/`import`/`require`/`use` targets now resolve onto the module's `defmodule` node across files, so the internal module dependency graph is no longer dropped as dangling. Only top-level modules are indexed (a nested `defmodule`, labeled with its bare inner name, cannot capture an unrelated `use <Name>` from another file), and a same-file reference is left unresolved so it cannot clobber the structural `contains` edge (#3603, thanks @ayushcodes10).
 - Feature: a Rust `self.method()` call now resolves to a method defined on the same type in another file (the common split-`impl`-block layout), pooling methods across every `impl` of one type and refusing to link when two unrelated types share a bare name (#3602, thanks @ayushcodes10).
 - Feature: a Ruby member call `obj.foo` on a known-type receiver now resolves to a method `foo` inherited from a superclass, including across files, using the same conservative promotion as the implicit-self resolver — a single owning class, matching method kind, and one unambiguous ancestry chain, or it stays dangling (#3585, thanks @oleksii-tumanov).

graphify/skill-claw.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

graphify/skill-copilot.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

graphify/skill-kilo.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

graphify/skill-kiro.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

graphify/skill-pi.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

graphify/skill-windows.md

@@ -283,6 +283,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

graphify/skill.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tests/test_install.py

@@ -462,6 +462,22 @@ def test_claw_skill_uses_agent_tool_dispatch():
     assert "@mention" not in skill
 
 
+def test_agent_tool_hosts_warn_against_a_named_subagent():
+    """#2847: a named Agent call's report can return only via SendMessage: if
+    that path is unavailable, the caller gets a bare idle notification with
+    zero findings, indistinguishable from a chunk that silently failed. Every
+    host dispatching via the Claude Code Agent tool (subagent_type=...) must
+    carry the "no name" warning alongside the subagent-type guidance."""
+    import graphify
+
+    for name in ("skill.md", "skill-claw.md"):
+        skill = (Path(graphify.__file__).parent / name).read_text()
+        assert 'subagent_type="general-purpose"' in skill, f"{name}: not an Agent-tool host?"
+        b2 = skill[skill.index("**Step B2"):skill.index("**Step B3")]
+        assert "IMPORTANT - no `name`" in b2, f"{name}: missing the no-name warning in Step B2"
+        assert "SendMessage" in b2, f"{name}: warning must explain the SendMessage failure mode"
+
+
 def test_all_skill_files_exist_in_package():
     """All installable platform skill files must be present in the installed package."""
     import graphify

tools/skillgen/expected/graphify__skill-claw.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/expected/graphify__skill-copilot.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/expected/graphify__skill-kilo.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/expected/graphify__skill-kiro.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/expected/graphify__skill-pi.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/expected/graphify__skill-windows.md

@@ -283,6 +283,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/expected/graphify__skill.md

@@ -256,6 +256,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/fragments/dispatch/agent-tool-disk-powershell.md

@@ -4,6 +4,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]

tools/skillgen/fragments/dispatch/agent-tool-disk.md

@@ -4,6 +4,8 @@ Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. Th
 
 **IMPORTANT - subagent type:** Always use `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. General-purpose has Write and Bash access which the subagent needs.
 
+**IMPORTANT - no `name`:** Spawn every extraction subagent WITHOUT the `name` parameter. A named agent's report may return only via `SendMessage`; if that path is unavailable the report is unrecoverable and you get a bare idle notification with zero findings - indistinguishable from a chunk that silently failed. An unnamed Agent call returns a real result through the completion notification instead.
+
 Concrete example for 3 chunks:
 ```
 [Agent tool call 1: files 1-15, subagent_type="general-purpose"]