claude_agent 0.7.14 → 0.7.16

data/lib/claude_agent/message.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Shared interface for all message and content block types.
+  #
+  # Provides a consistent API across the 22+ message types and 8 content
+  # block types without interfering with `Data.define` inheritance.
+  #
+  # @example Universal text extraction
+  #   message.text_content  # works on AssistantMessage, UserMessage, TextBlock, etc.
+  #
+  # @example Duck-type checks
+  #   message.session_message?   # has uuid + session_id?
+  #   message.identifiable?      # has uuid?
+  #
+  # @example Pattern matching
+  #   case message
+  #   in { type: :assistant }
+  #     puts message.text_content
+  #   in { type: :result }
+  #     puts message.cost
+  #   end
+  #
+  module Message
+    # Universal text extraction across all message and content block types.
+    #
+    # @return [String] Extracted text (empty string if no text available)
+    def text_content
+      case self
+      when AssistantMessage
+        text
+      when UserMessage, UserMessageReplay
+        content.is_a?(String) ? content : ""
+      when TextBlock
+        text
+      when ThinkingBlock
+        thinking
+      when StreamEvent
+        delta_text || ""
+      when ToolProgressMessage
+        ""
+      when ResultMessage
+        ""
+      when GenericMessage
+        raw.is_a?(Hash) ? (raw[:text] || raw["text"] || "").to_s : ""
+      else
+        respond_to?(:text) ? (text || "").to_s : ""
+      end
+    end
+
+    # Whether this message carries session identity (uuid + session_id).
+    #
+    # @return [Boolean]
+    def session_message?
+      respond_to?(:uuid) && respond_to?(:session_id) &&
+        !uuid.nil? && !session_id.nil?
+    end
+
+    # Whether this message has a UUID.
+    #
+    # @return [Boolean]
+    def identifiable?
+      respond_to?(:uuid) && !uuid.nil?
+    end
+
+    # Override deconstruct_keys to include :type for pattern matching.
+    #
+    # Allows `case msg; in { type: :assistant }` to work naturally.
+    #
+    # Data#deconstruct_keys stops early if it encounters a non-member key,
+    # so we filter out :type (a virtual key) before delegating to super.
+    #
+    # @param keys [Array<Symbol>, nil]
+    # @return [Hash]
+    def deconstruct_keys(keys)
+      if keys.nil?
+        { type: type }.merge(super)
+      elsif keys.include?(:type)
+        member_keys = keys - [ :type ]
+        base = member_keys.empty? ? {} : super(member_keys)
+        { type: type }.merge(base)
+      else
+        super
+      end
+    end
+  end
+
+  # Prepend Message in all message types (prepend needed to override Data#deconstruct_keys)
+  MESSAGE_TYPES.each { |klass| klass.prepend(Message) }
+
+  # Prepend Message in all content block types
+  CONTENT_BLOCK_TYPES.each { |klass| klass.prepend(Message) }
+end

data/lib/claude_agent/messages/streaming.rb

@@ -24,6 +24,43 @@ module ClaudeAgent
     def event_type
       event[:type]
     end
+
+    # Text delta content, or nil if this is not a text_delta event.
+    # @return [String, nil]
+    def delta_text
+      return nil unless event_type == "content_block_delta"
+      delta = event[:delta] || event["delta"]
+      return nil unless delta
+      type = delta[:type] || delta["type"]
+      return nil unless type == "text_delta"
+      delta[:text] || delta["text"]
+    end
+
+    # The delta type (e.g. "text_delta", "thinking_delta", "input_json_delta").
+    # @return [String, nil]
+    def delta_type
+      return nil unless event_type == "content_block_delta"
+      delta = event[:delta] || event["delta"]
+      return nil unless delta
+      delta[:type] || delta["type"]
+    end
+
+    # Thinking delta text, or nil if this is not a thinking_delta event.
+    # @return [String, nil]
+    def thinking_text
+      return nil unless event_type == "content_block_delta"
+      delta = event[:delta] || event["delta"]
+      return nil unless delta
+      type = delta[:type] || delta["type"]
+      return nil unless type == "thinking_delta"
+      delta[:thinking] || delta["thinking"]
+    end
+
+    # Content block index within the message.
+    # @return [Integer, nil]
+    def content_index
+      event[:index] || event["index"]
+    end
   end
 
   # Rate limit event (TypeScript SDK v0.2.45 parity)

data/lib/claude_agent/options.rb

@@ -122,10 +122,20 @@ module ClaudeAgent
               "Must set allow_dangerously_skip_permissions: true to use bypassPermissions mode"
       end
 
+      # Auto-compile PermissionPolicy to can_use_tool lambda
+      if can_use_tool.is_a?(PermissionPolicy)
+        @can_use_tool = can_use_tool.to_can_use_tool
+      end
+
       if can_use_tool && !can_use_tool.respond_to?(:call)
         raise ConfigurationError, "can_use_tool must be callable (Proc, Lambda, or object responding to #call)"
       end
 
+      # Auto-compile HookRegistry to hooks hash
+      if hooks.is_a?(HookRegistry)
+        @hooks = hooks.to_hooks_hash
+      end
+
       if on_elicitation && !on_elicitation.respond_to?(:call)
         raise ConfigurationError, "on_elicitation must be callable (Proc, Lambda, or object responding to #call)"
       end

data/lib/claude_agent/permission_policy.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Declarative permission policy builder.
+  #
+  # Compiles allow/deny rules into a `can_use_tool` lambda for use
+  # with Options and Conversation. Rules are evaluated in order;
+  # first match wins.
+  #
+  # @example Basic usage
+  #   policy = ClaudeAgent::PermissionPolicy.new do |p|
+  #     p.allow "Read", "Grep", "Glob"
+  #     p.deny "Bash", message: "Bash not allowed"
+  #     p.deny_all
+  #   end
+  #
+  # @example With regex matching
+  #   policy = ClaudeAgent::PermissionPolicy.new do |p|
+  #     p.allow_matching(/^mcp__/)
+  #     p.deny_all
+  #   end
+  #
+  # @example With custom handler for unmatched tools
+  #   policy = ClaudeAgent::PermissionPolicy.new do |p|
+  #     p.allow "Read"
+  #     p.ask { |name, input, ctx| PermissionResultAllow.new }
+  #   end
+  #
+  # @example Module-level convenience
+  #   ClaudeAgent.permissions do |p|
+  #     p.allow "Read", "Grep"
+  #     p.deny "Bash"
+  #   end
+  #
+  class PermissionPolicy
+    # @param block [Proc] DSL block yielding self
+    def initialize(&block)
+      @rules = []
+      @fallback = nil
+      yield self if block_given?
+    end
+
+    # Allow specific tools by exact name.
+    #
+    # @param tool_names [Array<String>] Tool names to allow
+    # @return [self]
+    def allow(*tool_names)
+      tool_names.flatten.each do |name|
+        @rules << { type: :exact, name: name.to_s, action: :allow }
+      end
+      self
+    end
+
+    # Deny specific tools by exact name.
+    #
+    # @param tool_names [Array<String>] Tool names to deny
+    # @param message [String] Denial message
+    # @param interrupt [Boolean] Whether to interrupt the conversation
+    # @return [self]
+    def deny(*tool_names, message: "", interrupt: false)
+      tool_names.flatten.each do |name|
+        @rules << { type: :exact, name: name.to_s, action: :deny, message: message, interrupt: interrupt }
+      end
+      self
+    end
+
+    # Allow tools matching a pattern.
+    #
+    # @param pattern [Regexp, String] Pattern to match against tool names
+    # @return [self]
+    def allow_matching(pattern)
+      @rules << { type: :pattern, pattern: to_regexp(pattern), action: :allow }
+      self
+    end
+
+    # Deny tools matching a pattern.
+    #
+    # @param pattern [Regexp, String] Pattern to match against tool names
+    # @param message [String] Denial message
+    # @param interrupt [Boolean] Whether to interrupt the conversation
+    # @return [self]
+    def deny_matching(pattern, message: "", interrupt: false)
+      @rules << { type: :pattern, pattern: to_regexp(pattern), action: :deny, message: message, interrupt: interrupt }
+      self
+    end
+
+    # Set a custom handler for tools that don't match any rule.
+    #
+    # @yield [name, input, context] Called for unmatched tools
+    # @return [self]
+    def ask(&handler)
+      @fallback = handler
+      self
+    end
+
+    # Set fallback to allow all unmatched tools.
+    # @return [self]
+    def allow_all
+      @fallback = :allow
+      self
+    end
+
+    # Set fallback to deny all unmatched tools.
+    #
+    # @param message [String] Denial message for unmatched tools
+    # @return [self]
+    def deny_all(message: "Denied by policy")
+      @fallback = { action: :deny, message: message }
+      self
+    end
+
+    # Compile this policy into a `can_use_tool` lambda.
+    #
+    # @return [Proc] Lambda compatible with Options#can_use_tool
+    def to_can_use_tool
+      rules = @rules.dup.freeze
+      fallback = @fallback
+
+      ->(tool_name, tool_input, context) {
+        # Check rules in order, first match wins
+        rules.each do |rule|
+          next unless matches?(rule, tool_name)
+
+          case rule[:action]
+          when :allow
+            return PermissionResultAllow.new
+          when :deny
+            return PermissionResultDeny.new(message: rule[:message], interrupt: rule[:interrupt])
+          end
+        end
+
+        # No rule matched, use fallback
+        case fallback
+        when :allow
+          PermissionResultAllow.new
+        when Hash
+          PermissionResultDeny.new(message: fallback[:message])
+        when Proc
+          fallback.call(tool_name, tool_input, context)
+        else
+          # Default: allow (no policy restriction)
+          PermissionResultAllow.new
+        end
+      }
+    end
+
+    # Whether any rules have been defined.
+    # @return [Boolean]
+    def empty?
+      @rules.empty? && @fallback.nil?
+    end
+
+    private
+
+    def matches?(rule, tool_name)
+      case rule[:type]
+      when :exact
+        rule[:name] == tool_name.to_s
+      when :pattern
+        rule[:pattern].match?(tool_name.to_s)
+      else
+        false
+      end
+    end
+
+    def to_regexp(pattern)
+      case pattern
+      when Regexp then pattern
+      when String then Regexp.new(pattern)
+      else raise ArgumentError, "Pattern must be a Regexp or String, got #{pattern.class}"
+      end
+    end
+  end
+end

data/lib/claude_agent/permission_request.rb

@@ -132,6 +132,23 @@ module ClaudeAgent
       end
     end
 
+    # Human-readable label for the permission request.
+    #
+    # Delegates to {ToolUseBlock#display_label} formatting.
+    #
+    # @return [String]
+    def display_label
+      ToolUseBlock.new(id: "", name: tool_name, input: input || {}).display_label
+    end
+
+    # Detailed summary of the tool call.
+    #
+    # @param max [Integer] Maximum length before truncation
+    # @return [String]
+    def summary(max: 60)
+      ToolUseBlock.new(id: "", name: tool_name, input: input || {}).summary(max: max)
+    end
+
     def inspect
       status = resolved? ? "resolved(#{@result&.behavior})" : "pending"
       "#<#{self.class} tool=#{tool_name} status=#{status} age=#{(Time.now - created_at).round(1)}s>"

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/turn_result.rb

@@ -35,6 +35,7 @@ module ClaudeAgent
     def initialize
       @messages = []
       @result = nil
+      @streamed_text = +""
     end
 
     # Append a message to this turn
@@ -44,6 +45,13 @@ module ClaudeAgent
     def <<(message)
       @messages << message
       @result = message if message.is_a?(ResultMessage)
+
+      # Accumulate streaming text deltas for reliable text access on abort
+      if message.is_a?(StreamEvent)
+        delta = message.delta_text
+        @streamed_text << delta if delta
+      end
+
       self
     end
 
@@ -61,10 +69,20 @@ module ClaudeAgent
 
     # --- Text & Thinking ---
 
-    # All text content concatenated across assistant messages
+    # All text content from the turn.
+    #
+    # Returns text from AssistantMessages when available (canonical source).
+    # Falls back to accumulated streaming deltas when assistant messages
+    # have no text (e.g., turn was aborted before AssistantMessage arrived).
+    #
     # @return [String]
     def text
-      assistant_messages.map(&:text).join
+      t = assistant_messages.map(&:text).join
+      if t.empty? && !@streamed_text.empty?
+        @streamed_text.dup.freeze
+      else
+        t
+      end
     end
 
     # All thinking content concatenated across assistant messages

data/lib/claude_agent/types/sessions.rb

@@ -47,4 +47,12 @@ module ClaudeAgent
       super
     end
   end
+
+  # Result of forking a session (TypeScript SDK v0.2.76 parity)
+  #
+  # @example
+  #   result = ClaudeAgent.fork_session("abc-123")
+  #   puts result.session_id  # => new UUID
+  #
+  ForkSessionResult = Data.define(:session_id)
 end

data/lib/claude_agent/version.rb

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