Feature Request: Expand Hooks to Cover the Full Agent Lifecycle

Title: Feature Request: Expand Hooks to Cover the Full Agent Lifecycle

Labels: enhancement, feature-request, hooks, automation, observability

Overview

Claude Code hooks are a powerful feature for observing and controlling tool execution. However, their current scope is primarily focused on the moments just before and after a tool is used (PreToolUse, PostToolUse).

To build truly robust, observable, and automated agentic systems, developers need visibility and control over the entire agent lifecycle. This proposal outlines the introduction of new hook events that fire at critical stages beyond simple tool execution, such as planning, failure, and session management.

The Problem: Limited Visibility into Agent State

The current hook events provide no insight into higher-level agent actions. Key "blind spots" include:

• Planning: We can't inspect or validate the agent's plan before it begins a complex task.
• Failure Handling: There is no specific event for when a tool fails, making it difficult to implement custom, context-aware recovery logic.
• Session State: There is no way to automatically run setup and teardown logic at the beginning and end of a user's session.

This lack of visibility makes it challenging to build advanced automation, monitoring, and enterprise-grade guardrails around Claude Code.

Proposed Solution

Introduce a set of new, granular hook events to cover more of the agent's lifecycle.

1. AgentPlanCreate

• Trigger: Fires after Claude generates a multi-step plan (e.g., within a Task tool call) but before execution begins.
• Input: The structured plan generated by the model.
• Use Case:
• Policy Enforcement: A hook could validate a plan against project policies, such as "all database changes must have a corresponding rollback plan," and block it if non-compliant.
• Observability: Log the agent's intended plan to a monitoring or audit system before it takes any action.

2. ToolUseFailure

• Trigger: Fires specifically when a tool call fails (e.g., non-zero exit code, API error, timeout). This is more specific than PostToolUse, which fires only on success.
• Input: The tool name, original input, and detailed error context (e.g., stdout, stderr, exit code).
• Use Case:
• Custom Retry Logic: If an npm install command fails due to a corporate proxy error, a hook could detect this specific error and provide Claude with precise instructions and environment variables to configure the proxy and attempt the installation again.
• Automated Bug Reporting: On failure, a hook could automatically create a ticket in a system like Jira with all the relevant error context.

3. SessionStart and SessionEnd

• Trigger:
• SessionStart: Fires at the beginning of a claude interactive session.
• SessionEnd: Fires just before the session exits cleanly.
• Use Case:
• Environment Management: A SessionStart hook could automatically spin up a temporary database or development server. The corresponding SessionEnd hook could tear it down, ensuring a clean state.
• Metrics and Cleanup: A SessionEnd hook could be used to clean up temporary files, log session duration, and push final session metrics to an observability platform.

Benefits

• Proactive Guardrails: Validate and control agentic plans before they are executed.
• Intelligent Failure Recovery: Move beyond simple failure notifications to implement sophisticated, context-aware retry and recovery mechanisms.
• Full Lifecycle Automation: Automate the setup, teardown, and monitoring of the entire development session, making Claude Code more seamless to integrate into complex environments.
• Enhanced Observability: Gain deep insights into every stage of the agent's operation, from planning to execution and completion, which is critical for debugging and auditing in enterprise settings.

Conclusion

Expanding the hook system to cover the full agent lifecycle is a crucial step for building advanced, reliable, and secure applications with Claude Code. These new events would provide developers with the granular control needed to deploy agentic workflows with confidence, particularly in automated and enterprise environments.