Feature Request: Add Hook for Agent Plan Validation (`AgentPlanCreate`)

Title: Feature Request: Add Hook for Agent Plan Validation (AgentPlanCreate)

Body:

Is your feature request related to a problem? Please describe.

The current hooks system in Claude Code (PreToolUse, PostToolUse, etc.) is excellent for controlling individual tool calls. However, when using agentic workflows, particularly with sub-agents via the Task tool, there is no mechanism to inspect, validate, or log the agent's entire multi-step plan before it begins execution.

We can currently intercept individual actions (like a file edit or a bash command), but we can't see the full sequence of intended actions ahead of time. This makes it challenging to:

• Enforce high-level organizational policies on complex operations (e.g., requiring rollback steps for any deployment plan).
• Prevent undesirable sequences of actions before the first step is even taken.
• Gain observability for auditing and security purposes by logging the agent's complete intention before it acts.

Describe the solution you'd like

I propose the introduction of a new hook event: AgentPlanCreate.

This hook would be triggered at a critical point in an agent's lifecycle, primarily when a sub-agent is invoked via the Task tool.

• Trigger: Fires after a sub-agent generates a structured, multi-step plan, but before the first step of that plan is executed.

• Input Schema: The hook script would receive a JSON object via stdin. This object would contain standard hook context and a new plan key, providing full visibility into the agent's intentions.

``json
{
"session_id": "...",
"cwd": "...",
"agent_name": "database-migrator-agent", // The name of the agent creating the plan
"plan": [
{
"step_id": "step-1",
"description": "Back up the production database.",
"tool_name": "Bash",
"tool_input": { "command": "pg_dump > backup.sql" }
},
{
"step_id": "step-2",
"description": "Run the database migration script.",
"tool_name": "Bash",
"tool_input": { "command": "npm run migrate:prod" }
}
]
}
``

• Behavior: The hook could influence execution in multiple ways:
• Allow: An exit code of 0 allows the plan to proceed as intended.
• Block & Feedback: An exit code of 2 blocks the entire plan and feeds stderr back to the agent, allowing it to self-correct based on the feedback.
• Modify & Allow: A structured JSON output (e.g., {"decision": "allow", "updatedPlan": [...]}) could allow an altered version of the plan to proceed, enabling plan augmentation.

• Configuration: The hook would be configured in settings.json, using a matcher to apply policies to specific agents.

``json
{
"hooks": {
"AgentPlanCreate": [
{
"matcher": "deployment-agent", // Matcher targets the agent name
"hooks": [
{
"type": "command",
"command": "/path/to/my/deployment-plan-validator.sh"
}
]
}
]
}
}
``

Use Cases & Benefits

This feature would unlock critical capabilities for enterprise, security-conscious, and power users:

• Security & Safety: Prevent dangerous sequences of actions that are safe individually but risky together. For example, a hook could block a plan that reads a secret from a .env file and later stages all files with git add ., preventing accidental secret exposure.

• Code Quality & Best Practices: Enforce complex development policies at the plan level. For instance, a hook could reject any feature implementation plan that modifies application code without also including steps to create or update corresponding tests, thus enforcing Test-Driven Development.

• Cost & Resource Management: Act as a gateway for potentially expensive operations. A hook could analyze a plan's complexity (e.g., number of files to be modified) and block large-scale, automated refactoring tasks that might exceed token or cost budgets without manual approval.

• Workflow Automation & Augmentation: Automatically inject required steps into an agent's plan. For example, a hook could modify any deployment plan to automatically add steps for sending pre- and post-deployment notifications to a Slack channel.

• Observability & Auditing: Create an immutable audit trail for compliance. By logging the agent's full, intended plan before any action is taken, organizations can maintain a clear record of what the agent was attempting to do, not just the individual tools it successfully ran.

• Human-in-the-Loop Gating: Enable gated approvals for critical operations. A hook could detect a high-risk plan (e.g., one involving terraform apply on production) and pause execution until a human provides explicit approval via an external system like Slack or Jira.

Additional Context

This feature is a natural and powerful extension of the existing hooks system. It aligns perfectly with the agentic direction of Claude Code, as seen with the introduction of sub-agents, by providing a much-needed layer of control, visibility, and safety for complex, multi-step tasks.

Thank you for considering this feature. I believe it would significantly enhance the safety, controllability, and enterprise-readiness of Claude Code.