openclacky 1.3.4 → 1.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d5879a7f2c6eb0a1846dd3049fa79abd3ca53119750bd0a43b337339f146dad
-  data.tar.gz: 12a39e3d860e9e9e691424289543b73813bcb4652e11fe0719e72aa9e6c72760
+  metadata.gz: 45a64960de249e34ee18e67f0ce38888b510a886988d545c58aca558d942bbdb
+  data.tar.gz: '008d7b7bec8fd7edf43cb9848949637d23783d2ad3a8a2b6199010f9b8ed660d'
 SHA512:
-  metadata.gz: cdb47cb9da7cccae4329aa0d4b98f03d9e5cadf763c12b9cd255060e2f230154eed3e7404e494f9a0b7e7b54cdb569f2dc25a1ea69c0b8af386a4a1122942d65
-  data.tar.gz: 196c48e418e2119201664b920871aa489ff3531128a8aa8b981f73d6ddc95a7d3ef23ecb79da0611810b8af02735f83340ce0712ddb18ad30de0f94421dbd0a4
+  metadata.gz: 2f0e9c3fb21691cf9bbfdd6820faaaed86086bebb820278b6104356f92fec4c0e53584a8c3ca40bfd42fb7f82e1f3a484ed404c2b693a47467e9c43d517ed9e8
+  data.tar.gz: 83cb1fa9ac5a3ae4834bf5c02c344da9db09a5863a4970857f2d233656c66d9b20fde131f0af4b04d23e204a09a978968ae7d2310ae1c3c3ceb8bcb6d721e3c2

data/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.3.6] - 2026-06-30
+
+### Added
+- Cron task session isolation with independent pagination and stable task count
+- Backup/restore UI in settings with WebSocket reconnect refresh and WSL open-folder support
+
+### Fixed
+- Rewrite human-readable cron parser to handle comma-separated lists, hour ranges, and `*/1` normalization
+- Setup submit button hover color follows accent theme variable
+- Settings button no longer navigates away when already on settings page
+- Use Unix epoch for old thread timestamps to avoid date parsing issues
+
+## [1.3.5] - 2026-06-29
+
+### Added
+- Run agent inside meeting sessions; launch new meetings directly from session context
+- Long video generation support
+- Show raw LLM error message in error card with collapsible detail
+- Fake tool call detector to catch hallucinated tool invocations
+- Accent color customization for Web UI theme
+
+### Improved
+- Refine auto-confirm wait TUI display
+- Improve split button UX and billing period tab hover behavior
+
+### Fixed
+- Terminal: adaptive GBK/UTF-8 decoding for PTY output to fix garbled text on Windows
+- Resolve vision model detection against the actual request model
+- Fix FrozenError when pressing Ctrl+U to clear text in modal
+- Detect scrollbar-drag correctly to prevent unwanted auto-scroll in chat
+- Fix split button dropdown closing when clicking inside button wrap area
+- Show success toast when saving profile or memory
+- Preserve single line breaks in profile/memory preview
+- Make text selection visible in profile/memory editor
+- Preserve memory card expand state across re-render
+- Refresh time machine on task completion
+- Re-check version on WebSocket reconnect so upgrade badge updates
+- Harden DashScope TTS routing and error handling
+
 ## [1.3.4] - 2026-06-25
 
 ### Added

data/lib/clacky/agent/fake_tool_call_detector.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Clacky
+  class Agent
+    module FakeToolCallDetector
+      FAKE_TOOL_CALL_PATTERNS = [
+        /<\s*invoke\s+name\s*=\s*["'][\w\-]+["']/i,
+        /<\s*function_calls\s*>/i,
+        /<\s*tool_use\s*[\s>]/i,
+        /<\s*antml:invoke\s+name\s*=/i,
+        /<\s*antml:function_calls\s*>/i
+      ].freeze
+
+      MAX_FAKE_TOOL_CALL_RETRIES = 2
+
+      private def fake_tool_call_in_content?(content)
+        return false if content.nil? || content.empty?
+        FAKE_TOOL_CALL_PATTERNS.any? { |re| content.match?(re) }
+      end
+
+      private def handle_fake_tool_call(response)
+        @task_fake_tool_call_count = (@task_fake_tool_call_count || 0) + 1
+
+        Clacky::Logger.warn("agent.fake_tool_call_detected",
+          session_id: @session_id,
+          iteration: @iterations,
+          retry_count: @task_fake_tool_call_count,
+          content_head: response[:content].to_s[0, 200],
+          finish_reason: response[:finish_reason].to_s
+        )
+
+        if @task_fake_tool_call_count > MAX_FAKE_TOOL_CALL_RETRIES
+          @ui&.show_error("Model repeatedly emitted text-formatted tool calls instead of using the tool_calls API. Stopping.")
+          emit_assistant_message(response[:content], reasoning_content: response[:reasoning_content]) if response[:content] && !response[:content].empty?
+          return :stop
+        end
+
+        @history.append({ role: "assistant", content: response[:content].to_s })
+        @history.append({
+          role: "user",
+          content: "Your previous reply contained tool-call XML written as text " \
+                   "(e.g. `<invoke name=\"...\">`). That syntax is NOT executed — " \
+                   "it was rendered to the user as raw text. " \
+                   "Re-issue the call using the structured tool_calls field provided by the runtime, " \
+                   "or, if no tool is needed, just answer normally.",
+          system_injected: true
+        })
+        :retry
+      end
+    end
+  end
+end

data/lib/clacky/agent/message_compressor.rb

@@ -39,10 +39,14 @@ module Clacky
 
       REQUIRED RESPONSE FORMAT:
       First output a <topics> line listing 3-6 key topic phrases (comma-separated, concise).
+      Then output a <continues_previous> line: "true" if this conversation is a direct
+      continuation of the SAME task/topic as the PREVIOUS chunk shown below, "false" if it
+      has moved on to a different task or topic. If there is no previous chunk, output "false".
       Then output the full summary wrapped in <summary> tags.
 
       Example format:
       <topics>Rails setup, database config, deploy pipeline, Tailwind CSS</topics>
+      <continues_previous>false</continues_previous>
       <summary>
       ...full summary text...
       </summary>
@@ -54,7 +58,8 @@ module Clacky
       - Errors encountered and fixes applied
       - Current work status and pending tasks
 
-      Begin your response NOW. Remember: PURE TEXT only, starting with <topics> then <summary>.
+      Begin your response NOW. Remember: PURE TEXT only, starting with <topics> then
+      <continues_previous> then <summary>.
     PROMPT
 
     def initialize(client, model: nil)
@@ -72,18 +77,25 @@ module Clacky
     #
     # @param messages [Array<Hash>] Original conversation messages
     # @param recent_messages [Array<Hash>] Recent messages to keep uncompressed (optional)
+    # @param previous_topics [String, nil] Topics of the most recent chunk on disk,
+    #   shown to the LLM so it can decide whether the current conversation is a
+    #   continuation (drives the <continues_previous> output for chunk merging).
     # @return [Hash] Compression instruction message to insert, or nil if nothing to compress
-    def build_compression_message(messages, recent_messages: [])
+    def build_compression_message(messages, recent_messages: [], previous_topics: nil)
       # Get messages to compress (exclude system message and recent messages)
       messages_to_compress = messages.reject { |m| m[:role] == "system" || recent_messages.include?(m) }
 
       # If nothing to compress, return nil
       return nil if messages_to_compress.empty?
 
-      # Simple compression instruction - LLM can see the history already
-      { 
-        role: "user", 
-        content: COMPRESSION_PROMPT,
+      content = COMPRESSION_PROMPT
+      if previous_topics && !previous_topics.strip.empty?
+        content = "#{COMPRESSION_PROMPT}\n\nPREVIOUS CHUNK TOPICS (for <continues_previous> judgement): #{previous_topics}"
+      end
+
+      {
+        role: "user",
+        content: content,
         system_injected: true
       }
     end
@@ -142,6 +154,15 @@ module Clacky
       m ? m[1].strip : nil
     end
 
+    # Parse the <continues_previous> tag. Returns true only when the LLM
+    # explicitly says "true"; missing tag or any other value → false.
+    # This conservative default ensures we never merge unless the model is sure.
+    def parse_continues_previous(content)
+      return false if content.nil? || content.to_s.empty?
+      m = content.to_s.match(/<continues_previous>(.*?)<\/continues_previous>/m)
+      m ? m[1].strip.downcase == "true" : false
+    end
+
     def parse_compressed_result(result, chunk_path: nil, topics: nil, previous_chunks: [])
       # Return the compressed result as a single user message (role: "user").
       #
@@ -171,8 +192,11 @@ module Clacky
       if content.empty?
         []
       else
-        # Strip out the <topics> block — it's metadata for the chunk file, not for AI context
-        content_without_topics = content.gsub(/<topics>.*?<\/topics>\n*/m, "").strip
+        # Strip out the <topics> and <continues_previous> blocks — they're
+        # metadata for chunk handling, not for AI context.
+        content_without_topics = content.gsub(/<topics>.*?<\/topics>\n*/m, "")
+                                        .gsub(/<continues_previous>.*?<\/continues_previous>\n*/m, "")
+                                        .strip
 
         # Build previous chunks index section — links to older chunk files so the AI
         # can find earlier conversations without keeping all prior compressed_summary

data/lib/clacky/agent/message_compressor_helper.rb

@@ -193,8 +193,18 @@ module Clacky
         recent_messages = get_recent_messages_with_tool_pairs(all_messages, target_recent_count)
         recent_messages = [] if recent_messages.nil?
 
+        # Surface the most recent chunk's topics so the compression LLM can judge
+        # whether this conversation continues the same task (drives chunk merging).
+        previous_topics = nil
+        if @session_id && @created_at
+          latest = session_manager.chunks_for_current(@session_id, @created_at).last
+          previous_topics = latest && latest[:topics]
+        end
+
         # Build compression instruction message (to be inserted into conversation)
-        compression_message = @message_compressor.build_compression_message(all_messages, recent_messages: recent_messages)
+        compression_message = @message_compressor.build_compression_message(
+          all_messages, recent_messages: recent_messages, previous_topics: previous_topics
+        )
 
         return nil if compression_message.nil?
 
@@ -242,25 +252,52 @@ module Clacky
         # all chunk file I/O (naming, writing, discovery) — we just ask it.
         sm = session_manager
         existing_chunks = sm.chunks_for_current(@session_id, @created_at)
-        chunk_index = sm.next_chunk_index(@session_id, @created_at)
 
         # Extract topics from the LLM response to store in both the chunk MD front
         # matter and the compressed_summary message hash (for future chunk indexing).
         topics = @message_compressor.parse_topics(compressed_content)
 
-        chunk_path = save_compressed_chunk(
-          original_messages,
-          compression_context[:recent_messages],
-          chunk_index: chunk_index,
-          compression_level: compression_context[:compression_level],
-          topics: topics
-        )
+        # Decide whether to MERGE into the previous chunk or create a NEW one.
+        # The LLM judges (via <continues_previous>) whether this conversation is a
+        # direct continuation of the previous chunk's task. Merging avoids tiny
+        # fragmented chunks (e.g. a long task compressed mid-flight into 2-message
+        # chunks) that pollute the topics index and degrade recall.
+        latest_chunk = existing_chunks.last
+        continues = latest_chunk && @message_compressor.parse_continues_previous(compressed_content)
+
+        if continues
+          chunk_path = merge_into_previous_chunk(
+            latest_chunk,
+            original_messages,
+            compression_context[:recent_messages],
+            compression_level: compression_context[:compression_level],
+            topics: topics
+          )
+          # Fallback to new chunk if the merge could not be performed.
+          chunk_path ||= save_compressed_chunk(
+            original_messages, compression_context[:recent_messages],
+            chunk_index: sm.next_chunk_index(@session_id, @created_at),
+            compression_level: compression_context[:compression_level], topics: topics
+          )
+          # The merged chunk is the current chunk — exclude it from previous_chunks.
+          index_chunks = existing_chunks.reject { |c| c[:index] == latest_chunk[:index] }
+        else
+          chunk_index = sm.next_chunk_index(@session_id, @created_at)
+          chunk_path = save_compressed_chunk(
+            original_messages,
+            compression_context[:recent_messages],
+            chunk_index: chunk_index,
+            compression_level: compression_context[:compression_level],
+            topics: topics
+          )
+          index_chunks = existing_chunks
+        end
 
         # Build previous_chunks index from the disk-discovered chunks (already
         # sorted by index ascending). This gives the new summary a complete
         # chronological index of all older archives so the AI can recall any
         # past chunk via file_reader, not just the most recent one.
-        previous_chunks = existing_chunks.map do |c|
+        previous_chunks = index_chunks.map do |c|
           { basename: c[:basename], path: c[:path], topics: c[:topics] }
         end
 
@@ -483,6 +520,62 @@ module Clacky
         nil
       end
 
+      # Merge the current batch of compressed messages INTO an existing chunk
+      # (overwrite-in-place, same chunk index). Used when the LLM judged this
+      # conversation as a continuation of the previous chunk's task. Keeps the
+      # archive on a single, growing, well-formed chunk instead of fragmenting
+      # into tiny standalone files that pollute the topics index.
+      #
+      # Every write hits disk immediately, so a crash never loses archived
+      # messages — there is no in-memory buffering.
+      #
+      # @param prev_chunk [Hash] disk-discovered chunk hash ({ index:, path:, topics: })
+      # @return [String, nil] the chunk path on success, nil if merge not possible
+      def merge_into_previous_chunk(prev_chunk, original_messages, recent_messages, compression_level:, topics: nil)
+        return nil unless @session_id && @created_at
+
+        recent_set = recent_messages.to_a
+        messages_to_archive = original_messages.reject do |m|
+          m[:role] == "system" || m[:system_injected] || m[:compressed_summary] || recent_set.include?(m)
+        end
+        return nil if messages_to_archive.empty?
+
+        sm = session_manager
+        raw = sm.read_chunk(prev_chunk[:path])
+        return nil unless raw
+
+        fm, body = sm.split_chunk_md(raw)
+        return nil unless fm
+
+        new_sections = render_message_sections(messages_to_archive)
+
+        fm["compression_level"] = compression_level.to_s
+        fm["archived_at"]       = Time.now.iso8601
+        fm["message_count"]     = (fm["message_count"].to_i + messages_to_archive.size).to_s
+        fm["merged_count"]      = (fm.fetch("merged_count", "1").to_i + 1).to_s
+        fm["topics"]            = merge_topics(fm["topics"], topics)
+
+        lines = ["---"]
+        fm.each { |k, v| lines << "#{k}: #{v}" }
+        lines << "---"
+        lines << body.rstrip
+        lines << ""
+        lines.concat(new_sections)
+
+        sm.write_chunk(@session_id, @created_at, prev_chunk[:index], lines.join("\n"))
+      rescue => e
+        @ui&.log("Failed to merge chunk MD: #{e.message}", level: :warn)
+        nil
+      end
+
+      # Union two comma-separated topic strings, preserving order, dropping dups.
+      private def merge_topics(existing, incoming)
+        a = (existing || "").split(/\s*,\s*/).map(&:strip).reject(&:empty?)
+        b = (incoming || "").split(/\s*,\s*/).map(&:strip).reject(&:empty?)
+        merged = (a + b).uniq
+        merged.empty? ? nil : merged.join(", ")
+      end
+
       # Build markdown content from a list of messages
       # @param messages [Array<Hash>] Messages to render
       # @param chunk_index [Integer] Chunk number for metadata
@@ -508,6 +601,15 @@ module Clacky
         lines << "> Use `file_reader` to recall specific details from this conversation."
         lines << ""
 
+        lines.concat(render_message_sections(messages))
+
+        lines.join("\n")
+      end
+
+      # Render messages into chunk MD body sections (no front matter / header).
+      # Shared by build_chunk_md and the chunk-merge path.
+      def render_message_sections(messages)
+        lines = []
         messages.each do |msg|
           role = msg[:role]
           content = msg[:content]
@@ -560,8 +662,7 @@ module Clacky
             lines << ""
           end
         end
-
-        lines.join("\n")
+        lines
       end
 
       # Format message content (handles string or array of content blocks)

data/lib/clacky/agent/session_serializer.rb

@@ -153,7 +153,7 @@ module Clacky
       # @param status [Symbol] Status of the last task: :success, :error, or :interrupted
       # @param error_message [String] Error message if status is :error
       # @return [Hash] Session data ready for serialization
-      def to_session_data(status: :success, error_message: nil, updated_at: nil, preserve_updated_at: false)
+      def to_session_data(status: :success, error_message: nil, raw_message: nil, updated_at: nil, preserve_updated_at: false)
         stats_data = {
           total_tasks: @total_tasks,
           total_iterations: @iterations,
@@ -167,7 +167,8 @@ module Clacky
         }
 
         # Add error message if status is error
-        stats_data[:last_error] = error_message if status == :error && error_message
+        stats_data[:last_error]     = error_message if status == :error && error_message
+        stats_data[:last_error_raw] = raw_message   if status == :error && raw_message
 
         {
           session_id: @session_id,

data/lib/clacky/agent/tool_executor.rb

@@ -254,18 +254,6 @@ module Clacky
         }
       end
 
-      # Show countdown before auto-executing in auto_approve mode.
-      # Gives the user time to see what's happening and Ctrl+C to cancel.
-      # @param seconds [Integer] Countdown duration
-      private def auto_approve_countdown(seconds: 10)
-        return unless @ui
-
-        seconds.downto(1) do |remaining|
-          @ui.show_info("  Auto-executing in #{remaining}s... (Ctrl+C to cancel)", prefix_newline: false)
-          sleep 1
-        end
-      end
-
       # Check if a tool is potentially slow and should show progress
       # @param tool_name [String] Name of the tool
       # @param args [Hash] Tool arguments

data/lib/clacky/agent.rb

@@ -5,6 +5,7 @@ require "json"
 require "cgi"
 require "tty-prompt"
 require "set"
+require_relative "null_ui_controller"
 require_relative "utils/arguments_parser"
 require_relative "utils/file_processor"
 require_relative "utils/environment_detector"
@@ -23,6 +24,7 @@ require_relative "agent/memory_updater"
 require_relative "agent/skill_evolution"
 require_relative "agent/skill_reflector"
 require_relative "agent/skill_auto_creator"
+require_relative "agent/fake_tool_call_detector"
 
 module Clacky
   class Agent
@@ -39,6 +41,7 @@ module Clacky
     include SkillEvolution
     include SkillReflector
     include SkillAutoCreator
+    include FakeToolCallDetector
 
     attr_reader :session_id, :name, :history, :iterations, :total_cost, :working_dir, :created_at, :total_tasks, :todos,
                 :cache_stats, :cost_source, :ui, :skill_loader, :agent_profile,
@@ -274,6 +277,7 @@ module Clacky
       else
         @start_time = Time.now
         @task_truncation_count = 0  # Reset truncation counter for each task
+        @task_fake_tool_call_count = 0  # Reset fake tool-call counter for each task
         @task_timeout_hint_injected = false  # Reset read-timeout hint injection (see LlmCaller)
         @task_upstream_truncation_hint_injected = false  # Reset upstream-truncation hint injection (see LlmCaller)
         @task_cost_source = :estimated  # Reset for new task
@@ -488,6 +492,18 @@ module Clacky
             Clacky::Logger.warn("agent.think_response.log_failed", error: e.message)
           end
 
+          # Detect fake tool-calls written as XML/text in content (model bug
+          # where it emits `<invoke name="...">` instead of using the
+          # structured tool_calls field). Only triggers when tool_calls is
+          # absent — a real call alongside stray XML is not our problem here.
+          if (response[:tool_calls].nil? || response[:tool_calls].empty?) &&
+             fake_tool_call_in_content?(response[:content])
+            case handle_fake_tool_call(response)
+            when :retry then next
+            when :stop then break
+            end
+          end
+
           # Check if done (no more tool calls needed).
           #
           # Defensive rule: we ONLY exit on empty/missing tool_calls.
@@ -667,9 +683,6 @@ module Clacky
         raise
       ensure
         # Safety net: ensure any lingering progress spinner is stopped.
-        # Normal paths close their own spinners; this guards against exceptions
-        # raised between a progress slot's active/done pair.
-        Clacky::Logger.warn("[ph_debug] agent_run_ensure")
         @ui&.show_progress(phase: "done")
 
         # Fire-and-forget telemetry after every agent run.
@@ -949,10 +962,9 @@ module Clacky
         end
 
         # Special handling for request_user_feedback
-        if call[:name] == "request_user_feedback"
-          # In auto_approve mode, give user time to see and cancel before auto-answering
-          auto_approve_countdown(seconds: 10) if @config.permission_mode == :auto_approve
-        else
+        # The interactive countdown (auto_approve) is handled after the tool
+        # executes, once the question itself has been rendered to the user.
+        unless call[:name] == "request_user_feedback"
           @ui&.show_tool_call(call[:name], redact_tool_args(call[:arguments]))
         end
 
@@ -1037,11 +1049,26 @@ module Clacky
             @ui&.show_tool_call(call[:name], call[:arguments])
 
             if @config.permission_mode == :auto_approve
-              # auto_approve means no human is watching (unattended/scheduled tasks).
-              # Inject an auto_reply so the LLM makes a reasonable decision and keeps going.
-              result = result.merge(
-                auto_reply: "No user is available. Please make a reasonable decision based on the context and continue."
-              )
+              # auto_approve means the agent runs unattended by default, but a
+              # human MAY be watching the terminal. Show a short interactive
+              # countdown: if the user steps in, hand control over and wait for
+              # their answer; otherwise auto-decide and keep going.
+              countdown = @ui&.request_feedback_with_countdown(seconds: 10)
+
+              if @ui.nil? || countdown == :timeout
+                result = result.merge(
+                  auto_reply: "No user is available. Please make a reasonable decision based on the context and continue."
+                )
+              elsif countdown.is_a?(String) && !countdown.strip.empty?
+                # User stepped in and typed an answer right away. Route it through
+                # the denied+feedback path so the agent responds to it immediately
+                # instead of breaking and forcing the user to re-type.
+                denied = true
+                feedback = countdown
+              else
+                # User stepped in but gave no text — hand control back to the CLI.
+                awaiting_feedback = true
+              end
             else
               # confirm_all / confirm_safes — a human is present, truly wait for user input.
               awaiting_feedback = true
@@ -1288,6 +1315,41 @@ module Clacky
       @tool_registry.register(Tools::Browser.new)
     end
 
+    # Run a one-off task on a forked subagent and return its final reply text,
+    # WITHOUT mutating this (parent) agent's history. Used by extensions that
+    # need a side analysis (e.g. meeting annotate) which must reuse the parent's
+    # cached context + unified billing, but must NOT pollute the main conversation.
+    #
+    # The subagent deep-clones the parent history (cache prefix + task state), runs
+    # to completion, and is discarded. Only the cost is merged back into the parent.
+    #
+    # @param task [String] The task/prompt for the subagent
+    # @param model [String, nil] Model name ("lite" for the lite companion, nil = current)
+    # @param forbidden_tools [Array<String>] Tool names to block at runtime
+    # @return [String] Subagent's final assistant reply (empty string if none)
+    def run_detached(task, model: nil, forbidden_tools: [])
+      subagent = fork_subagent(
+        model: model,
+        forbidden_tools: forbidden_tools,
+        system_prompt_suffix: "You are running a one-off background analysis. Do the task and return only the requested output. Do not ask follow-up questions."
+      )
+      # Detached runs must stay invisible: a real UI (e.g. WebUIController bound
+      # to the parent's session_id) would broadcast the subagent's raw output
+      # into the parent chat transcript. Swap in a no-op UI so nothing leaks.
+      subagent.instance_variable_set(:@ui, NullUIController.new)
+      parent_count = subagent.instance_variable_get(:@parent_message_count) || 0
+      result = subagent.run(task)
+
+      @total_cost += result[:total_cost_usd] || 0.0
+
+      new_messages = subagent.history.to_a[parent_count..] || []
+      new_messages
+        .reverse
+        .find { |m| m[:role] == "assistant" && m[:content] && !m[:content].to_s.empty? }
+        &.dig(:content)
+        .to_s
+    end
+
     # Fork a subagent with specified configuration
     # The subagent inherits all messages and tools from parent agent
     # Tools are not modified (for cache reuse), but forbidden tools are blocked at runtime via hooks

data/lib/clacky/api_extension.rb

@@ -238,6 +238,87 @@ module Clacky
       @http_server&.instance_variable_get(:@agent_config)
     end
 
+    def registry
+      @http_server&.instance_variable_get(:@registry)
+    end
+
+    # Create a brand-new session and optionally kick off its first task.
+    # Returns the new session_id. When a prompt is given, the task is
+    # submitted immediately (the session starts running); display_message
+    # controls the user-facing bubble shown in place of the raw prompt.
+    def create_session(name: nil, prompt: nil, working_dir: nil, profile: "general",
+                       source: :manual, display_message: nil)
+      error!("server not ready", status: 503) unless @http_server
+
+      session_id = @http_server.send(
+        :build_session,
+        name: name,
+        working_dir: working_dir,
+        profile: profile,
+        source: source
+      )
+
+      submit_task(session_id, prompt, display_message: display_message) if prompt && !prompt.strip.empty?
+
+      session_id
+    end
+
+    # Submit a prompt to an existing session for execution.
+    # The session must be idle; returns the session_id on success.
+    # Raises Halt (409) if the session is already running.
+    def submit_task(session_id, prompt, display_message: nil)
+      reg = registry
+      error!("server not ready", status: 503) unless reg
+
+      unless reg.exist?(session_id)
+        reg.ensure(session_id)
+        error!("session not found: #{session_id}", status: 404) unless reg.exist?(session_id)
+      end
+
+      session = reg.get(session_id)
+      error!("session is busy", status: 409) if session[:status] == :running
+
+      @http_server.send(:run_session_task, session_id, prompt, display_message: display_message)
+      session_id
+    end
+
+    # Run a one-off side task on an existing session's agent and return its
+    # reply text SYNCHRONOUSLY, without polluting the main conversation.
+    #
+    # Unlike submit_task (which enqueues a turn into the live conversation and
+    # returns immediately), this forks the session's agent — reusing its cached
+    # context and unified billing — runs the task to completion on the fork, and
+    # returns the fork's final reply. The main conversation is never touched.
+    #
+    # Strategy A (parent-busy → skip): if the session is currently running, or the
+    # server is at its concurrency limit, this returns { busy: true } without
+    # running. Callers (e.g. periodic analysis) should treat that as "try later".
+    #
+    # @param session_id [String]
+    # @param prompt [String]
+    # @param model [String, nil] "lite" for the lite companion, nil = current
+    # @param forbidden_tools [Array<String>] tool names blocked in the fork
+    # @return [Hash] { text: "..." } on success, or { busy: true } when skipped
+    def dispatch_to_session(session_id, prompt, model: nil, forbidden_tools: [])
+      reg = registry
+      error!("server not ready", status: 503) unless reg
+
+      unless reg.exist?(session_id)
+        reg.ensure(session_id)
+        error!("session not found: #{session_id}", status: 404) unless reg.exist?(session_id)
+      end
+
+      return { busy: true } if reg.respond_to?(:running_full?) && reg.running_full?
+
+      session = reg.get(session_id)
+      return { busy: true } if session[:status] == :running
+
+      agent = session[:agent]
+      error!("session agent not available", status: 503) unless agent
+
+      { text: agent.run_detached(prompt, model: model, forbidden_tools: forbidden_tools) }
+    end
+
     def server_start_time
       @http_server&.instance_variable_get(:@start_time)
     end

data/lib/clacky/api_extension_loader.rb

@@ -12,15 +12,27 @@ module Clacky
   # isolated: skipped with a logged warning, never aborts the load of others.
   module ApiExtensionLoader
     DEFAULT_DIR  = File.expand_path("~/.clacky/api_ext")
+    BUILTIN_DIR  = File.expand_path("../default_extensions", __FILE__)
     DISABLED_DIR = "_disabled"
 
     Result = Struct.new(:loaded, :skipped, keyword_init: true)
 
     class << self
-      def load_all(dir: DEFAULT_DIR)
+      def load_all(dir: DEFAULT_DIR, builtin: true)
         result = Result.new(loaded: [], skipped: [])
         Clacky::ApiExtension.reset_registry!
 
+        # Load built-in (gem-shipped) extensions first (lowest priority)
+        if builtin && Dir.exist?(BUILTIN_DIR)
+          Dir.glob(File.join(BUILTIN_DIR, "*", "handler.rb")).sort.each do |handler_path|
+            ext_dir = File.dirname(handler_path)
+            ext_id  = File.basename(ext_dir)
+            next if ext_id.start_with?("_")
+            load_one(ext_id, ext_dir, handler_path, result)
+          end
+        end
+
+        # Load user extensions (higher priority — same ext_id overwrites built-in)
         if Dir.exist?(dir)
           Dir.glob(File.join(dir, "*", "handler.rb")).sort.each do |handler_path|
             ext_dir = File.dirname(handler_path)