claude-howto/openspec/changes/add-context-tracking-hooks/specs/hooks-documentation/spec.md

hooks-documentation Spec Delta

ADDED Requirements

Requirement: Pre-Message and Post-Response Hook Pairs Documentation

The hooks lesson SHALL document how to use UserPromptSubmit and Stop hooks together for context/token usage tracking.

Scenario: Understanding hook event timing for context tracking

• WHEN a user wants to track per-request token consumption
• THEN they find documentation explaining that UserPromptSubmit fires before the prompt is processed (pre-message)
• AND they find documentation explaining that Stop fires after Claude completes its response (post-response)
• AND they understand how to calculate the delta between these two points

Scenario: Token delta calculation methodology

• WHEN a user implements a context tracking hook pair
• THEN they find documentation explaining how to:
  • Record token count at UserPromptSubmit time
  • Calculate new token count at Stop time
  • Compute the delta representing per-request consumption

Requirement: Context Tracking Hook Pair Example

The hooks lesson SHALL provide a working example script that tracks context usage using pre-message and post-response hooks.

Scenario: Single script handles both hook events

• WHEN a user copies the context-tracker.py example
• THEN the script detects the hook event type via hook_event_name
• AND handles UserPromptSubmit by saving current token estimate to a temp file
• AND handles Stop by loading the saved count, calculating delta, and reporting usage

Scenario: Complete configuration for hook pair

• WHEN a user wants to configure both hooks
• THEN they find a complete settings.json example showing:
  • UserPromptSubmit hook configuration pointing to the context tracker script
  • Stop hook configuration pointing to the same script
  • Both hooks using the same script for consistent token calculation

Scenario: Per-request usage reporting

• WHEN the context tracking hooks execute
• THEN the Stop hook outputs a report showing:
  • Total estimated tokens used in session
  • Tokens consumed by the current request (delta)
  • Remaining capacity estimate

Requirement: Token Counting Methods Documentation

The hooks lesson SHALL document two offline token counting methods that require no API key.

Scenario: tiktoken-based token counting documented

• WHEN a user wants more accurate offline token counts
• THEN they find documentation for using tiktoken with p50k_base encoding
• AND they see a Python example using tiktoken.get_encoding("p50k_base")
• AND they understand it provides ~90-95% accuracy compared to Claude's tokenizer
• AND they learn it requires the tiktoken dependency

Scenario: Character estimation token counting documented

• WHEN a user wants zero-dependency token estimation
• THEN they find documentation for the ~4 characters per token estimation ratio
• AND they understand this provides ~80-90% accuracy for English text
• AND they learn it works with no external dependencies

Scenario: Method comparison provided

• WHEN a user needs to choose between token counting methods
• THEN they find a comparison showing:
  • tiktoken method: ~90-95% accuracy, requires tiktoken, <10ms latency
  • Estimation method: ~80-90% accuracy, no dependencies, <1ms latency
• AND both methods work completely offline without API keys

Scenario: Transcript contents explained

• WHEN a user wants to understand what's included in token counts
• THEN they find documentation explaining that the transcript includes:
  • User prompts
  • Claude's responses
  • Tool inputs and outputs
• AND they understand that system prompts and internal context are NOT included

Scenario: No official Claude tokenizer caveat

• WHEN a user reads about token counting accuracy
• THEN they understand that Anthropic hasn't released an official offline tokenizer
• AND they understand both methods are approximations based on similar BPE tokenizers

MODIFIED Requirements

Requirement: Context Usage Reporting Hook Example

The hooks lesson SHALL include a correct, working example showing how to create a hook that reports context/token usage after each Claude response.

Scenario: Token calculation is correct

• WHEN a user copies the context-usage.py example
• AND runs it as a Stop hook
• THEN the hook correctly calculates estimated tokens from total character count
• AND displays a non-zero token count proportional to conversation length

Scenario: User learns to create context monitoring hook

• WHEN a user reads the context usage reporter example
• THEN they find a complete Python script that reads the transcript file
• AND they understand how to estimate token usage from conversation history
• AND they see the configuration for Stop hooks
• AND they understand the limitations of token estimation

Scenario: Hook output format is documented

• WHEN a user implements the context usage hook
• THEN they can generate a one-line report showing used tokens and remaining capacity
• AND the output shows realistic token counts based on conversation size

Scenario: Delta-based tracking is documented

• WHEN a user wants per-request token consumption
• THEN they find documentation pointing to the pre-message/post-response hook pair approach
• AND they understand how to use UserPromptSubmit + Stop for delta calculation