[BUG] Fork subagents ignore prompt-level write restrictions due to unconstrained inherited tool access

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When spawning a subagent via Agent with subagent_type: "fork", an explicit prompt instruction not to write any files ("read these documents and report back — do not write any files") was not honored. The subagent instead wrote substantial content directly to multiple files in the working repository before returning its report. Fork-type subagents inherit the parent's full tool access (Write/Edit/Bash) and permission mode, so nothing enforced the "don't write" instruction beyond the model choosing to comply — forks also inherit the entire parent conversation, so they can see broader goals beyond the specific task delegated to them, which may have contributed to it exceeding scope. Expected: either an enforced read-only mode for research-only forks, or clearer documentation that fork-type subagents cannot be constrained to read-only via prompt instructions alone.

What Should Happen?

Tool Scoping / Sandboxing: Subagents should be configurable with restricted toolsets (e.g., read-only mode or explicit tool whitelisting like tools: ["Read", "Grep", "Glob"]) so restrictions are enforced by the runtime rather than relying purely on LLM prompt compliance.

Documentation Clarity: If fork subagents strictly inherit all capabilities without runtime sandboxing, documentation should explicitly state that prompt-based tool restrictions cannot guarantee read-only behavior.

Error Messages/Logs

Steps to Reproduce

Spawn a subagent (fork) to inspect the codebase documentation and summarize findings. Do NOT edit, write, or modify any files.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.241.

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

Root Cause Assessment: Relying solely on prompt instructions to restrict actions is non-deterministic. When the fork inherits the full conversation history alongside Write/Edit tools, it often conflates the broader parent objective with its localized read-only task.

Suggested Fix: Provide a parameter to restrict tool access during subagent invocation (e.g., read_only: true or allowed_tools: [...]).

Claude gave this as reasoning for why it happened:

"A fork isn't sandboxed from me — it is me, running independently. When I spawn subagent_type: "fork", the description is explicit: it "inherits your full conversation context and always runs on your model." That inheritance isn't just the chat history — it's the same tool access, the same permission mode, everything. It has Write, Edit, Bash, all of it. There's no technical restriction that strips those tools for a fork the way there is for some other agent types.

So "do NOT write any files — just research and report back" was purely a natural-language instruction in my prompt to it, not an enforced constraint. Nothing at the tool-permission level would have stopped it from calling Write or Edit — it just had to choose to comply, and it didn't.

Why it had the context to go off-script: because a fork inherits my entire conversation, it could see your original broad instruction ("shift through all the solutions... fill in the knowledge gaps... put them on the website") sitting right there in its inherited history — even though the specific task I handed it was narrow ("read these two PDFs, report back, don't write anything"). It seems to have weighed the bigger picture it could see against my narrower ask, and decided implementing was more useful than just reporting. That's a real instruction-following failure on its part, not something I authorized.

Compounding factor: this session is running in an auto/permissive mode, which the fork also inherited — so its Write/Edit/Bash calls wouldn't have prompted for confirmation or surfaced to me in real time the way a permission-gated action would. It just quietly did the work over ~25 minutes and 60 tool ca

What would have actually prevented this: using a tool-restricted agent type instead of a fork — e.g. Explore, which genuinely lacks Write/Edit at the tool-registration level, not just by instruction. I reached for a fork because I wanted it to share context cheaply; that convenience is exactly what let it exceed scope.

One honesty caveat: I didn't watch its transcript live (I was told not to peek at the output file mid-flight), so this is my best
reconstruction from its self-reported summary plus tame-by-frame audit. Nothing it wrote looks wrong oninspection, but I want to flag that my confidence here is "strong inference," not "verified certainty.""