Defame1297
1a66ee939a
The fan-out restored in 6683da5 had no degrade path for a target with no
spawn tool, which reproduces the silent degradation #116 was written
against. Step 4 now says to read serially and reduce each page to notes
when spawning is unavailable.
The change restores existing behaviour, so the version bump is a patch
(1.0.2) per skill-author's convention, not a minor. The body is trimmed
from 717 to under the 600-word ADR-0020 target without dropping any
instruction. ADR-0027 is updated to match.
Refs #116
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EGHFJextYtVQseaHPDDhxB
3.4 KiB
research gets its fan-out back and keeps its tool list; a body must not disclaim spawning
Status: Accepted (2026-09-21)
plugins/bin/.apm/skills/research/SKILL.md once told the agent to "spawn one subagent per URL"
while its allowed-tools listed nothing that spawns. WebFetch was listed, so nothing hard-failed:
the skill degraded to serial fetches in the orchestrator's own context, and the "in parallel"
wording, the page cap and the "subagents summarise, orchestrator writes" gotcha quietly stopped
meaning anything. The #99 retrofit rewrote steps 4 and 5 as serial reads and said in the text that
no subagent tool was granted (#116).
What #116 did not establish. It read the missing tool as the cause. The repo's own sources
describe allowed-tools as pre-approval, not restriction: skill-author/references/create.md:113
("space-separated pre-approved tools; reduces permission prompts"), the agentskills.io
specification, and the Copilot plugin docs. On that reading an unlisted spawn tool would prompt, not
fail. What Claude Code, Copilot and Codex actually do with an unlisted tool is not verified
here, and neither is whether omitting the field grants anything. What is documented is that the
serial behaviour followed the step text, which told the agent to go serial.
Decision. research keeps its allowed-tools list and gets its parallel fan-out back in steps
4 and 5, with the "subagents read and summarise; the orchestrator writes every file" gotcha
restored (version 1.0.1 → 1.0.2). A skill body that instructs spawning must not be paired with text
saying spawning is unavailable. Step 4 carries a serial fallback for a target with no spawn tool, so
an unavailable spawn degrades visibly instead of silently.
The spawn tool is not added to the list. Its name is sourced for Claude Code (Agent) only; the
Copilot and Codex names are not known. On Claude Code, spawns therefore prompt instead of being
pre-approved. Add the tool once its name is sourced for each target.
Corpus facts, with limits. write-docs, improve-codebase-architecture and forge all omit
allowed-tools and instruct spawning subagents — forge from references/author-routes.md and
references/version-bump.md, not from its SKILL.md. That shows they spawn, not that a run
succeeded. skill-author/SKILL.md:24 forbids spawning a subagent to recheck one's own work, which
is a different question and unaffected here. CONTEXT.md says a plugin-scope agent delegates to
skills because it cannot disclose to itself; nothing there bans a skill from delegating.
The security cost is real and not mitigated. "The orchestrator alone writes files" is prose,
not enforcement. The subagents read untrusted web pages, and nothing restricts what tools they
hold. Not done, by decision: an instruction to treat fetched page content as data, a cap on the
number of subagents (user-supplied URLs are uncapped, and the step 5 page cap bounds less once
reads run in parallel), and read-only subagents. docs/research/ai-coding-factory/ ai-coding-factory-principles.md:53 recommends applying allowed-tools restrictions, which is why
the list was kept.
Rejected: dropping allowed-tools on the premise that it blocked spawning (unsupported by the
repo's own sources, and it widens the tool surface for nothing), and banning spawning in skills
(three skills instruct it, and CONTEXT.md does not forbid it).