[FEATURE] Add prompt_id to PostToolUse and PreToolUse hook payloads

Status Fixed / completed
Maintainer reply None cached
Activity 4 comments · opened Jun 5, 2026 · closed Jun 26, 2026

Preflight Checklist

  • [x] I have searched existing requests and this feature hasn't been requested yet
  • [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code already generates a prompt_id for every user prompt and emits it on OTel events
both claude_code.api_request and claude_code.tool_result carry it. However, prompt_id is
not present in the PostToolUse (or PreToolUse) hook JSON payload, which only exposes
session_id.

This creates an inconsistency: the PostToolUse hook fires at the same lifecycle moment as the
claude_code.tool_result OTel event, but the two outputs don't share a common key below
session_id. I imagine this value exists in the runtime at hook-fire time since it's being attached
to the concurrent OTel events.

Proposed Solution

Add prompt_id to the PostToolUse and PreToolUse hook JSON payloads alongside the existing
session_id. The change is additive and non-breaking.

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": { ... },
  "tool_response": { ... },
  "tool_use_id": "..."
}

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Other

Use Case Example

We're building a cost attribution pipeline to associate Claude Code API spend with
PRs and engineering initiatives. The architecture joins two BigQuery pipelines:

  • Hooks pipeline captures which files were modified by which Claude session, via

PostToolUse hooks writing (session_id, file_path) tuples at edit time and reconciling
against committed files at push time.

  • OTel pipeline captures token counts and cost_usd per prompt_id from

claude_code.api_request events.

These pipelines currently can only join at session_id grain, which is too coarse since a session
spans hours and dozens of prompts, only some of which are relevant to any given commit. With
prompt_id in the hook payload, we can join at prompt grain and produce accurate per-PR and
per-initiative cost attribution.

Additional Context

_No response_

View original on GitHub ↗

4 Comments

mikeschinkel · 4 months ago

@marcusgreer — This would be very helpful for my use-cases too.

Necmttn · 3 months ago

prompt_id is the right join key, but I would add two constraints.

First, it should be the same value as the OTel event fired for the same lifecycle moment. Second, it should be preserved for subagent hook payloads too. For nested Agent calls, include parent_tool_use_id or an agent path if the runtime has it.

It is also better to emit null / unknown explicitly than omit the field, so ingestion pipelines can distinguish older clients from missing data.

---

_Generated with ax._

marcusgreer · 3 months ago

This was closed as completed, but I can't find the prompt_id field in the shipped hook payloads. Could someone point me to the version or PR where this landed? Happy to re-verify if it shipped behind a flag or under a different field name. Otherwise it looks like the closure may not match the shipped CLI.

github-actions[bot] · 1 month ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.