🪝 [P1] Full Lifecycle Hooks (session, turn, tool error, compaction)

Feature: Full Lifecycle Hooks System

Parent epic: #20 (Feature Parity with Python SDK)

Current State (v0.4.3)

We have 4 hooks + generic events in lib/antigravity/hooks.rb:

hooks.before_prompt { |text| ... }        # pre-turn
hooks.after_response { |msg| ... }        # post-turn
hooks.before_tool_call { |name, params| :allow / :deny }
hooks.after_tool_call { |name, params, result| modified_result }
hooks.on(:ws_message) { |msg| ... }       # generic events (Ruby-only!)

Target: Full Python SDK Parity

Proposed Ruby API

agent = Antigravity::Agent.new do |a|
  # Session lifecycle
  a.on_session_start { |session| puts "Session #{session.conversation_id} started" }
  a.on_session_end { |session| puts "#{session.turn_count} turns, #{session.total_tokens} tokens" }

  # Turn lifecycle
  a.before_prompt { |text| puts ">>> #{text}" }        # existing
  a.after_response { |msg| puts "<<< #{msg.content}" } # existing

  # Tool lifecycle
  a.before_tool_call { |name, params| :allow }   # existing
  a.after_tool_call { |name, params, result| }    # existing
  a.on_tool_error { |name, params, error| "Fallback: #{error.message}" }  # NEW

  # Context management
  a.on_compaction { |info| puts "Context compacted at turn #{info[:turn]}" }  # NEW
end

Rails-Friendly Defaults 🛤️

When RAILS_ENV or RACK_ENV is set to test, auto-attach verbose hooks:

# In lib/antigravity/hooks/test_defaults.rb
module Antigravity::Hooks::TestDefaults
  def self.attach!(agent)
    agent.on_session_start { |s| puts "[TEST] 🟢 Session started: #{s.conversation_id}" }
    agent.on_session_end   { |s| puts "[TEST] 🔴 Session ended: #{s.turn_count} turns" }
    agent.before_prompt    { |t| puts "[TEST] ➡️  Prompt: #{t[0..80]}..." }
    agent.after_response   { |m| puts "[TEST] ⬅️  Response: #{m.content[0..80]}..." }
    agent.before_tool_call { |n, p| puts "[TEST] 🔧 Tool: #{n}(#{p.keys.join(", ")})"; :allow }
    agent.on_tool_error    { |n, _, e| puts "[TEST] 💥 Tool #{n} failed: #{e.message}" }
  end
end

# Auto-attach in test/development:
Antigravity.configure do |c|
  c.test_hooks = true  # or auto-detect from RAILS_ENV
end

Deliverables

• Add on_session_start, on_session_end hooks (fire in connect! / close!)
• Add on_tool_error hook (fire in client.rb rescue block, allow recovery)
• Add on_compaction hook (detect compaction events from WebSocket)
• Add Hooks::TestDefaults module with verbose logging
• Auto-attach test hooks when ENV["RAILS_ENV"] == "test" or ENV["ANTIGRAVITY_DEBUG"]
• Example 11_e2e_lifecycle_hooks.rb demonstrating all hooks
• Keep backward compat: before_prompt / after_response still work (aliases)
• Update docs/FEATURE_PARITY.md

Priority

P1 -- hooks are the extensibility backbone. Policy engine (#21) and MCP will build on top of this.

Start with lib/antigravity/hooks.rb, then trace connect! and close! for session events and the rescue block in client.rb for tool errors. Review WebSocket event handling for compaction, and the proposed lib/antigravity/hooks/test_defaults.rb structure. Done means all listed hooks and aliases work, test defaults attach under the stated environments, the example runs, and docs/FEATURE_PARITY.md is updated.