openclacky 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d36230a47c25a8b5fb04dfc14f9359155489a2539d0a699843e140deed1434ba
-  data.tar.gz: c237725ed637d2d7a852d3624611cca101290e2348e0c6befb2650342550ec03
+  metadata.gz: 448b47d4336764c1646147f9b86fc04f8bad84a34565b9b67cbf558000c185bf
+  data.tar.gz: 827ace1367511360cd6586f5a89529b504d31cdce68d5ecd90fadbe92069c2b5
 SHA512:
-  metadata.gz: 89c65d848c67dff3ed63ae70cd6a0539a7a8068682d72009b34741ea09c44749f5fa05c5839bc9c02c5c499709c8e5bce321165561bdbf8a43500539d1e4b21c
-  data.tar.gz: 74ebac898a16e090481c8ba423ac7c2d9cafe918f09cdc87066b54c911034b941c713650d24aaa8d71c627c48d3c8c56a780c2ffa6e717448e4712cdd5ca9512
+  metadata.gz: 667591fbe92e0e4d01de03cd1e9924ff595a1a11fa5196a7b338675366e37445d7cfe02844fc6bd1eb768ab54134d56195a9573fb95dc20c57d448429bcfb8d2
+  data.tar.gz: b324a9f5161eb7574f846736c200341fb2f4db39786f3bd5c2210c178a8c2ed115a520251e36da4ed82572ea6ebf0e88d1072a51536a817169d0838ae86d7dea

data/CHANGELOG.md

@@ -5,7 +5,22 @@ 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.0.2] - 2026-05-07
+## [1.0.3] - 2026-05-09
+
+### Added
+- **Channel send command — push messages from CLI/agent to IM channels.** New `clacky channel send` CLI command and full outbound channel pipeline. The agent can now actively reach out to users on Feishu/WeCom/WeChat (e.g. for cron tasks or background completions) instead of only replying. Includes a new `ChannelManager` for routing, multi-master server discovery, and proper `chat_id` extraction for outbound messages. (#73)
+- **`--model` flag to override the model per invocation.** Run any one-off command with a different model without changing config: `clacky --model gpt-4o-mini "..."`. Useful for quick comparisons or routing specific tasks to cheaper/faster models. (#76)
+- **Fuzzy tool-name resolution for cross-model compatibility.** When a model emits a slightly off tool name (e.g. `read_file` vs `file_reader`, case mismatches, or hyphen/underscore differences), the agent now resolves it to the closest registered tool instead of erroring out. Significantly improves reliability when switching between Claude, GPT, and other providers. (#78)
+- **Context overflow auto-recovery.** When an upstream LLM call hits a context-length error, the agent now detects it via `LlmCaller`'s error classification and automatically compresses message history to retry — instead of bubbling a hard error to the user. Backed by 175 new error-detection and 169 new recovery specs.
+- **Refined session list UI with SVG icons.** Reworked sidebar session list with crisp SVG icons and tightened styling for a more polished look. (#83)
+
+### Fixed
+- **EPIPE crashes when stdout/stderr is closed.** Wrapped server I/O in `EpipeSafeIO` so the master/web server no longer crashes when its output stream goes away (e.g. terminal closed, pipe broken). Covered by 193 new specs.
+- **Duplicate `$` in CLI completion line.** Removed the stray dollar sign that appeared at the end of completed commands. (C-5583, #86)
+- **Session list scroll jump on "load more".** The list no longer snaps back to the top when older sessions are paginated in. (C-5568, #85)
+- Reverted an earlier message line-wrap change (#74) that caused regressions; will be revisited. (#84)
+
+
 
 ### Added
 - **Multi-region provider endpoints.** Providers can now expose multiple endpoint variants (e.g. global vs. CN-optimized Anthropic), and you can switch between them from both the onboarding flow and the Settings page. Bundled with updated model pricing data so cost estimates stay accurate across regions. (#67)

data/lib/clacky/agent/llm_caller.rb

@@ -79,6 +79,14 @@ module Clacky
         # the error is something else and we let it propagate.
         force_reasoning_content_pad = false
         thinking_retry_attempted = false
+        # One-shot flag for context-overflow recovery. When the server complains
+        # the input exceeds the model's context window, we run a forced
+        # compression with pull_back_from_tail: 1 (preserves the model's
+        # two-checkpoint prompt cache) and retry the original request once.
+        # We retry at most once — if still overflowing afterward, the issue is
+        # something else (e.g. tool schemas alone exceed the window) and we let
+        # the error propagate.
+        context_overflow_retry_attempted = false
 
         begin
           begin
@@ -220,6 +228,55 @@ module Clacky
         end
 
         rescue Clacky::BadRequestError => e
+          # One-shot recovery for "context too long" errors. The model's
+          # context window is exceeded by the current history+tools+system
+          # prompt. We run a forced compression with pull_back_from_tail: 1
+          # (preserves the two-checkpoint prompt cache so the compression
+          # call itself still hits cache#A on the second-to-last position),
+          # then retry the original request once.
+          if !context_overflow_retry_attempted &&
+              !@compressing_for_overflow &&
+              context_too_long_error?(e) &&
+              respond_to?(:compress_messages_if_needed, true)
+            context_overflow_retry_attempted = true
+            Clacky::Logger.info(
+              "[context-overflow] caught BadRequestError, attempting forced compression with pull-back",
+              error_message: e.message[0, 200],
+              history_size: @history.size,
+              previous_total_tokens: @previous_total_tokens
+            )
+            # Layer 1: standard cache-preserving compression (pull_back: 1).
+            # Handles 99% of real overflow cases (newest message tipped the
+            # request just past the window).
+            if perform_context_overflow_compression(mode: :standard)
+              retry
+            end
+
+            # Layer 2: aggressive fallback. The Layer 1 compression call
+            # itself overflowed — happens when a single newly-appended
+            # message is enormous (huge tool_result, pasted file, etc.) so
+            # popping just K=1 didn't bring the request below the window.
+            # Pop ~half the history this time; sacrifices prompt cache to
+            # guarantee the compression call fits.
+            Clacky::Logger.warn(
+              "[context-overflow] standard compression failed, escalating to aggressive mode"
+            )
+            if perform_context_overflow_compression(mode: :aggressive)
+              retry
+            end
+
+            # Both layers exhausted. Let the original error propagate so the
+            # user sees the underlying provider message. This should be
+            # extremely rare — would require both halves of the history to
+            # individually exceed the window, which is essentially impossible
+            # under the "previous turn succeeded" invariant.
+            Clacky::Logger.error(
+              "[context-overflow] both standard and aggressive compression failed; " \
+              "propagating original error"
+            )
+            raise
+          end
+
           # One-shot recovery for thinking-mode providers (DeepSeek V4, Kimi K2)
           # that require every assistant message in the history to carry a
           # reasoning_content field. The history-evidence heuristic in
@@ -342,6 +399,101 @@ module Clacky
         )
       end
 
+      # Run a forced compression to recover from a context-overflow error.
+      # Called by the BadRequestError rescue when context_too_long_error?
+      # returns true.
+      #
+      # Two-layer defence:
+      # ────────────────────────────────────────────────────────────────────
+      # Layer 1 (mode: :standard, default) — preserves prompt cache.
+      #   Pop K=1 message from @history tail, then run compression. This
+      #   frees just enough token budget for the compression LLM call
+      #   itself to fit, while preserving the model's two-checkpoint prompt
+      #   cache (cache#A at second-to-last position is still hit). The
+      #   popped message is reattached to the rebuilt history's tail by
+      #   handle_compression_response, so recent task progress is not lost.
+      #   Handles 99% of real-world cases where overflow is caused by the
+      #   newest message pushing total just past the window.
+      #
+      # Layer 2 (mode: :aggressive) — sacrifices prompt cache to survive.
+      #   Pop ~half the history (capped) from the tail. This dramatically
+      #   shrinks the compression call's input regardless of how big any
+      #   single message is. Used as a fallback when Layer 1 itself raises
+      #   context_too_long — i.e. a single newly-appended message is so
+      #   large (e.g. >50K-token tool_result, pasted huge file) that even
+      #   removing it didn't bring the request under the window, OR the
+      #   popped message was small but earlier history grew past the limit.
+      #   Pulled-back messages are still reattached after compression so no
+      #   user content is silently dropped.
+      #
+      # @param mode [Symbol] :standard or :aggressive
+      # @return [Boolean] true if compression succeeded (caller should retry
+      #   the original request), false if compression was unable to run
+      #   (compression disabled, history too short, etc.) or itself failed
+      #   — caller decides whether to escalate to the next layer or
+      #   propagate the original error.
+      private def perform_context_overflow_compression(mode: :standard)
+        return false unless respond_to?(:compress_messages_if_needed, true)
+
+        # Compute pull-back count.
+        # Standard: K=1 (cache-preserving).
+        # Aggressive: pop ~half the history, but never less than 4 and never
+        #   more than (history_size - 2) so we always keep system + at least
+        #   one recent message. Capped at 64 to bound the worst case (an
+        #   enormous history that should never realistically occur).
+        pull_back =
+          if mode == :aggressive
+            half = @history.size / 2
+            [[half, 4].max, [@history.size - 2, 64].min].min
+          else
+            1
+          end
+
+        @compressing_for_overflow = true
+        compression_context = nil
+
+        begin
+          compression_context = compress_messages_if_needed(
+            force: true,
+            pull_back_from_tail: pull_back
+          )
+          return false if compression_context.nil?
+
+          compression_message = compression_context[:compression_message]
+          @history.append(compression_message)
+
+          response = call_llm  # recursive — guarded by @compressing_for_overflow
+          handle_compression_response(response, compression_context)
+          Clacky::Logger.info(
+            "[context-overflow] compression succeeded",
+            mode: mode,
+            pull_back: pull_back
+          )
+          true
+        rescue => e
+          # Compression failed mid-flight. Restore @history to a sensible state:
+          # roll back the compression instruction we appended, and re-append the
+          # pulled-back messages so the user's recent work isn't silently lost.
+          if compression_context
+            cm = compression_context[:compression_message]
+            @history.rollback_before(cm) if cm
+            (compression_context[:pulled_back_messages] || []).each do |m|
+              @history.append(m)
+            end
+          end
+          Clacky::Logger.warn(
+            "[context-overflow] compression failed during overflow recovery",
+            mode: mode,
+            pull_back: pull_back,
+            error_class: e.class.name,
+            error_message: e.message[0, 200]
+          )
+          false
+        ensure
+          @compressing_for_overflow = false
+        end
+      end
+
       # True when a 400 BadRequestError is specifically about a missing
       # reasoning_content field in thinking mode (DeepSeek V4, Kimi K2 thinking).
       # We require TWO distinct substrings to avoid false positives — a generic
@@ -358,6 +510,72 @@ module Clacky
            msg.include?("must be provided"))
       end
 
+      # True when a 400 BadRequestError indicates the request exceeded the
+      # model's context window (i.e. the conversation history is too long).
+      #
+      # We deliberately favour broad detection over narrow precision:
+      #   - False positive cost: one extra (no-op) compression cycle.
+      #   - False negative cost: user is stuck — every retry hits the same wall.
+      # So the matcher is intentionally permissive.
+      #
+      # Coverage (verified against real production error strings):
+      #
+      #   OpenAI:
+      #     "This model's maximum context length is 128000 tokens. However
+      #      you requested ... Please reduce the length of the messages."
+      #     error.code == "context_length_exceeded"
+      #
+      #   Anthropic:
+      #     "prompt is too long: 218849 tokens > 200000 maximum"
+      #
+      #   Qwen / Alibaba (DashScope):
+      #     "You passed 117345 input tokens and requested 8192 output tokens.
+      #      However the model's context length is only 125536 tokens, resulting
+      #      in a maximum input length of 117344 tokens. Please reduce the length
+      #      of the input prompt. (parameter=input_tokens, value=117345)"
+      #
+      #   Qwen / Alibaba (DashScope) — newer/terser format (qwen3.6 series):
+      #     "InternalError.Algo.InvalidParameter: Range of input length should be [1, 229376]"
+      #
+      #   DeepSeek / Kimi / MiniMax / most OpenAI-compatible relays:
+      #     Variants of OpenAI-style "context length" / "tokens exceeds" wording.
+      #
+      #   Generic gateways (Portkey, OpenRouter):
+      #     "The total number of tokens exceeds the model's maximum context length"
+      private def context_too_long_error?(err)
+        return false unless err.is_a?(Clacky::BadRequestError)
+
+        msg = err.message.to_s.downcase
+
+        # Strong phrases — any one of these is conclusive on its own.
+        # Each phrase is two-or-more semantic words to avoid single-word noise.
+        strong_phrases = [
+          "context length",                 # OpenAI / Qwen / many compat APIs
+          "context_length_exceeded",        # OpenAI error.code
+          "maximum context",                # OpenAI variant
+          "maximum input length",           # Qwen
+          "prompt is too long",             # Anthropic
+          "input is too long",              # Anthropic-compat relays
+          "exceeds the maximum context",    # Portkey & generic gateways
+          "exceeds the model's context",    # Generic
+          "exceeds the model's maximum",    # Generic
+          "reduce the length of the input", # Qwen action hint
+          "reduce the length of the messages", # OpenAI action hint
+          "reduce the length of your",      # Generic action hint
+          "reduce the length of the prompt", # Generic action hint
+          "range of input length"           # Qwen DashScope qwen3.6+ terse format
+        ]
+        return true if strong_phrases.any? { |p| msg.include?(p) }
+
+        # Pattern 1: Anthropic-style "<N> tokens > <N> maximum"
+        return true if msg =~ /\d+\s*tokens?\s*>\s*\d+/
+
+        # Pattern 2: Qwen-style structured field "parameter=input_tokens"
+        return true if msg.include?("parameter=input_tokens")
+
+        false
+      end
+
       # Detect upstream tool-call truncation and raise UpstreamTruncatedError
       # so the standard RetryableError rescue (with fallback model support)
       # handles retry identically to 5xx/429.

data/lib/clacky/agent/message_compressor.rb

@@ -93,8 +93,13 @@ module Clacky
     # @param original_messages [Array<Hash>] Original messages before compression
     # @param recent_messages [Array<Hash>] Recent messages to preserve
     # @param chunk_path [String, nil] Path to the archived chunk MD file (if saved)
-    # @return [Array<Hash>] Rebuilt message list: system + compressed + recent
-    def rebuild_with_compression(compressed_content, original_messages:, recent_messages:, chunk_path: nil, topics: nil, previous_chunks: [])
+    # @param pulled_back_messages [Array<Hash>] Messages temporarily popped from the
+    #   tail of @history before the compression LLM call (to free up token budget so
+    #   the compression call itself doesn't overflow context). These are NOT discarded —
+    #   they are reattached to the tail of the rebuilt history so recent task progress
+    #   is preserved. Default: [] (normal compression path doesn't need this).
+    # @return [Array<Hash>] Rebuilt message list: system + compressed + recent + pulled_back
+    def rebuild_with_compression(compressed_content, original_messages:, recent_messages:, chunk_path: nil, topics: nil, previous_chunks: [], pulled_back_messages: [])
       # Find and preserve system message
       system_msg = original_messages.find { |m| m[:role] == "system" }
 
@@ -112,13 +117,19 @@ module Clacky
         raise "LLM compression failed: unable to parse compressed messages"
       end
 
-      # Return system message + compressed messages + recent messages.
+      # Return system message + compressed messages + recent messages + pulled_back messages.
       # Strip any system messages from recent_messages as a safety net —
       # get_recent_messages_with_tool_pairs already excludes them, but this
       # guard ensures we never end up with duplicate system prompts even if
       # the caller passes an unfiltered list.
+      #
+      # pulled_back_messages: messages that were temporarily popped from the tail
+      # of @history before the compression LLM call (to free up token budget so
+      # the compression call itself doesn't overflow context). They are reattached
+      # here to preserve recent task progress.
       safe_recent = recent_messages.reject { |m| m[:role] == "system" }
-      [system_msg, *parsed_messages, *safe_recent].compact
+      safe_pulled_back = pulled_back_messages.reject { |m| m[:role] == "system" }
+      [system_msg, *parsed_messages, *safe_recent, *safe_pulled_back].compact
     end
 
 

data/lib/clacky/agent/message_compressor_helper.rb

@@ -103,8 +103,24 @@ module Clacky
 
       # Check if compression is needed and return compression context
       # @param force [Boolean] Force compression even if thresholds not met
+      # @param pull_back_from_tail [Integer] Number of messages to temporarily pop
+      #   from the tail of history before building the compression instruction.
+      #   Used by the context-overflow recovery path: when the current history
+      #   is already at/over the model's context window, we cannot append even
+      #   a small compression instruction without overflowing. Popping K messages
+      #   from the tail frees up token budget for the compression call itself.
+      #
+      #   Cache-preservation note: thanks to the model's two-checkpoint prompt
+      #   cache (cache#A at second-to-last, cache#B at last), pulling back K=1
+      #   message keeps cache#A intact — the compression LLM call still hits the
+      #   cached prefix [system, m1..m(N-1)]. K>=2 sacrifices cache hits but is
+      #   only used as fallback when one message isn't enough headroom.
+      #
+      #   The popped messages are NOT discarded — they ride along in the
+      #   returned context and are reattached to the rebuilt history's tail by
+      #   handle_compression_response, so recent task progress is preserved.
       # @return [Hash, nil] Compression context or nil if not needed
-      def compress_messages_if_needed(force: false)
+      def compress_messages_if_needed(force: false, pull_back_from_tail: 0)
         # Check if compression is enabled
         return nil unless @config.enable_compression
 
@@ -148,6 +164,27 @@ module Clacky
 
         # Get the most recent N messages, ensuring tool_calls/tool results pairs are kept together
         all_messages = @history.to_a
+
+        # Pull back K messages from the tail (context-overflow recovery path).
+        # We *physically* remove them from @history so the next call_llm
+        # (which reads @history.to_api) doesn't include them in the prompt.
+        # They will be reattached to the rebuilt history's tail by
+        # handle_compression_response after compression succeeds. If compression
+        # fails, the caller is responsible for restoring them via the returned
+        # context (rollback path).
+        pulled_back_messages = []
+        if pull_back_from_tail > 0
+          k = [pull_back_from_tail, all_messages.size - 1].min  # never pop the system message
+          k.times do
+            popped = @history.pop_last
+            pulled_back_messages.unshift(popped) if popped
+          end
+          # Recompute all_messages from the now-shrunk history so downstream
+          # logic (recent_messages selection, build_compression_message) sees
+          # the post-pop view.
+          all_messages = @history.to_a
+        end
+
         recent_messages = get_recent_messages_with_tool_pairs(all_messages, target_recent_count)
         recent_messages = [] if recent_messages.nil?
 
@@ -160,6 +197,7 @@ module Clacky
         {
           compression_message: compression_message,
           recent_messages: recent_messages,
+          pulled_back_messages: pulled_back_messages,
           original_token_count: total_tokens,
           original_message_count: @history.size,
           compression_level: @compression_level
@@ -227,7 +265,8 @@ module Clacky
           recent_messages: compression_context[:recent_messages],
           chunk_path: chunk_path,
           topics: topics,
-          previous_chunks: previous_chunks
+          previous_chunks: previous_chunks,
+          pulled_back_messages: compression_context[:pulled_back_messages] || []
         ))
 
         # Reset to the estimated size of the rebuilt (small) history.

data/lib/clacky/agent/tool_registry.rb

@@ -2,18 +2,127 @@
 
 module Clacky
   class ToolRegistry
+    # Common aliases that LLMs frequently use instead of the registered tool names.
+    # Keys are downcased aliases; values are the canonical registered names.
+    TOOL_ALIASES = {
+      # file_reader aliases
+      "read" => "file_reader",
+      "read_file" => "file_reader",
+      "filereader" => "file_reader",
+      "file_read" => "file_reader",
+      "cat" => "file_reader",
+      # write aliases
+      "write_file" => "write",
+      "create_file" => "write",
+      "file_write" => "write",
+      # edit aliases
+      "file_edit" => "edit",
+      "replace" => "edit",
+      "replace_in_file" => "edit",
+      "str_replace" => "edit",
+      # terminal aliases
+      "shell" => "terminal",
+      "bash" => "terminal",
+      "exec" => "terminal",
+      "execute" => "terminal",
+      "run_command" => "terminal",
+      "run" => "terminal",
+      "command" => "terminal",
+      # web_search aliases
+      "search" => "web_search",
+      "websearch" => "web_search",
+      "internet_search" => "web_search",
+      "online_search" => "web_search",
+      # web_fetch aliases
+      "fetch" => "web_fetch",
+      "webfetch" => "web_fetch",
+      "browse" => "web_fetch",
+      "url_fetch" => "web_fetch",
+      "http_get" => "web_fetch",
+      # grep aliases
+      "search_files" => "grep",
+      "search_in_files" => "grep",
+      "find_in_files" => "grep",
+      "search_code" => "grep",
+      # glob aliases
+      "find_files" => "glob",
+      "list_files" => "glob",
+      "file_glob" => "glob",
+      "search_filenames" => "glob",
+      # invoke_skill aliases
+      "skill" => "invoke_skill",
+      "run_skill" => "invoke_skill",
+      # todo_manager aliases
+      "todo" => "todo_manager",
+      "task_manager" => "todo_manager",
+      # request_user_feedback aliases
+      "ask_user" => "request_user_feedback",
+      "user_feedback" => "request_user_feedback",
+      "ask" => "request_user_feedback",
+      # undo_task aliases
+      "undo" => "undo_task",
+      # redo_task aliases
+      "redo" => "redo_task",
+      # list_tasks aliases
+      "tasks" => "list_tasks",
+      "task_history" => "list_tasks",
+      # trash_manager aliases
+      "trash" => "trash_manager",
+      "delete" => "trash_manager",
+      "rm" => "trash_manager",
+      "remove" => "trash_manager",
+    }.freeze
+
     def initialize
       @tools = {}
+      # Downcased index for case-insensitive lookups
+      @downcased_index = {}
     end
 
     def register(tool)
       @tools[tool.name] = tool
+      @downcased_index[tool.name.downcase] = tool.name
     end
 
     def get(name)
       @tools[name] || raise(Clacky::ToolCallError, "Tool not found: #{name}")
     end
 
+    # Resolve a tool name (possibly misspelt or aliased) to the canonical
+    # registered name.  Resolution order:
+    #   1. Exact match in the registry
+    #   2. Case-insensitive match (e.g. "Read" → "file_reader")
+    #   3. Alias lookup (e.g. "read_file" → "file_reader")
+    # Returns the canonical tool name, or nil if nothing matched.
+    def resolve(name)
+      return name if @tools.key?(name)
+
+      downcased = name.downcase
+
+      # Case-insensitive match
+      if @downcased_index.key?(downcased)
+        return @downcased_index[downcased]
+      end
+
+      # Alias lookup
+      if TOOL_ALIASES.key?(downcased)
+        return TOOL_ALIASES[downcased]
+      end
+
+      # Fuzzy: try underscore / hyphen normalisation (e.g. "file-reader" → "file_reader")
+      normalized = downcased.tr("-", "_")
+      if normalized != downcased
+        if @downcased_index.key?(normalized)
+          return @downcased_index[normalized]
+        end
+        if TOOL_ALIASES.key?(normalized)
+          return TOOL_ALIASES[normalized]
+        end
+      end
+
+      nil
+    end
+
     def all
       @tools.values
     end

data/lib/clacky/agent.rb

@@ -768,6 +768,22 @@ module Clacky
       awaiting_feedback = false
 
       tool_calls.each_with_index do |call, index|
+        # Resolve tool name: handle case-insensitive and common alias mismatches
+        # from different LLM providers (e.g. "read" → "file_reader", "Read" → "file_reader")
+        original_name = call[:name]
+        resolved = @tool_registry.resolve(call[:name])
+        if resolved && resolved != call[:name]
+          @debug_logs << {
+            timestamp: Time.now.iso8601,
+            event: "tool_name_resolved",
+            original: original_name,
+            resolved: resolved
+          }
+          call = call.merge(name: resolved)
+        elsif resolved.nil?
+          # Tool truly not found — let the rescue below handle it with a clear message
+        end
+
         # Hook: before_tool_use
         hook_result = @hooks.trigger(:before_tool_use, call)
         if hook_result[:action] == :deny

data/lib/clacky/agent_config.rb

@@ -426,6 +426,23 @@ module Clacky
       true
     end
 
+    # Switch to a model by its display name (fuzzy match, case-insensitive).
+    #
+    # @param name [String] the model name to search for (e.g. "gpt-5.3-codex")
+    # @return [Boolean] true if switched, false if name not found
+    def switch_model_by_name(name)
+      return false if name.nil? || name.to_s.strip.empty?
+
+      name_str = name.to_s.strip.downcase
+      index = @models.find_index { |m| m["model"].to_s.downcase == name_str }
+      return false if index.nil?
+
+      @current_model_id = @models[index]["id"]
+      @current_model_index = index
+
+      true
+    end
+
     # Set the **global** default model marker (`type: "default"`).
     #
     # This is separate from `switch_model_by_id`:

data/lib/clacky/cli.rb

@@ -41,6 +41,7 @@ module Clacky
 
       Examples:
         $ clacky agent --mode=auto_approve --path /path/to/project
+        $ clacky agent --model gpt-5.3-codex -m "write a hello world script"
     LONGDESC
     option :mode, type: :string, default: "confirm_safes",
            desc: "Permission mode: auto_approve, confirm_safes, confirm_all"
@@ -56,6 +57,7 @@ module Clacky
     option :file,  type: :array, aliases: "-f", desc: "File path(s) to attach (use with -m; supports images and documents)"
     option :image, type: :array, aliases: "-i", desc: "Image file path(s) to attach (alias for --file, kept for compatibility)"
     option :agent, type: :string, default: "coding", desc: "Agent profile to use: coding, general, or any custom profile name (default: coding)"
+    option :model, type: :string, desc: "Override the model to use (by name, e.g. gpt-5.3-codex or deepseek-v4-pro). Uses default model if not specified"
     option :help, type: :boolean, aliases: "-h", desc: "Show this help message"
     def agent
       # Handle help option
@@ -68,8 +70,25 @@ module Clacky
       # Fire-and-forget background thread; never blocks startup.
       Clacky::Telemetry.startup!
 
+      # ── Sibling server discovery ───────────────────────────────────────
+      # Bare-CLI mode does NOT boot an HTTP server, so skills that call
+      # back into /api/* (channels, browser, scheduler) normally can't work.
+      # If the user happens to have a Clacky server running on this machine
+      # (in another terminal or via `clacky server`), auto-wire CLACKY_SERVER_HOST
+      # / CLACKY_SERVER_PORT so those skills can reach it transparently.
+      discover_sibling_server!
+
       agent_config = Clacky::AgentConfig.load
 
+      # Override model if --model option is specified
+      if options[:model]
+        unless agent_config.switch_model_by_name(options[:model])
+          # During early startup @ui may not be ready; use simple error output
+          $stderr.puts "Error: model '#{options[:model]}' not found. Available: #{agent_config.model_names.join(', ')}"
+          exit 1
+        end
+      end
+
       # Handle session listing
       if options[:list]
         list_sessions
@@ -148,6 +167,36 @@ module Clacky
     end
 
     no_commands do
+      # Detect a sibling Clacky server running on this machine and expose its
+      # address to skills via ENV. Runs only in bare-CLI mode (where no server
+      # is booted by this process), and only when the user hasn't already set
+      # CLACKY_SERVER_HOST / CLACKY_SERVER_PORT explicitly.
+      #
+      # Why: skills like `channel-setup` and `browser-setup` call back into
+      # http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/*. In server
+      # mode those vars are injected by HTTPServer#start. In CLI mode they
+      # would be blank, so the skill templates expand to an unreachable URL.
+      #
+      # Discovery is best-effort and non-fatal: if nothing is found we stay
+      # silent and let the skill's own pre-flight check emit a friendly error.
+      private def discover_sibling_server!
+        return if ENV["CLACKY_SERVER_PORT"] && !ENV["CLACKY_SERVER_PORT"].strip.empty?
+
+        require_relative "server/discover"
+        info = Clacky::Server::Discover.find_local
+        return unless info
+
+        ENV["CLACKY_SERVER_HOST"] = info[:host]
+        ENV["CLACKY_SERVER_PORT"] = info[:port].to_s
+        Clacky::Logger.debug(
+          "[CLI] Discovered local server PID=#{info[:pid]} at " \
+          "#{info[:host]}:#{info[:port]} — CLACKY_SERVER_* exported."
+        )
+      rescue StandardError => e
+        # Discovery must never break `clacky agent`.
+        Clacky::Logger.debug("[CLI] discover_sibling_server! failed: #{e.class}: #{e.message}")
+      end
+
       # Handle the `/config` slash command.
       #
       # show_config_modal is a pure UI component — it only mutates @models
@@ -943,6 +992,22 @@ module Clacky
         # Spawned by Master. Inherit the listen socket from the file descriptor
         # passed via CLACKY_INHERIT_FD, and report back to master via CLACKY_MASTER_PID.
         require_relative "server/http_server"
+        require_relative "server/epipe_safe_io"
+
+        # Protect $stdout / $stderr from Errno::EPIPE.
+        #
+        # The worker inherits fd 1/2 from the Master process. If the Master's
+        # stdout pipe ever breaks (e.g. it was launched by an installer or GUI
+        # that has since exited), the next `puts` would raise Errno::EPIPE and
+        # crash the worker — destroying all in-memory sessions, agent loops,
+        # and SSE connections, and looping forever because the respawned
+        # worker inherits the same broken fd.
+        #
+        # In healthy state these wrappers are transparent — output goes to
+        # the user's terminal as usual. On first broken-pipe failure they
+        # silently fall back to /dev/null and the worker stays alive.
+        $stdout = Clacky::Server::EPIPESafeIO.new($stdout)
+        $stderr = Clacky::Server::EPIPESafeIO.new($stderr)
 
         fd         = ENV["CLACKY_INHERIT_FD"].to_i
         master_pid = ENV["CLACKY_MASTER_PID"].to_i