Authoritative session-finalization contract for audit and security integrations

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 exposes useful lifecycle hooks, tool events, permission events, and telemetry, but there does not appear to be an authoritative signal that a session has reached a fully finalized state.

In controlled testing on Claude Code 2.1.224, session-level hooks and repository outcomes could be observed successfully, but local provider/account-related state was still able to change after the apparent end of the session.

The problem is not detecting that state changed. The problem is determining:

• whether the change belongs to the completed session,
• whether additional asynchronous session-related work is still pending,
• when all relevant event producers have quiesced,
• and what signal can be treated as the authoritative boundary for sealing a session's evidence.

SessionEnd provides a lifecycle notification, and telemetry sequencing provides ordering, but neither appears to provide a documented guarantee that all session-scoped asynchronous work and security-relevant events are complete.

This makes it difficult for external audit, security, compliance, and observability integrations to know when a session's evidence can be considered complete rather than merely intact.

This observation is specific to Claude Code 2.1.224 and is not intended as a claim that current versions contain a security vulnerability. The request is for a documented, provider-supported session-finalization boundary.

Proposed Solution

Expose a documented, versioned session-finalization signal or API that fires only after all documented session-scoped activity has reached a terminal state.

Ideally it would provide:

• the stable session ID,
• the authoritative final telemetry/event sequence,
• the event schema version,
• an explicit indication that no documented session-scoped asynchronous work remains pending,
• and a clear definition of which state is included or excluded from the finalization boundary.

An optional digest or signed commitment over the final ordered security-relevant event set would also be valuable for high-assurance audit integrations.

The important requirement is not a particular implementation, but an authoritative way for an external integration to know: this session is finalized and this is the complete supported evidence boundary.

Alternative Solutions

I considered several existing mechanisms:

• SessionEnd: useful as a lifecycle notification, but does not appear to guarantee that all asynchronous session-related activity has finished.
• OpenTelemetry sequencing: provides ordering, but the largest sequence received does not prove that it is the final sequence.
• Waiting for local state to stop changing: a quiet period does not establish finality or attribution.
• Hashing/HMAC-binding state: proves integrity of observed data, but not whether asynchronous writers are finished.
• External filesystem/process/network observation: can establish local quiescence, but does not provide a provider-supported session-finality guarantee.

These mechanisms are useful together, but none appears to provide the authoritative completion boundary needed here.

Priority

Critical - Blocking my work

Feature Category

Developer tools/SDK

Use Case Example

1. An external audit or security integration observes a Claude Code session through hooks and OpenTelemetry while independently tracking repository, process, filesystem, and network activity.
2. The user completes the coding task, and Claude Code emits SessionEnd.
3. Before sealing the evidence, the integration must determine whether every supported session event and asynchronous operation has actually completed.
4. Currently, the integration cannot reliably distinguish a fully completed session from one that is only temporarily quiet. Additional events or state changes may still occur after the apparent session end.
5. With an authoritative session-finalization contract, Claude Code would provide the session identity, final event sequence, and confirmation that no documented session-scoped work remains pending.
6. The integration could then verify its collected evidence against that final boundary and either safely seal the session or fail closed when evidence is incomplete.

Additional Context

_No response_