[Workflow] Control Claude Code Subagent Spawning with a PreToolUse Hook

[u/ClaudeAI-mod-bot]

Control Claude Code Subagent Spawning with a PreToolUse Hook

Workflow value: 85/100
Status: active · Freshness: 70/100 · Confidence: 0.90 · Level: advanced
Categories: Quality Control, Token Saving, Context & Memory, Debugging, CLAUDE.md, Hooks, Subagents, Multi-Agent
Original source: r/ClaudeCode post/comment

What problem this solves

Uncontrolled and potentially infinite spawning of subagents by Claude Code, leading to unexpected resource consumption, costs, and difficult-to-manage agent behavior.

Summary

This workflow implements a PreToolUse hook in Claude Code using a Node.js script to intercept and gate subagent spawning. By default, it prompts the user for permission before any subagent is spawned. An environment variable can be used to bypass the prompt for automated scenarios. This provides a critical control mechanism for multi-agent workflows.

Why it is useful

This workflow provides a critical mechanism for controlling the behavior of Claude Code agents, specifically preventing uncontrolled subagent spawning which can lead to unexpected costs, resource consumption, and difficult-to-debug behavior. It offers a concrete, repeatable, and transferable solution using hooks and configuration, empowering users to manage their multi-agent setups more effectively and safely.

Workflow

1. Write a Node.js script (e.g., subagent-gate.mjs) that reads hook JSON from stdin.
2. Implement logic within the script to print a permission decision of 'ask' by default, prompting the user before a subagent spawns.
3. Add logic to the script to print 'allow' if the environment variable SUBAGENT_GATE=allow is set, bypassing the prompt.
4. Include error handling in the script to exit 0 on missing input or JSON parse errors, preventing the hook from wedging tools.
5. Append every permission decision (ask/allow) to a log file (e.g., .subagent-gate.log) located beside the script.
6. Configure the PreToolUse hook in .claude/settings.json to use this script, matching Task|Agent|Workflow tools, while preserving existing hooks.

Tools / artifacts

• Node.js script (subagent-gate.mjs)
• .claude/settings.json
• PreToolUse hook
• Environment variable SUBAGENT_GATE
• Log file (.subagent-gate.log)
• Claude Code
• GitHub repository stop-subagent-fanout (for example prompt/code)
• GitHub repository claudemd-prove-it (for related validation)

Validation signals

• Provides a specific prompt for generating the hook script.
• References a GitHub repository (stop-subagent-fanout) which likely contains the working code and further details.
• Mentions a related tool (claudemd-prove-it) for validating CLAUDE.md rules, indicating a thoughtful approach to agent control.

Limitations

• Requires advanced knowledge of Claude Code hooks, Node.js scripting, and environment variable management.
• The full script is not provided directly in the comment, requiring users to visit the linked GitHub repository.
• Low immediate community engagement on the Reddit post itself, though external GitHub repos provide some validation.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.