claude-agent-sdk 1.1.0 → 1.2.0

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -36,6 +36,9 @@ module ClaudeAgentSDK
   # mangled into nonsense parameter lists ("additionalProperties" as a
   # required string param). A $ref-only schema without type: 'object' remains
   # indistinguishable from a params hash — declare the type alongside $ref.
+  # For the same reason { type: :object } is this prebuilt accept-any-object
+  # schema even though :object is also a shorthand type: a simple schema with
+  # an object parameter literally named type has to spell it { type: Hash }.
   # @api private
   def self.prebuilt_json_schema?(schema)
     return false unless schema.is_a?(Hash)
@@ -67,13 +70,16 @@ module ClaudeAgentSDK
   # @api private
   def self.ruby_type_to_json_schema(type)
     # Class#=== matches instances, not the class object used in { id: Integer }.
-    type = { String => :string, Integer => :integer, Float => :float,
-             TrueClass => :boolean, FalseClass => :boolean }.fetch(type, type)
+    type = { String => :string, Integer => :integer, Float => :float, TrueClass => :boolean,
+             FalseClass => :boolean, Array => :array, Hash => :object }.fetch(type, type)
     case type
     when :string, String then { type: 'string' }
     when :integer, Integer then { type: 'integer' }
     when :float, Float, :number then { type: 'number' }
     when :boolean, TrueClass, FalseClass then { type: 'boolean' }
+    # The class or the Symbol only. An Array or Hash VALUE ([String], a nested
+    # schema fragment) is not a shorthand and falls through like before.
+    when :array, :object then { type: type.to_s }
     else { type: 'string' } # rubocop:disable Lint/DuplicateBranch -- default fallback; the :string arm stays explicit
     end
   end
@@ -301,13 +307,25 @@ module ClaudeAgentSDK
         ClaudeAgentSDK.normalize_tool_result(tool.handler.call(arguments))
       end
 
-      # Guard before flexible_fetch: it raises on non-Hash inputs.
-      content = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, 'content', 'content') : nil
-      return error_tool_result("Tool '#{name}' must return a hash with :content key") unless content
+      # Guard before flexible_fetch: it raises on non-Hash inputs. This first
+      # diagnostic is about the KEY: a present false or nil is a wrong value
+      # and gets the Array diagnostic below, like any other non-Array.
+      unless result.is_a?(Hash) && (result.key?(:content) || result.key?('content'))
+        return error_tool_result("Tool '#{name}' must return a hash with :content key")
+      end
+
+      content = ClaudeAgentSDK.flexible_fetch(result, 'content', 'content')
+      # A String or a single block here is not a result an MCP client accepts.
+      unless content.is_a?(Array)
+        return error_tool_result("Tool '#{name}' must return :content as an Array of content blocks " \
+                                 "(got #{content.class})")
+      end
 
       result
-    rescue StandardError => e
-      # Bare e.message like Python's str(e) — no prefix.
+    rescue *FiberBoundary::CALLBACK_FAILURES => e
+      # Bare e.message like Python's str(e) — no prefix. The list, not just
+      # StandardError: a handler's NotImplementedError, LoadError or
+      # SystemStackError is a tool failure the model should read as well.
       error_tool_result(e.message)
     end
 
@@ -412,7 +430,7 @@ module ClaudeAgentSDK
     end
 
     # Create dynamic Tool classes from tool definitions
-    def create_tool_classes(tools) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- builds each dynamic MCP::Tool subclass inline
+    def create_tool_classes(tools) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- builds each dynamic MCP::Tool subclass inline
       # Captured so the dynamic class can resolve the effective scheduling
       # mode at call time — same pattern as prompt classes.
       sdk_server = self
@@ -444,16 +462,22 @@ module ClaudeAgentSDK
             end
 
             def input_schema_value
-              # Full-schema construction: the gem JSON-round-trips and
-              # validates against the draft4 metaschema. additionalProperties/
-              # enum/description survive. Empty required arrays are stripped —
-              # draft4's metaschema mandates non-empty required (Python's
-              # modern jsonschema accepts []). Schemas the draft4 metaschema
-              # rejects (numeric exclusiveMinimum, $ref/$defs — valid modern
-              # JSON Schema that Python accepts) fall back to a permissive
-              # schema with a one-time warning: the tool keeps working with
-              # argument validation disabled instead of being permanently
-              # uncallable while tools/list advertises it as healthy.
+              # Full-schema construction: the gem JSON-round-trips the schema
+              # and validates it against the JSON Schema 2020-12 metaschema
+              # (every mcp version this gem supports; older ones used draft4).
+              # additionalProperties/enum/description survive, and so do a
+              # numeric exclusiveMinimum and same-document $ref/$defs. Empty
+              # required arrays are stripped — a holdover from draft4, whose
+              # metaschema mandated a non-empty required.
+              #
+              # A schema the gem refuses (ArgumentError: a draft4-style
+              # boolean exclusiveMinimum, an unknown type, a $ref that leaves
+              # the document, an invalid pattern, ...) falls back to a
+              # permissive schema with a warning, once per tool: the tool
+              # keeps working with argument validation disabled instead of
+              # being permanently uncallable while tools/list advertises it
+              # as healthy. (The warning's "not draft4-compatible" wording
+              # dates from the draft4 days.)
               @input_schema_value ||= begin
                 schema = ClaudeAgentSDK.normalize_tool_schema(@tool_def.input_schema)
                 schema = schema.except(:required) if schema[:required].is_a?(Array) && schema[:required].empty?
@@ -493,11 +517,21 @@ module ClaudeAgentSDK
 
               # Guard BEFORE flexible_fetch: on a non-Hash it raises
               # TypeError/NoMethodError, surfacing garbage instead of the
-              # friendly message.
-              raise "Tool '#{@tool_def.name}' must return a hash with :content key" unless result.is_a?(Hash)
+              # friendly message. This first diagnostic is about the KEY: a
+              # present false or nil is a wrong value and gets the Array
+              # diagnostic below, like any other non-Array.
+              unless result.is_a?(Hash) && (result.key?(:content) || result.key?('content'))
+                raise "Tool '#{@tool_def.name}' must return a hash with :content key"
+              end
 
               content = ClaudeAgentSDK.flexible_fetch(result, 'content', 'content')
-              raise "Tool '#{@tool_def.name}' must return a hash with :content key" if content.nil?
+              # A String or a single block Hash would go out as it is, and the
+              # CLI rejects that frame against its schema: the model is told
+              # the SERVER returned a malformed result and never sees the text.
+              unless content.is_a?(Array)
+                raise "Tool '#{@tool_def.name}' must return :content as an Array of content blocks " \
+                      "(got #{content.class})"
+              end
 
               is_error = ClaudeAgentSDK.flexible_fetch(result, 'isError', 'is_error')
               structured_content = ClaudeAgentSDK.flexible_fetch(result, 'structuredContent', 'structured_content')
@@ -507,12 +541,15 @@ module ClaudeAgentSDK
                 error: !!is_error,
                 structured_content: structured_content
               )
-            rescue StandardError => e
+            rescue *FiberBoundary::CALLBACK_FAILURES => e
               # Report handler failures in-band HERE rather than letting them
               # reach the gem: mcp >= 1.2 deliberately drops e.message from
               # its "Internal error calling tool X" wrapper (CWE-209), which
               # would hide the text the model needs to self-correct. Bare
               # e.message like Python's str(e) and #call_tool — no prefix.
+              # The list, not just StandardError: the gem rescues only
+              # StandardError, so a handler's NotImplementedError / LoadError /
+              # SystemStackError would pass it unanswered.
               # Nothing gem-internal can be swallowed here today: handlers get
               # no server_context, so MCP::CancelledError never originates
               # inside this method. Revisit if cancellation is ever plumbed in.
@@ -606,7 +643,17 @@ module ClaudeAgentSDK
   #
   # @param name [String] Unique identifier for the tool
   # @param description [String] Human-readable description
-  # @param input_schema [Hash] Schema defining input parameters
+  # @param input_schema [Hash] Schema defining input parameters: a full JSON
+  #   Schema (+{ type: 'object', properties: ... }+), or the shorthand
+  #   +{ name: type }+, in which every parameter is required and each type is
+  #   +String+ / +:string+, +Integer+ / +:integer+, +Float+ / +:float+ /
+  #   +:number+, +TrueClass+ / +FalseClass+ / +:boolean+, +Array+ / +:array+
+  #   or +Hash+ / +:object+
+  # @param annotations [Hash, nil] MCP tool annotations (+title+,
+  #   +readOnlyHint+, ...). +maxResultSizeChars+ is also forwarded as
+  #   +_meta['anthropic/maxResultSizeChars']+, the form the CLI reads
+  # @param meta [Hash, nil] The tool's +_meta+. Merged with the size hint
+  #   derived from +annotations+; a key given here wins
   # @param handler [Proc] Block that implements the tool logic. It returns a
   #   String, sent to Claude as a single text block, or a Hash with a
   #   +:content+ Array of MCP content blocks plus optional +:is_error+ /
@@ -641,11 +688,16 @@ module ClaudeAgentSDK
   def self.create_tool(name, description, input_schema, annotations: nil, meta: nil, &handler)
     raise ArgumentError, 'Block required for tool handler' unless handler
 
-    # Auto-populate _meta with maxResultSizeChars from annotations if present
+    # Auto-populate _meta with maxResultSizeChars from annotations if present.
+    # An explicit meta: is merged with that hint rather than replacing it (an
+    # unrelated key used to drop it); a size key the caller sets itself wins,
+    # in either spelling — adding the String key beside a Symbol one would
+    # put the same JSON key in the frame twice.
+    size_key = 'anthropic/maxResultSizeChars'
     resolved_meta = meta
-    if resolved_meta.nil? && annotations
+    if annotations.is_a?(Hash) && (meta.nil? || (meta.is_a?(Hash) && meta.keys.none? { |key| key.to_s == size_key }))
       max_chars = annotations[:maxResultSizeChars] || annotations['maxResultSizeChars']
-      resolved_meta = { 'anthropic/maxResultSizeChars' => max_chars } if max_chars
+      resolved_meta = { size_key => max_chars }.merge(meta || {}) if max_chars
     end
 
     # tools/call arrives from the CLI with the name as a JSON String; the mcp

data/lib/claude_agent_sdk/session_mutations.rb

@@ -27,19 +27,25 @@ module ClaudeAgentSDK
 
     # Rename a session by appending a custom-title entry.
     #
-    # list_sessions reads the LAST custom-title from the file tail, so
-    # repeated calls are safe — the most recent wins.
+    # Repeated calls are safe: the disk listing takes the LAST custom-title
+    # in the final 64 KiB of the file (then in the first 64 KiB), the store
+    # fold the last one overall. On disk the entry is only seen while it
+    # stays inside one of those windows: rename a session that is still
+    # running, let 64 KiB of transcript follow, and list_sessions /
+    # get_session_info report the previous title again until the CLI resumes
+    # the session and re-appends its metadata at the end (the same holds for
+    # tag_session). Not fixed here: finding it again means reading the whole
+    # file on every listing.
     #
     # @param session_id [String] UUID of the session to rename
     # @param title [String] New session title (whitespace stripped)
     # @param directory [String, nil] Project directory path
-    # @raise [ArgumentError] if session_id is invalid or title is empty
+    # @raise [ArgumentError] if session_id is invalid, or title is blank or not a String
     # @raise [Errno::ENOENT] if the session file cannot be found
     def rename_session(session_id:, title:, directory: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
-      stripped = title.strip
-      raise ArgumentError, 'title must be non-empty' if stripped.empty?
+      stripped = stripped_title(title)
 
       data = "#{JSON.generate({ type: 'custom-title', customTitle: stripped, sessionId: session_id })}\n"
 
@@ -54,19 +60,12 @@ module ClaudeAgentSDK
     # @param session_id [String] UUID of the session to tag
     # @param tag [String, nil] Tag string, or nil to clear
     # @param directory [String, nil] Project directory path
-    # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
+    # @raise [ArgumentError] if session_id is invalid, or tag is not a String or is empty after sanitization
     # @raise [Errno::ENOENT] if the session file cannot be found
     def tag_session(session_id:, tag:, directory: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
-      if tag
-        sanitized = sanitize_unicode(tag).strip
-        raise ArgumentError, 'tag must be non-empty (use nil to clear)' if sanitized.empty?
-
-        tag = sanitized
-      end
-
-      data = "#{JSON.generate({ type: 'tag', tag: tag || '', sessionId: session_id })}\n"
+      data = "#{JSON.generate({ type: 'tag', tag: sanitized_tag(tag), sessionId: session_id })}\n"
 
       append_to_session(session_id, data, directory)
     end
@@ -164,13 +163,12 @@ module ClaudeAgentSDK
     # appended entry carries a fresh uuid + ISO timestamp so adapters that dedupe
     # by entry["uuid"] (per the SessionStore#append contract) treat it correctly.
     #
-    # @raise [ArgumentError] if session_id is invalid or title is empty
+    # @raise [ArgumentError] if session_id is invalid, or title is blank or not a String
     # @raise [Errno::ENOENT] if the session is not found in the store
     def rename_session_via_store(session_store:, session_id:, title:, directory: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
-      stripped = title.strip
-      raise ArgumentError, 'title must be non-empty' if stripped.empty?
+      stripped = stripped_title(title)
 
       key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
       ensure_store_session_exists(session_store, key)
@@ -188,23 +186,17 @@ module ClaudeAgentSDK
     # counterpart to tag_session. Pass nil to clear the tag. Tags are
     # Unicode-sanitized before storing.
     #
-    # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
+    # @raise [ArgumentError] if session_id is invalid, or tag is not a String or is empty after sanitization
     # @raise [Errno::ENOENT] if the session is not found in the store
     def tag_session_via_store(session_store:, session_id:, tag:, directory: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
-      if tag
-        sanitized = sanitize_unicode(tag).strip
-        raise ArgumentError, 'tag must be non-empty (use nil to clear)' if sanitized.empty?
-
-        tag = sanitized
-      end
-
+      tag = sanitized_tag(tag)
       key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
       ensure_store_session_exists(session_store, key)
       session_store.append(key, [{
                              'type' => 'tag',
-                             'tag' => tag || '',
+                             'tag' => tag,
                              'sessionId' => session_id,
                              'uuid' => SecureRandom.uuid,
                              'timestamp' => iso_now
@@ -222,10 +214,9 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id is invalid
     def delete_session_via_store(session_store:, session_id:, directory: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
-      return unless SessionStore.implements?(session_store, :delete)
 
       key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
-      session_store.delete(key)
+      SessionStores.optional_call(session_store, :delete) { session_store.delete(key) }
       nil
     end
 
@@ -263,6 +254,49 @@ module ClaudeAgentSDK
 
     # -- Private helpers --
 
+    # The title to store: stripped and non-empty. A value that is not a usable
+    # String (nil, another type, bytes invalid in their encoding) gets the
+    # ArgumentError an empty title gets — the boundary check the session ids
+    # have — where calling #strip on it raised NoMethodError or an encoding
+    # error from inside.
+    def stripped_title(title)
+      text = utf8_text(title)
+      stripped = text ? text.strip : ''
+      raise ArgumentError, 'title must be non-empty' if stripped.empty?
+
+      stripped
+    end
+
+    # +value+ as UTF-8 text, or nil when it is not usable text: not a String,
+    # or bytes that are not valid text. A binary String (ASCII-8BIT, what
+    # File.binread returns) always reports valid_encoding?, so it is read as
+    # the UTF-8 it usually holds and checked as such; a String in another
+    # encoding is transcoded. Without this, binary bytes that are not UTF-8
+    # got past the check and failed later as JSON::GeneratorError or
+    # Encoding::CompatibilityError instead of the documented ArgumentError.
+    def utf8_text(value)
+      return nil unless value.is_a?(String)
+
+      text = value.encoding == Encoding::BINARY ? value.dup.force_encoding(Encoding::UTF_8) : value.encode(Encoding::UTF_8)
+      text.valid_encoding? ? text : nil
+    rescue EncodingError
+      nil
+    end
+
+    # The tag to store: Unicode-sanitized and stripped, or '' (which clears
+    # the tag) for nil — only nil: false is not a tag either, and clearing on
+    # it would turn a Boolean from untyped input into a destructive write.
+    # Same boundary check as stripped_title.
+    def sanitized_tag(tag)
+      return '' if tag.nil?
+
+      text = utf8_text(tag)
+      sanitized = text ? sanitize_unicode(text).strip : ''
+      raise ArgumentError, 'tag must be non-empty (use nil to clear)' if sanitized.empty?
+
+      sanitized
+    end
+
     # Raise Errno::ENOENT (as the disk counterparts and fork_session_via_store
     # do) unless the store holds entries for +key+. Without this probe, a
     # rename/tag of a typo'd or stale id APPENDED metadata to a never-written
@@ -293,8 +327,12 @@ module ClaudeAgentSDK
     end
 
     def find_in_directory(file_name, directory)
-      path = File.realpath(directory).unicode_normalize(:nfc)
-      result = try_project_dir(file_name, Sessions.find_project_dir(path))
+      # canonicalize_path, not File.realpath: the transcripts outlive the
+      # directory (a removed worktree), and realpath raised Errno::ENOENT for
+      # it before the session was even looked for — while the readers, which
+      # canonicalize, still found the session through the same directory.
+      path = Sessions.canonicalize_path(directory)
+      result = try_project_dir(file_name, Sessions.find_project_dir(path), path)
       return result if result
 
       worktree_paths = begin
@@ -305,7 +343,7 @@ module ClaudeAgentSDK
       worktree_paths.each do |wt_path|
         next if wt_path == path
 
-        result = try_project_dir(file_name, Sessions.find_project_dir(wt_path))
+        result = try_project_dir(file_name, Sessions.find_project_dir(wt_path), wt_path)
         return result if result
       end
       nil
@@ -315,11 +353,17 @@ module ClaudeAgentSDK
     # in one project dir must not stop the search when the real transcript
     # lives under another (worktree) project dir. Mirrors the read path
     # (Sessions.stat_candidate) and the append path (try_append).
-    def try_project_dir(file_name, project_dir)
+    # With +path+ (a directory-scoped lookup), the candidate must also be one
+    # of that path's own transcripts (Sessions.own_transcript?: a directory
+    # the long-path fallback found can hold other paths' sessions).
+    def try_project_dir(file_name, project_dir, path = nil)
       return nil unless project_dir
 
       candidate = File.join(project_dir, file_name)
-      File.size(candidate).positive? ? [candidate, project_dir] : nil
+      return nil unless File.size(candidate).positive?
+      return nil if path && !Sessions.own_transcript?(project_dir, candidate, path)
+
+      [candidate, project_dir]
     rescue SystemCallError
       nil
     end
@@ -433,9 +477,10 @@ module ClaudeAgentSDK
                                })
       end
 
-      # Derive title: explicit > original customTitle > original aiTitle > first
-      # prompt, suffixed with " (fork)" when derived. listSessions reads the LAST
-      # custom-title from the tail, so this trailer is what surfaces.
+      # Derive title: explicit > the source's listed title (custom, else AI) >
+      # its first prompt, suffixed with " (fork)" when derived. listSessions
+      # reads the LAST custom-title from the tail, so this trailer is what
+      # surfaces.
       fork_title = title&.strip
       fork_title = "#{derive_title.call || 'Forked session'} (fork)" if fork_title.nil? || fork_title.empty?
 
@@ -472,61 +517,30 @@ module ClaudeAgentSDK
       [transcript, content_replacements]
     end
 
-    # Derive a fork title by scanning already-parsed store entries — the store
-    # path's analogue of derive_fork_title's head/tail byte scan. Last occurrence
-    # wins for both customTitle and aiTitle; customTitle beats aiTitle; the first
-    # user prompt is the final fallback. Returns nil when nothing is found (the
-    # caller supplies the "Forked session" default). This scans the RAW entries,
-    # not the partitioned transcript (which drops customTitle/aiTitle metadata) —
-    # the store half of #837's P0-1 fix.
+    # Derive a fork title from already-parsed store entries: the title the
+    # store listing shows for the session (custom title, else AI title — the
+    # latest occurrence of each, a blank one counting as absent), else its
+    # first prompt. Folds the RAW entries (the partitioned transcript has
+    # dropped the customTitle/aiTitle metadata — the store half of #837's
+    # P0-1 fix) with the fold the listing uses, and takes the title from the
+    # folded fields rather than from summary_entry_to_sdk_info: that returns
+    # nil for a sidechain or summary-less session, which can still be forked.
+    # nil when the session has none of the three (the caller supplies the
+    # "Forked session" default).
     def derive_title_from_entries(raw)
-      custom = nil
-      ai = nil
-      raw.each do |e|
-        next unless e.is_a?(Hash)
-
-        ct = e['customTitle']
-        custom = ct if ct.is_a?(String) && !ct.empty?
-        at = e['aiTitle']
-        ai = at if at.is_a?(String) && !at.empty?
-      end
-      return custom if custom
-      return ai if ai
-
-      # First-prompt fallback: re-serialize to a JSONL string and reuse the head
-      # extractor so skip-patterns/truncation match the disk path exactly.
-      # extract_first_prompt_from_head returns '' (truthy in Ruby!) when no
-      # prompt qualifies — normalize to nil so the caller's 'Forked session'
-      # default actually fires (Python appends `or None` here for this reason).
-      jsonl = "#{raw.map { |e| JSON.generate(e) }.join("\n")}\n"
-      title = Sessions.extract_first_prompt_from_head(jsonl)
-      title.nil? || title.empty? ? nil : title
+      data = SessionSummary.fold_session_summary(nil, {}, raw)['data']
+      first_prompt = data['first_prompt_locked'] ? data['first_prompt'] : data['command_fallback']
+      Sessions.display_title(data['custom_title'], data['ai_title']) || Sessions.presence(first_prompt)
     end
 
-    # Derive a fork title from the source file's head/tail chunks without
-    # slurping the entire file. Matches the lookup order used for
-    # SDKSessionInfo.custom_title / ai_title / first_prompt. Returns nil when
-    # nothing is found (build_fork_lines supplies the "Forked session" default).
+    # Derive a fork title from the source file without slurping it: the title
+    # and first prompt the disk listing reports for the session, taken from
+    # the same head/tail windows by the same rule. nil when it has neither
+    # (build_fork_lines supplies the "Forked session" default).
     def derive_fork_title(file_path, file_size)
-      buf_size = [Sessions::LITE_READ_BUF_SIZE, file_size].min
-      File.open(file_path, 'rb') do |f|
-        head = (f.read(buf_size) || '').force_encoding('UTF-8').scrub
-        tail = if file_size > Sessions::LITE_READ_BUF_SIZE
-                 f.seek(-buf_size, IO::SEEK_END)
-                 (f.read(buf_size) || '').force_encoding('UTF-8').scrub
-               else
-                 head
-               end
-        title = Sessions.extract_json_string_field(tail, 'customTitle', last: true) ||
-                Sessions.extract_json_string_field(head, 'customTitle', last: true) ||
-                Sessions.extract_json_string_field(tail, 'aiTitle', last: true) ||
-                Sessions.extract_json_string_field(head, 'aiTitle', last: true) ||
-                Sessions.extract_first_prompt_from_head(head)
-        # extract_first_prompt_from_head returns '' (truthy in Ruby!) when no
-        # prompt qualifies — normalize to nil so the 'Forked session' default
-        # fires (Python appends `or None` here for the same reason).
-        title.nil? || title.empty? ? nil : title
-      end
+      head, tail = Sessions.read_head_tail(file_path, file_size)
+      title, first_prompt = Sessions.title_and_first_prompt(file_path, head, tail, file_size)
+      title || first_prompt
     end
 
     # Build a single forked entry with remapped UUIDs.
@@ -587,11 +601,11 @@ module ClaudeAgentSDK
     end
 
     def append_to_session_in_directory(session_id, data, file_name, directory)
-      path = File.realpath(directory).unicode_normalize(:nfc)
+      path = Sessions.canonicalize_path(directory) # see find_in_directory
 
       # Try the exact/prefix-matched project directory first.
       project_dir = Sessions.find_project_dir(path)
-      return if project_dir && try_append(File.join(project_dir, file_name), data)
+      return if project_dir && own_append(project_dir, file_name, path, data)
 
       # Worktree fallback
       begin
@@ -604,7 +618,7 @@ module ClaudeAgentSDK
         next false if wt_path == path
 
         wt_project_dir = Sessions.find_project_dir(wt_path)
-        wt_project_dir && try_append(File.join(wt_project_dir, file_name), data)
+        wt_project_dir && own_append(wt_project_dir, file_name, wt_path, data)
       end
       return if found
 
@@ -626,6 +640,12 @@ module ClaudeAgentSDK
       raise Errno::ENOENT, "Session #{session_id} not found in any project directory"
     end
 
+    # try_append, for a transcript of +path+'s own (Sessions.own_transcript?).
+    def own_append(project_dir, file_name, path, data)
+      candidate = File.join(project_dir, file_name)
+      Sessions.own_transcript?(project_dir, candidate, path) && try_append(candidate, data)
+    end
+
     # Try appending to a path.
     #
     # Opens with WRONLY | APPEND (no CREAT) so the open fails with
@@ -675,11 +695,11 @@ module ClaudeAgentSDK
       'Other'
     end
 
-    private_class_method :find_session_file_with_dir,
+    private_class_method :stripped_title, :sanitized_tag, :find_session_file_with_dir,
                          :find_in_directory, :try_project_dir, :find_in_all_projects,
                          :parse_fork_transcript, :derive_fork_title, :build_forked_entry, :resolve_parent_uuid,
                          :append_to_session, :append_to_session_in_directory,
-                         :append_to_session_global, :try_append, :sanitize_unicode, :unicode_category,
+                         :append_to_session_global, :own_append, :try_append, :sanitize_unicode, :unicode_category,
                          :iso_now, :build_fork_lines, :partition_fork_entries, :derive_title_from_entries,
                          :ensure_store_session_exists
   end