Name the subagent capability requirement, not just general-purpose (#2525)

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 extraction-subagent dispatch instructions named the literal agent type `general-purpose` as the only acceptable choice, so a host whose dispatch policy restricts or refuses that exact type (an org policy hook, a curated persona registry) could not follow the skill as written, and every diagnostic pointed back at the one type the host would not permit. The instructions now state the actual requirement — Write and Bash access, since the subagent builds its chunk file on disk — keep `general-purpose` as the default, and tell a policy-restricted host to dispatch any permitted type with both tools instead. The internal guard that checks the devin monolith stays in sync with this wording now matches only the two changed lines' exact old and new forms, not a bare substring that also matched an unrelated worked example line (#2525, thanks @maxhawk1).
+
 - 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-agents.md

@@ -278,10 +278,10 @@ See `references/extraction-spec.md` for the exact subagent prompt (JSON schema,
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_NN.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only (Explore type) — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type (e.g. Explore) — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent call completes, read the real token counts from the Agent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then run:
 ```bash

graphify/skill-amp.md

@@ -278,10 +278,10 @@ See `references/extraction-spec.md` for the exact subagent prompt (JSON schema,
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_NN.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only (Explore type) — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type (e.g. Explore) — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent call completes, read the real token counts from the Agent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then run:
 ```bash

graphify/skill-claw.md

@@ -254,7 +254,7 @@ Load files from `graphify-out/.graphify_uncached.txt`. Split into chunks of 20-2
 
 Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. This is the only way they run in parallel. If you make one Agent call, wait, then make another, you are doing it sequentially and defeating the purpose.
 
-**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 - subagent type:** the extraction subagent MUST have Write and Bash access - it builds the chunk file on disk itself. Default to `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. If this host's dispatch policy restricts or refuses `general-purpose` (an org policy hook, a curated persona registry), dispatch any available type that lists Write and Bash access instead - that is a host policy constraint, not a graphify requirement. Never downgrade to a read-only type to satisfy a policy; that trades a loud failure for a silent one.
 
 Concrete example for 3 chunks:
 ```
@@ -281,10 +281,10 @@ See `references/extraction-spec.md` for the exact subagent prompt (JSON schema,
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_NN.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only (Explore type) — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type (e.g. Explore) — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent call completes, read the real token counts from the Agent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then run:
 ```bash

graphify/skill-codex.md

@@ -278,10 +278,10 @@ See `references/extraction-spec.md` for the compact subagent prompt (rules, node
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_NN.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only (Explore type) — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type (e.g. Explore) — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent call completes, read the real token counts from the Agent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then run:
 ```bash

graphify/skill-copilot.md

@@ -254,7 +254,7 @@ Load files from `graphify-out/.graphify_uncached.txt`. Split into chunks of 20-2
 
 Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. This is the only way they run in parallel. If you make one Agent call, wait, then make another, you are doing it sequentially and defeating the purpose.
 
-**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 - subagent type:** the extraction subagent MUST have Write and Bash access - it builds the chunk file on disk itself. Default to `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. If this host's dispatch policy restricts or refuses `general-purpose` (an org policy hook, a curated persona registry), dispatch any available type that lists Write and Bash access instead - that is a host policy constraint, not a graphify requirement. Never downgrade to a read-only type to satisfy a policy; that trades a loud failure for a silent one.
 
 Concrete example for 3 chunks:
 ```
@@ -281,10 +281,10 @@ See `references/extraction-spec.md` for the exact subagent prompt (JSON schema,
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_NN.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only (Explore type) — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type (e.g. Explore) — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent call completes, read the real token counts from the Agent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then run:
 ```bash

graphify/skill-devin.md

@@ -331,10 +331,10 @@ FILE_LIST
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_N.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 After each subagent call completes, write its result to `graphify-out/.graphify_chunk_N.json`. **After each subagent call completes, read the real token counts from the subagent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then merge:
 

graphify/skill-droid.md

@@ -278,10 +278,10 @@ See `references/extraction-spec.md` for the exact subagent prompt (JSON schema,
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_NN.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only (Explore type) — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type (e.g. Explore) — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent call completes, read the real token counts from the Agent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then run:
 ```bash

graphify/skill-kilo.md

@@ -254,7 +254,7 @@ Load files from `graphify-out/.graphify_uncached.txt`. Split into chunks of 20-2
 
 Call the Agent tool multiple times IN THE SAME RESPONSE - one call per chunk. This is the only way they run in parallel. If you make one Agent call, wait, then make another, you are doing it sequentially and defeating the purpose.
 
-**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 - subagent type:** the extraction subagent MUST have Write and Bash access - it builds the chunk file on disk itself. Default to `subagent_type="general-purpose"`. Do NOT use `Explore` - it is read-only and cannot write chunk files to disk, which silently drops extraction results. If this host's dispatch policy restricts or refuses `general-purpose` (an org policy hook, a curated persona registry), dispatch any available type that lists Write and Bash access instead - that is a host policy constraint, not a graphify requirement. Never downgrade to a read-only type to satisfy a policy; that trades a loud failure for a silent one.
 
 Concrete example for 3 chunks:
 ```
@@ -281,10 +281,10 @@ See `references/extraction-spec.md` for the exact subagent prompt (JSON schema,
 Wait for all subagents. For each result:
 - Check that `graphify-out/.graphify_chunk_NN.json` exists on disk — this is the success signal
 - If the file exists and contains valid JSON with `nodes` and `edges`, include it and save to cache
-- If the file is missing, the subagent was likely dispatched as read-only (Explore type) — print a warning: "chunk N missing from disk — subagent may have been read-only. Re-run with general-purpose agent." Do not silently skip.
+- If the file is missing, the subagent was likely dispatched as a read-only type (e.g. Explore) — print a warning: "chunk N missing from disk — subagent may have been dispatched without Write and Bash access. Re-run with a subagent type that has both." Do not silently skip.
 - If a subagent failed or returned invalid JSON, print a warning and skip that chunk - do not abort
 
-If more than half the chunks failed or are missing, stop and tell the user to re-run and ensure `subagent_type="general-purpose"` is used.
+If more than half the chunks failed or are missing, stop and tell the user to re-run using a subagent type that has Write and Bash access (`general-purpose` by default; any host-permitted type with those two tools otherwise).
 
 Merge all chunk files into `.graphify_semantic_new.json`. **After each Agent call completes, read the real token counts from the Agent tool result's `usage` field and write them back into the chunk JSON before merging** — the chunk JSON itself always has placeholder zeros. Then run:
 ```bash
@@ -708,7 +708,7 @@ When the user asks to install the post-commit auto-rebuild hook or wire graphify
 
 - Use the native `Task` tool for semantic extraction fan-out.
 - Launch all chunk tasks in the same response so they run in parallel.
-- Always use `subagent_type="general"` for extraction chunks.
+- Default to `subagent_type="general"` for extraction chunks; it needs Write and Bash access, so if a dispatch policy restricts `general`, use any permitted type with both tools instead.
 - After modifying code files during the session, run `graphify update .`.
 
 ---