Feature Request: Enable Hooks to Suggest Follow-up Tool Calls for Deterministic Tool Chaining

Title: Feature Request: Enable Hooks to Suggest Follow-up Tool Calls for Deterministic Tool Chaining

Labels: enhancement, feature-request, hooks, agentic-workflows

Overview

This is a feature request to significantly enhance the Claude Code hooks system by allowing a hook's JSON output to include a suggestedToolCalls field. This would enable hooks to deterministically suggest one or more subsequent tool calls, creating a powerful mechanism for building automated, reliable, and composable agentic workflows.

The Problem & Motivation

The current hooks system is excellent for reacting to events. A PostToolUse hook can automatically format a file after an Edit tool call, and a PreToolUse hook can validate inputs or block unsafe commands. This reactive capability is a cornerstone of Claude Code's power.

However, the current system is limited to reacting. To create a deterministic chain of actions (e.g., Edit -> Format -> Lint -> Test), developers must rely on one of the following methods:

1. Complex Prompting: Instructing the model in the main conversation to perform all steps. This is non-deterministic, as the model may get distracted, forget a step, or misunderstand the required sequence.
2. Manual Chaining: The user must manually issue each subsequent command, which defeats the purpose of automation and adds cognitive load.
3. Indirect Workarounds: Using Stop hooks to inspect the last action and inject a new prompt is a brittle and unintuitive way to achieve this.

There is no direct, reliable mechanism for a hook to say, "This action is complete; now here is the logical next action you should take." This limits the ability to encode complex, project-specific workflows directly into the tool.

Proposed Solution

I propose extending the advanced JSON output schema for hooks to include a new optional field, suggestedToolCalls.

This field would contain an array of tool call objects. When the Claude Code agent loop processes a hook's output and finds this field, it would treat the suggested calls as if the model had generated them. They would be added to the agent's plan and be subject to the standard permission and execution flow, including user approval prompts.

Proposed JSON Output Structure:

{
  "continue": true,
  "suppressOutput": true,
  "suggestedToolCalls": [
    {
      "tool_name": "Bash",
      "tool_input": {
        "command": "npm run lint -- --fix path/to/file.ts",
        "description": "Run the linter on the recently formatted file."
      }
    }
  ]
}

This feature would primarily be used in PostToolUse hooks but could be applicable to other hook events as well.

Detailed Use Case: Automated Format-and-Lint Workflow

This canonical example illustrates the feature's power:

1. User Prompt: > Refactor the login function in auth.ts to be more efficient.
2. Agent Action: Claude uses the Edit tool to modify auth.ts.
3. Hook Trigger: A PostToolUse hook, configured to match Edit calls on *.ts files, is triggered.
4. Hook Action: The hook's script runs a code formatter (e.g., npx prettier --write auth.ts) and exits successfully.
5. New Behavior (Hook Output): The hook script returns the JSON payload above, suggesting a Bash tool call to run the linter.
6. Agent Response: The agent loop processes the hook output, sees the suggestion, and presents the Bash("npm run lint ...") tool call to the user for approval.
7. Result: A complete, reliable Edit -> Format -> Lint workflow is executed from a single high-level prompt, without requiring further user intervention or relying on the model's non-deterministic memory.

Describe alternatives you've considered

1. Enhanced Prompt Engineering: One could meticulously prompt the model to perform the entire sequence of actions ("First, edit the file. Second, run the formatter. Third, run the linter.").

• Why it's insufficient: This approach is not deterministic and places a high cognitive load on the user. The model can forget steps, execute them in the wrong order, or get sidetracked, making it unreliable for consistent, complex workflows.

1. Using Stop Hooks: A Stop hook could be engineered to inspect the last action in the transcript and, if it matches a certain condition (e.g., an Edit tool call), return a new prompt to the model to trigger the next action.

• Why it's insufficient: This is a very indirect and brittle workaround. The Stop hook is not directly tied to the successful completion of a specific tool but to the end of the entire agent turn. This makes the logic complex, hard to configure correctly, and less intuitive than a direct, event-driven suggestion.

1. Chaining /slash Commands: The user could manually chain custom slash commands, for example, /format-file <file> followed by /lint-file <file>.

• Why it's insufficient: This requires manual intervention at each step and is not a true, automated workflow triggered by a single event. It breaks the "fire-and-forget" nature of an agentic task.

Benefits

• Determinism & Reliability: Moves predictable workflow logic from probabilistic LLM prompting into deterministic hook configuration, making agent behavior far more reliable.
• Powerful Automation & Composability: Allows developers to compose simple, single-purpose hooks into complex, multi-step agentic behaviors.
• Improved User Experience: The next logical step is automatically presented to the user for simple approval, reducing cognitive load and manual typing.
• Enhanced Extensibility: Transforms the hook system from a purely reactive mechanism into a proactive automation framework, allowing developers to deeply customize Claude Code to their project's needs.
• Reduced LLM Reliance: Offloads simple, sequential logic from the model, potentially saving tokens and reducing the chance of the agent getting sidetracked on common workflows.

Implementation and Security Considerations

• Permissions: All suggested tool calls must be subject to the existing permission system (/permissions, --allowedTools, user approval prompts) to maintain security.
• UI/UX: For transparency, the UI should indicate that a tool call was suggested by a hook (e.g., [Hook] Suggested running: npm run lint).
• Multiple Suggestions: A clear rule should be defined for handling suggestedToolCalls from multiple hooks firing on the same event (e.g., queuing them in order).

This feature would be a major leap forward in enabling more complex, reliable, and powerful agentic coding workflows with Claude Code. Thank you for considering this proposal.