Feature Request: Support for Asynchronous ("Fire-and-Forget") Hooks

Resolved 💬 3 comments Opened Jul 25, 2025 by coygeek Closed Jan 4, 2026

Title: Feature Request: Support for Asynchronous ("Fire-and-Forget") Hooks

Area: Hooks, Performance

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

Currently, all Claude Code hooks are executed synchronously. As described in the documentation (en/docs/claude-code/hooks.md under "Hook Execution Details"), Claude Code blocks and waits for each hook to complete before proceeding.

This synchronous execution model adds unnecessary latency for hooks that perform non-critical, out-of-band actions where the result is not needed to continue the main agent flow. For example, hooks used for logging, metrics, or notifications can slow down the user's interaction with Claude, impacting the tool's perceived performance and responsiveness.

Describe the solution you'd like

I propose adding a new boolean property to the individual hook configuration, such as "background": true or "waitForCompletion": false.

When this property is set to true (or waitForCompletion is false), Claude Code would spawn the hook's command as a detached background process and immediately continue its own execution without waiting for the hook's exit code or output. This would enable a "fire-and-forget" pattern for specific hooks.

Proposed Configuration Change

Based on the current hook configuration documented in en/docs/claude-code/hooks.md, the new property could be added as follows:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/log-write-event.sh",
            "background": true, // <-- Proposed new property
            "timeout": 30 // Timeout could still apply to the detached process for cleanup
          }
        ]
      }
    ]
  }
}

Describe alternatives you've considered

The current synchronous model is the only available option. The alternative is to not use hooks for these out-of-band tasks, which means losing valuable integration points for monitoring, auditing, and automation. There is no current workaround to achieve this asynchronous behavior.

Additional context & Rationale

This feature would significantly improve the performance and user experience by enabling a non-blocking pattern for hooks. It's ideal for tasks that shouldn't slow down the core user-agent interaction.

Primary Use Cases:

  • Telemetry & Metrics: Emitting metrics to an observability platform (e.g., OpenTelemetry) without delaying the next turn.
  • Asynchronous Notifications: Sending a Slack or Microsoft Teams notification about a specific event (e.g., a critical file being modified) without making the user wait.
  • Remote Logging: Logging tool usage or specific events to a remote service for auditing or analytics purposes.

By decoupling the agent's critical path from these peripheral operations, the entire system would feel faster and more responsive. This is particularly valuable in enterprise environments with numerous hooks or slow, network-dependent hook scripts.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗