| name | bash-subagent-write-limitation |
| description | Fix for Task tool subagents with subagent_type=Bash being unable to write files when
PreToolUse hooks block write operations. Use when: (1) dispatching parallel Bash agents
to implement code in worktrees, (2) agents report "Permission to use Bash has been
auto-denied", (3) agents can read files but all write/touch/cp/dd commands fail.
Solution: write files from the parent session using Write/Edit tools, then optionally
dispatch Bash agents only for validation (lint, test, typecheck).
|
| author | Claude Code |
| version | 1.0.0 |
| date | 2026-02-01T00:00:00.000Z |
Bash Subagents Cannot Write Files Under PreToolUse Hooks
Problem
When dispatching parallel agents using Task with subagent_type=Bash, these agents
only have access to the Bash tool. If PreToolUse hooks (e.g., from hookify or custom
plugins) block file-write Bash commands, the agent gets stuck in a loop trying
different write approaches (heredoc, dd, python -c, base64) — all denied.
Context / Trigger Conditions
- Using
Task tool with subagent_type=Bash and run_in_background=true
- PreToolUse hooks configured that filter/block Bash write operations
- Agent output shows repeated "Permission to use Bash has been auto-denied"
- Agent can run read-only commands (ls, cat, whoami, date) but not writes
Solution
- Don't use Bash subagents for implementation tasks when hooks are active
- Write files from the parent session using Write/Edit tools (these bypass Bash hooks)
- Then dispatch Bash agents only for validation: lint, test, typecheck, commit
- Alternative: use
subagent_type=general-purpose which has Write/Edit tools, but these
are heavier and slower
Recommended Pattern
1. Parent session: Write all source files using Write tool
2. Parent session: Write all test files using Write tool
3. Dispatch Bash agents (parallel) for: ruff check, mypy, pytest, git commit
4. Or just run validation from parent session directly
Verification
- Check agent output file for "auto-denied" messages
- If agents complete successfully with commits, the approach worked
Notes
- The
general-purpose subagent type has all tools but is slower to start
- If no hooks are configured, Bash subagents can write files normally
- This is specific to the interaction between Task tool's Bash agents and PreToolUse hooks
- The hooks system doesn't distinguish between "write to project" and "write to /tmp"
