claude_hooks 0.2.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08b8b23bcfdeed5cf98e3477b6339f29488d6e547fd2fb10ef40947bbc3d45dc'
-  data.tar.gz: 20d0f599bac9dcde566829dabba1d1f3f13756181ed4ea7bbe4cfa1c0a95838a
+  metadata.gz: d82c5deaa5426bc2ca898300f7772fa58c56a2998fd00af4eb1a93de25d3336e
+  data.tar.gz: ffde711d996ad0f43f7f75a3002f5a1e74e84f28ed2197ddf9c53c8b982a5152
 SHA512:
-  metadata.gz: 7cd6ecea85c72ce39e77613f68c3dc9f689aca7611dd499482e20538bbb456e2c6b4c23bc791372173fd4b955e8d4211c3c8c29e0e97957812916f901327ce22
-  data.tar.gz: 93b6032c1c29c11081419d0415dae8ac5cd2494fa558af1637c081ce11d256403c1b26c49740c9aa8294c385aa311b12da2b3e5a6949e88a4a5f892b68abcf54
+  metadata.gz: 8256eeed53e717873271ea94b9d85610e741ade7d6009b41a9df6eccc8ea58ec4af3b4ab8883d8dfba3d0ef849afdcae6939786d7cb7ad4d000dd7dc749a73ab
+  data.tar.gz: 306144f71bd099d70df514ee21eb9e63a11389562322927465b1aecff447c78eaafc602aa973db8a925bf0885c4e212fbcbfacb410c6d34c30a7b56eb9e51145

data/CHANGELOG.md

@@ -5,6 +5,143 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2] - 2026-01-04
+
+### Fixed
+
+- **Critical: Fixed hook output contract for JSON API** - Stop, PostToolUse, UserPromptSubmit, and PreToolUse hooks now correctly use stdout + exit 0 when outputting structured JSON
+  - Stop hooks now output to stdout with exit 0 instead of stderr with exit 2 (PR #15, fixes #11)
+  - PostToolUse hooks now use stdout + exit 0 for JSON API consistency
+  - UserPromptSubmit hooks now use stdout + exit 0 for JSON API consistency
+  - PreToolUse hooks now use exit 0 for all permission decisions (previously varied: 0 for allow, 1 for ask, 2 for deny)
+  - This aligns with Anthropic's official guidance: when using advanced JSON API with decision/reason fields, hooks must output to stdout with exit 0
+  - **Breaking behavior fixed**: Plugin hooks with `continue_with_instructions!` now work correctly
+  - Reference: https://github.com/anthropics/claude-code/issues/10875
+  - Reference: https://github.com/gabriel-dehan/claude_hooks/issues/11
+
+### Notes
+
+- All tests updated and passing (147 runs, 262 assertions, 0 failures)
+- This fix ensures compatibility with Claude Code's plugin system
+- The exit code 2 + stderr approach is only for simple text output without JSON structure
+
+## [1.0.1] - 2025-10-13
+
+### Documentation
+
+- **Added comprehensive plugin hooks documentation** - Full guide on using the Claude Hooks DSL with Claude Code plugins
+  - New "Plugin Hooks Support" section in README with working examples
+  - Created `example_dotclaude/plugins/README.md` with complete plugin development guide
+  - Example plugin formatter implementation using the DSL
+  - Environment variables documentation for plugin development
+  - Best practices and testing instructions for plugin hooks
+- **Updated SessionStart hook documentation** - Added the new `compact` matcher introduced in official Claude Hooks documentation
+  - Updated `docs/API/SESSION_START.md` to include `'compact'` as a valid source value
+  - Updated SessionStart hook type description to mention compact functionality
+- **Synchronized with official documentation** - All documentation now matches the official Claude Hooks reference as of 2025-10-13
+  - Plugin hooks feature (Issue #9)
+  - SessionStart `compact` matcher (Issue #2)
+
+### Notes
+
+- No code changes required - the implementation already supports all documented features
+- The DSL's dynamic implementation handles the new `compact` source automatically
+- Plugin environment variables (`CLAUDE_PLUGIN_ROOT`) work seamlessly with existing configuration system
+
+## [1.0.0] - 2025-08-27
+
+> [!WARNING]
+> These changes are not backward compatible (hence the version bump to 1.0.0), the API has changed too much.
+
+Follow the [migration guide](docs/1.0.0_MIGRATION_GUIDE.md) to migrate to the new API.
+
+### Changed
+
+#### Revamped documentation
+
+- **New documentation structure**:
+  - **API Reference**: Comprehensive API reference for all hook types
+  - **Common Helpers**: Shared helpers for all hook types
+  - **Output Helpers**: Helpers for working with the output state
+  - **Hook Exit Codes**: Exit codes for each hook type
+  - **Hook Types**: Overview of all hook types and their purpose
+
+#### Added support for SessionEnd
+Handles the new `SessionEnd` hook type.
+
+#### Handles new field for PostToolUse
+`additionalContext` field is now available in the `hookSpecificOutput` field.
+
+#### Output Objects System
+New output handling with intelligent exit code management.
+
+- **Automatic Exit Code Selection**: Output objects automatically choose the correct exit code (0, 1, 2) based on hook type and the state of the hook
+- - **Enhanced Base Class**: All hook instances now automatically get an `@output` attribute with a `output` accessor. They can still access raw `output_data`
+- **Helper Methods**: Access to hook-specific data via methods like `output.blocked?`, `output.allowed?`, `output.should_ask_permission?`
+- **Automatic Stream Selection**: Output objects automatically route to `STDOUT` or `STDERR` based on exit code and hook type
+- **One-Line Output Execution**: New `output_and_exit` method handles JSON serialization, stream selection, and exit code in one call
+- **Object-Based Merging**: New `ClaudeHooks::Output::*.merge()` methods for cleaner multi-hook merging
+- **Comprehensive Output Classes**: Full coverage for all 8 hook types:
+  - `ClaudeHooks::Output::UserPromptSubmit` - Provides `blocked?`, `reason`, `additional_context`
+  - `ClaudeHooks::Output::PreToolUse` - Provides `allowed?`, `denied?`, `should_ask_permission?`
+  - `ClaudeHooks::Output::PostToolUse` - Provides `blocked?`, `reason`
+  - `ClaudeHooks::Output::Stop` - Provides `should_continue?`, `continue_instructions` (inverted logic)
+  - `ClaudeHooks::Output::SubagentStop` - Inherits Stop behavior
+  - `ClaudeHooks::Output::Notification` - Basic output handling
+  - `ClaudeHooks::Output::SessionStart` - Provides `additional_context`
+  - `ClaudeHooks::Output::PreCompact` - Basic output handling
+
+##### Migration Guide
+
+**Before (Old Pattern):**
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+begin
+  input_data = JSON.parse(STDIN.read)
+  hook = MyHook.new(input_data)
+  result = hook.call
+
+  # Manual stream and exit code selection
+  if result['continue'] != false
+    if result.dig('hookSpecificOutput', 'permissionDecision') == 'deny'
+      STDERR.puts hook.stringify_output
+      exit 1
+    elsif result.dig('hookSpecificOutput', 'permissionDecision') == 'ask'
+      STDERR.puts hook.stringify_output
+      exit 2
+    else
+      puts hook.stringify_output
+      exit 0
+    end
+  else # Continue == false
+    STDERR.puts hook.stringify_output
+    exit 2
+  end
+rescue StandardError => e
+  # Error handling...
+end
+```
+
+**After (New Pattern):**
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+# Just 3 lines for most cases!
+begin
+  input_data = JSON.parse(STDIN.read)
+  hook = MyHook.new(input_data)
+  hook.call
+
+  # Handles everything automatically!
+  hook.output_and_exit
+rescue StandardError => e
+  # Error handling...
+end
+```
+
 ## [0.2.1] - 2025-08-21
 
 ### Fixed