claude_agent 0.7.15 → 0.7.16

data/lib/claude_agent/session.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  # Historical session finder with Rails-like API.
+  # Historical session finder with Rails-like API and Stripe-style resource methods.
   #
-  # Wraps SessionInfo with a rich interface for finding sessions
-  # and querying their message transcripts.
+  # Wraps SessionInfo with a rich interface for finding sessions,
+  # querying their message transcripts, and mutating session metadata.
   #
   # @example Find a session by ID
   #   session = ClaudeAgent::Session.find("abc-123")
   #   session.summary  # => "Fix login bug"
   #
-  # @example List all sessions
-  #   sessions = ClaudeAgent::Session.all(limit: 10)
+  # @example Retrieve (raises on not found)
+  #   session = ClaudeAgent::Session.retrieve("abc-123")
   #
-  # @example Query messages with chainable relation
-  #   session.messages.where(limit: 5).each { |m| puts m.type }
+  # @example Mutations
+  #   session.rename("My Session")
+  #   session.tag("important")
+  #   forked = session.fork(title: "Branch off")
+  #
+  # @example Resume a conversation
+  #   session.resume(model: "opus") { |c| c.say("Continue") }
   #
   class Session
     attr_reader :session_id, :summary, :last_modified, :file_size,
-                :custom_title, :first_prompt, :git_branch, :cwd
+                :custom_title, :first_prompt, :git_branch, :cwd,
+                :tag, :created_at
 
     def initialize(session_info)
       @session_id = session_info.session_id
@@ -29,6 +35,8 @@ module ClaudeAgent
       @first_prompt = session_info.first_prompt
       @git_branch = session_info.git_branch
       @cwd = session_info.cwd
+      @tag = session_info.tag
+      @created_at = session_info.created_at
       @dir = session_info.cwd
     end
 
@@ -39,18 +47,99 @@ module ClaudeAgent
       SessionMessageRelation.new(session_id, dir: @dir)
     end
 
+    # --- Instance Mutation Methods ---
+
+    # Rename this session.
+    #
+    # @param title [String] New title
+    # @return [self]
+    def rename(title)
+      SessionMutations.rename_session(session_id, title, dir: @dir)
+      @custom_title = title
+      self
+    end
+
+    # Tag this session.
+    #
+    # @param value [String, nil] Tag value. Pass nil to clear.
+    # @return [self]
+    def tag_session(value)
+      SessionMutations.tag_session(session_id, value, dir: @dir)
+      @tag = value
+      self
+    end
+
+    # Fork this session.
+    #
+    # @param up_to [String, nil] Truncate at this message UUID (inclusive)
+    # @param title [String, nil] Title for the forked session
+    # @return [Session] The new forked session
+    def fork(up_to: nil, title: nil)
+      result = ForkSession.call(session_id, up_to_message_id: up_to, title: title, dir: @dir)
+      info = GetSessionInfo.call(result.session_id, dir: @dir)
+      info ? Session.new(info) : Session.new(SessionInfo.new(
+        session_id: result.session_id,
+        summary: title || @summary,
+        last_modified: Time.now.to_i * 1000,
+        file_size: 0
+      ))
+    end
+
+    # Re-read session metadata from disk.
+    #
+    # @return [self]
+    def reload
+      info = GetSessionInfo.call(session_id, dir: @dir)
+      raise NotFoundError, "Session not found: #{session_id}" unless info
+
+      @summary = info.summary
+      @last_modified = info.last_modified
+      @file_size = info.file_size
+      @custom_title = info.custom_title
+      @first_prompt = info.first_prompt
+      @git_branch = info.git_branch
+      @cwd = info.cwd
+      @tag = info.tag
+      @created_at = info.created_at
+      self
+    end
+
+    # Resume this session as a Conversation.
+    #
+    # @param kwargs Options/Conversation keyword arguments
+    # @yield [Conversation] Block form with auto-cleanup
+    # @return [Conversation, Object]
+    def resume(**kwargs, &block)
+      if block
+        Conversation.open(resume: session_id, **kwargs, &block)
+      else
+        Conversation.resume(session_id, **kwargs)
+      end
+    end
+
     class << self
-      # Find a session by its UUID.
+      # Find a session by its UUID (targeted lookup, not full scan).
       #
       # @param session_id [String] UUID of the session
       # @param dir [String, nil] Directory to scope the search
       # @return [Session, nil] The session, or nil if not found
       def find(session_id, dir: nil)
-        sessions = ListSessions.call(dir: dir)
-        info = sessions.find { |s| s.session_id == session_id }
+        info = GetSessionInfo.call(session_id, dir: dir)
         info ? new(info) : nil
       end
 
+      # Retrieve a session by UUID. Raises if not found (Stripe convention).
+      #
+      # @param session_id [String] UUID of the session
+      # @param dir [String, nil] Directory to scope the search
+      # @return [Session]
+      # @raise [NotFoundError] If session is not found
+      def retrieve(session_id, dir: nil)
+        info = GetSessionInfo.call(session_id, dir: dir)
+        raise NotFoundError, "Session not found: #{session_id}" unless info
+        new(info)
+      end
+
       # List all sessions.
       #
       # @return [Array<Session>]

data/lib/claude_agent/session_paths.rb

@@ -93,9 +93,12 @@ module ClaudeAgent
     # @param path [String]
     # @return [String]
     def realpath(path)
-      File.realpath(path).unicode_normalize(:nfc)
+      resolved = File.realpath(path)
+      resolved = resolved.encode("UTF-8") unless resolved.encoding == Encoding::UTF_8
+      resolved.unicode_normalize(:nfc)
     rescue SystemCallError
-      path.unicode_normalize(:nfc)
+      safe = path.encode("UTF-8") rescue path
+      safe.unicode_normalize(:nfc) rescue safe
     end
 
     # Get git worktree paths for a directory.

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.7.15"
+  VERSION = "0.7.16"
 end

data/lib/claude_agent.rb

@@ -13,6 +13,9 @@ require_relative "claude_agent/spawn"              # Custom spawn support (TypeS
 require_relative "claude_agent/options"
 require_relative "claude_agent/content_blocks"
 require_relative "claude_agent/messages"
+require_relative "claude_agent/message"              # Shared interface module for all message/block types
+require_relative "claude_agent/permission_policy"    # Declarative permission DSL
+require_relative "claude_agent/hook_registry"        # Declarative hooks DSL
 require_relative "claude_agent/message_parser"
 require_relative "claude_agent/hooks"
 require_relative "claude_agent/permissions"
@@ -40,10 +43,135 @@ require_relative "claude_agent/session_mutations"          # Session rename/tag
 require_relative "claude_agent/get_session_info"           # Single session lookup
 require_relative "claude_agent/fork_session"               # Session forking (TypeScript SDK v0.2.76 parity)
 require_relative "claude_agent/v2_session"                  # V2 Session API (unstable)
+require_relative "claude_agent/configuration"                # Stripe-style global config
 require_relative "claude_agent/session"                    # Session finder
 
 module ClaudeAgent
+  require "forwardable"
+
+  @config = Configuration.setup
+
   class << self
+    extend Forwardable
+    attr_reader :config
+
+    # --- Tier 1 delegators (set once at boot) ---
+
+    def_delegators :@config, :model, :model=,
+                             :permission_mode, :permission_mode=,
+                             :max_turns, :max_turns=,
+                             :max_budget_usd, :max_budget_usd=,
+                             :system_prompt, :system_prompt=,
+                             :append_system_prompt, :append_system_prompt=,
+                             :cli_path, :cli_path=,
+                             :cwd, :cwd=,
+                             :sandbox, :sandbox=,
+                             :debug, :debug=,
+                             :effort, :effort=,
+                             :persist_session, :persist_session=,
+                             :fallback_model, :fallback_model=
+
+    # Block-based bulk configuration.
+    #
+    # @example
+    #   ClaudeAgent.configure do |c|
+    #     c.model = "opus"
+    #     c.max_turns = 10
+    #   end
+    #
+    # @yield [Configuration]
+    # @return [void]
+    def configure
+      yield @config
+    end
+
+    # Reset configuration to defaults.
+    # @return [Configuration]
+    def reset_config!
+      @config = Configuration.setup
+    end
+
+    # --- Primary entry points ---
+
+    # One-shot query — the simple path returns a TurnResult.
+    #
+    # @param prompt [String] The prompt to send to Claude
+    # @param options [Options, nil] Pre-built Options (bypasses Configuration merge)
+    # @param kwargs Overrides merged with Configuration defaults
+    # @yield [Message] Each message as it streams in (optional)
+    # @return [TurnResult]
+    #
+    # @example Simple
+    #   turn = ClaudeAgent.ask("What is 2+2?")
+    #   puts turn.text
+    #
+    # @example With overrides
+    #   turn = ClaudeAgent.ask("Fix the bug", model: "opus", max_turns: 5)
+    #
+    # @example With streaming
+    #   turn = ClaudeAgent.ask("Explain Ruby") { |msg| print msg.text_content }
+    #
+    def ask(prompt, options: nil, **kwargs, &block)
+      callbacks, config_overrides = extract_callbacks(kwargs)
+
+      opts = options || @config.to_options(**config_overrides)
+      events = build_events(callbacks)
+
+      query_turn(prompt: prompt, options: opts, events: events, &block)
+    end
+
+    # Multi-turn conversation — block form auto-cleans, no block returns Conversation.
+    #
+    # @param kwargs Overrides merged with Configuration defaults
+    # @yield [Conversation] Block form with auto-cleanup
+    # @return [Conversation, Object] Conversation (no block) or block return value
+    #
+    # @example Block form
+    #   ClaudeAgent.chat(model: "opus") do |c|
+    #     c.say("Hello")
+    #     c.say("Goodbye")
+    #   end
+    #
+    # @example No block
+    #   c = ClaudeAgent.chat(model: "opus")
+    #   c.say("Hello")
+    #   c.close
+    #
+    def chat(**kwargs, &block)
+      # Merge global config defaults into kwargs for Conversation
+      merged = merge_config_into_kwargs(kwargs)
+
+      if block
+        Conversation.open(**merged, &block)
+      else
+        Conversation.new(**merged)
+      end
+    end
+
+    # Set a global permission policy.
+    #
+    # @yield [PermissionPolicy] DSL block
+    # @return [void]
+    def permissions(&block)
+      @config.default_permissions = PermissionPolicy.new(&block)
+    end
+
+    # Set global hooks.
+    #
+    # @yield [HookRegistry] DSL block
+    # @return [void]
+    def hooks(&block)
+      @config.default_hooks = HookRegistry.new(&block)
+    end
+
+    # Register a global MCP server.
+    #
+    # @param server [MCP::Server] Server instance
+    # @return [void]
+    def register_mcp_server(server)
+      @config.default_mcp_servers[server.name] = server.to_config
+    end
+
     # Create a new Conversation
     #
     # @see Conversation#initialize
@@ -130,5 +258,52 @@ module ClaudeAgent
     def resume_conversation(session_id, **kwargs)
       Conversation.resume(session_id, **kwargs)
     end
+
+    private
+
+    # Separate on_* callbacks from config overrides in kwargs.
+    def extract_callbacks(kwargs)
+      callbacks = {}
+      config_overrides = {}
+
+      kwargs.each do |key, value|
+        if key.to_s.start_with?("on_") || key == :can_use_tool
+          callbacks[key] = value
+        else
+          config_overrides[key] = value
+        end
+      end
+
+      [ callbacks, config_overrides ]
+    end
+
+    # Build an EventHandler from on_* callback kwargs.
+    def build_events(callbacks)
+      return nil if callbacks.empty?
+
+      events = EventHandler.new
+      callbacks.each do |key, value|
+        next unless value
+        next if key == :can_use_tool
+
+        event = Conversation::CALLBACK_ALIASES[key] || key.to_s.delete_prefix("on_").to_sym
+        events.on(event, &value)
+      end
+      events.has_handlers? ? events : nil
+    end
+
+    # Merge global config defaults into Conversation kwargs.
+    def merge_config_into_kwargs(kwargs)
+      merged = {}
+
+      # Apply config defaults for fields Conversation forwards to Options
+      Configuration::ALL_FIELDS.each do |field|
+        config_val = @config.public_send(field)
+        merged[field] = config_val unless config_val.nil?
+      end
+
+      # Per-request kwargs override config
+      merged.merge(kwargs)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.7.15
+  version: 0.7.16
 platform: ruby
 authors:
 - Thomas Carr
@@ -51,10 +51,25 @@ files:
 - README.md
 - Rakefile
 - SPEC.md
+- docs/architecture.md
+- docs/client.md
+- docs/configuration.md
+- docs/conversations.md
+- docs/errors.md
+- docs/events.md
+- docs/getting-started.md
+- docs/hooks.md
+- docs/logging.md
+- docs/mcp.md
+- docs/messages.md
+- docs/permissions.md
+- docs/queries.md
+- docs/sessions.md
 - lib/claude_agent.rb
 - lib/claude_agent/abort_controller.rb
 - lib/claude_agent/client.rb
 - lib/claude_agent/client/commands.rb
+- lib/claude_agent/configuration.rb
 - lib/claude_agent/content_blocks.rb
 - lib/claude_agent/content_blocks/generic_block.rb
 - lib/claude_agent/content_blocks/image_content_block.rb
@@ -77,12 +92,14 @@ files:
 - lib/claude_agent/fork_session.rb
 - lib/claude_agent/get_session_info.rb
 - lib/claude_agent/get_session_messages.rb
+- lib/claude_agent/hook_registry.rb
 - lib/claude_agent/hooks.rb
 - lib/claude_agent/list_sessions.rb
 - lib/claude_agent/live_tool_activity.rb
 - lib/claude_agent/logging.rb
 - lib/claude_agent/mcp/server.rb
 - lib/claude_agent/mcp/tool.rb
+- lib/claude_agent/message.rb
 - lib/claude_agent/message_parser.rb
 - lib/claude_agent/messages.rb
 - lib/claude_agent/messages/conversation.rb
@@ -95,6 +112,7 @@ files:
 - lib/claude_agent/messages/tool_lifecycle.rb
 - lib/claude_agent/options.rb
 - lib/claude_agent/options/serializer.rb
+- lib/claude_agent/permission_policy.rb
 - lib/claude_agent/permission_queue.rb
 - lib/claude_agent/permission_request.rb
 - lib/claude_agent/permissions.rb