Feature Request: Invoke Subagents from Hooks for Deterministic Workflows

Title: Feature Request: Invoke Subagents from Hooks for Deterministic Workflows

Labels: enhancement, feature-request, hooks, subagents

Is this a bug report or a feature request?

This is a feature request.

Problem Description

The current implementation of Subagents and Hooks is incredibly powerful, but they operate largely independently. Subagent invocation relies on either:

1. Heuristic Delegation: The main agent decides to delegate a task to a subagent based on the user's prompt and the subagent's description.
2. Manual Invocation: The user explicitly requests a specific subagent (e.g., > Use the code-reviewer subagent...).

While this is excellent for interactive sessions, it lacks a mechanism for deterministic, automated invocation. There is no way to configure a workflow where a specific subagent is guaranteed to run in response to a specific event (e.g., automatically running a code-reviewer subagent every time a file is modified).

Proposed Solution

Extend the Hooks system to support invoking a subagent as a hook action. This would bridge the gap between deterministic automation (Hooks) and specialized reasoning (Subagents).

A new hook type could be introduced in the settings.json configuration. For example:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Code modified, triggering review...'"
          },
          {
            "type": "subagent",
            "name": "code-reviewer",
            "prompt": "A file was just modified. Please review the changes for quality, style, and potential bugs." 
          }
        ]
      }
    ]
  }
}

Key components of this proposal:

• type: "subagent": A new hook action type.
• name: "subagent-name": The name of the subagent to invoke (e.g., code-reviewer).
• prompt (optional): A prompt to pass to the subagent, giving it context about why it was invoked by the hook. The subagent would then execute its task within its own isolated context, as it does now.

Use Cases and Rationale

This feature would unlock powerful, enforceable automation workflows:

1. Automated Code Quality Gates: After any Edit, MultiEdit, or Write tool call, a PostToolUse hook could trigger a code-reviewer subagent to immediately check the changes against project standards.
2. Enforced Security Scans: A hook on git commit or Edit could invoke a security-scanner subagent to analyze new code for vulnerabilities before it's even committed.
3. Automatic Test Execution: After new code is written, a hook could trigger a test-runner subagent to locate and run the relevant tests, then attempt to fix them if they fail.
4. Living Documentation: A PostToolUse hook on a tool like git commit could trigger a doc-writer subagent to update the README.md, CHANGELOG.md, or other relevant documentation based on the commit's changes.

By making subagent invocation a deterministic action, you enable developers and organizations to build robust, automated guardrails and helpers directly into their development lifecycle with Claude Code.

Impact on Documentation

This feature would require updates to the following documentation pages to describe the new functionality and provide examples:

• en/docs/claude-code/hooks.md
• en/docs/claude-code/hooks-guide.md
• en/docs/claude-code/sub-agents.md