Avoid the Dangers of Settings Pollution in Subagents, Hooks, and Scripts

When building complex automations with Claude, it's crucial to understand that any settings defined for your main agent—including powerful hooks—are inherited by any sub-agents it creates. This can lead to a dangerous "worst-case scenario": a PostToolUse hook that calls Claude again can trigger an infinite recursive loop, spawning endless processes and potentially crashing your system and burning through your API tokens.

This lesson demonstrates this exact problem and provides a clear, effective solution. You'll learn how to break the recursive chain by using the --settings flag to provide your sub-agent with a separate, minimal configuration file that explicitly disables all hooks.

Workflow demonstrated in this lesson:

• Create a Recursive Hook: Set up a PostToolUse hook that calls a script, which in turn invokes another instance of Claude.
• Trigger the Infinite Loop: Run a simple command to trigger the hook and observe how it rapidly spawns new Claude processes.
• Introduce the --settings Flag: Modify the sub-agent call in the script to include a --settings flag pointing to a new configuration file (e.g., no-hooks.json).
• Disable Hooks for the Sub-agent: In the new settings file, add the "disableAllHooks": true property.
• Verify the Fix: Run the command again to confirm that the sub-agent uses the new settings, the hook is not triggered, and the infinite loop is prevented.

Key benefits:

• Understand Setting Inheritance: Learn how project settings are passed down to sub-agents.
• Prevent Dangerous Loops: Master the technique to stop recursive hooks and secure your automations.
• Gain Granular Control: Use separate settings files to give sub-agents different capabilities than the main agent.
• Build More Stable AI Agents: Ensure your complex workflows are safe, predictable, and efficient.

Summary

This lesson demonstrates a critical security consideration when working with Claude sub-agents: they inherit project-level settings, including hooks. This can create a dangerous infinite loop if a hook is configured to call Claude again. The video first showcases this "worst-case scenario" by setting up a PostToolUse hook that triggers a script, which in turn invokes a new Claude instance, leading to an uncontrollable cascade of processes. The solution presented is to use the --settings flag when calling the sub-agent from the script. This flag points to a separate configuration file (e.g., no-hooks.json) containing the property "disableAllHooks": true, which effectively breaks the recursive chain and prevents the infinite loop, securing the automation.

Prompts

Please check the git status.

Create a timestamped .txt file

Terminal Commands

pkill -f "claude"

claude

Code Snippets

The initial settings.local.json file configures a hook that will run after any tool is used, creating the potential for a recursive loop.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bun .claude/hooks/index.ts"
          }
        ]
      }
    ]
  }
}

The hook script (index.ts) itself calls Claude again, which inherits the hook settings and causes the infinite loop.

import { $ } from "bun";

await $`claude --print --model haiku "Check on the git status then write it out to a timestamped .txt file"`;

To fix this, the script is updated to pass a --settings flag, pointing to a file with no hooks.

import { $ } from "bun";

await $`claude --print --model haiku "Check on the git status then write it out to a timestamped .txt file" --settings no-hooks.json`;

The no-hooks.json file contains a single property to disable all hooks for the sub-agent, breaking the loop.

{
  "disableAllHooks": true
}