openclacky 1.5.11 → 1.5.13

data/lib/clacky/billing/platform_billing.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "../platform_http_client"
+
+module Clacky
+  module Billing
+    # Authoritative usage data from the OpenClacky platform.
+    #
+    # The gateway records usage against real upstream model ids, while the
+    # client persists the user-facing alias (e.g. "dsk-deepseek-v4-pro" is
+    # stored as "deepseek-v4-pro" upstream). These tables bridge the two so
+    # the billing UI can merge platform data with local data under one name.
+    module PlatformBilling
+      # alias → real upstream model id, used to translate the model filter
+      # before querying the platform API. Vertex ids are preferred as the
+      # "primary" id where the gateway can dispatch an alias two ways.
+      ALIAS_TO_REAL = {
+        # deepseek (dsk-)
+        "dsk-deepseek-v4-pro"              => "deepseek-v4-pro",
+        "dsk-deepseek-v4-flash"            => "deepseek-v4-flash",
+        "dsk-deepseek-v4-flash-vision-exp" => "deepseek-v4-flash-vision-exp",
+        # claude via bedrock (abs-)
+        "abs-claude-fable-5-1"  => "global.anthropic.claude-fable-5-1",
+        "abs-claude-fable-5"    => "global.anthropic.claude-fable-5",
+        "abs-claude-opus-5"     => "global.anthropic.claude-opus-5",
+        "abs-claude-opus-4-8"   => "global.anthropic.claude-opus-4-8",
+        "abs-claude-opus-4-7"   => "global.anthropic.claude-opus-4-7",
+        "abs-claude-opus-4-6"   => "global.anthropic.claude-opus-4-6",
+        "abs-claude-sonnet-5"   => "global.anthropic.claude-sonnet-5",
+        "abs-claude-sonnet-4-6" => "global.anthropic.claude-sonnet-4-6",
+        "abs-claude-sonnet-4-5" => "global.anthropic.claude-sonnet-4-5",
+        "abs-claude-haiku-4-5"  => "global.anthropic.claude-haiku-4-5",
+        # gemini chat (or-)
+        "or-gemini-3-1-pro"   => "gemini-3.1-pro-preview",
+        "or-gemini-3-8-flash" => "gemini-3.8-flash",
+        "or-gemini-3-7-flash" => "gemini-3.7-flash",
+        "or-gemini-3-6-flash" => "gemini-3.6-flash",
+        "or-gemini-3-5-flash" => "gemini-3.5-flash",
+        # image generation (or-)
+        "or-gemini-3-pro-image"     => "gemini-3-pro-image",
+        "or-gemini-3-1-flash-image" => "gemini-3.1-flash-image",
+        "or-gpt-image-2"            => "openai/gpt-5.4-image-2",
+        # video generation (or-)
+        "or-veo-3"       => "veo-3.0-generate-001",
+        "or-veo-3-fast"  => "veo-3.0-fast-generate-001",
+        "or-veo-3-1"     => "veo-3.1-generate-001",
+        "or-veo-3-1-fast" => "veo-3.1-fast-generate-001",
+        # text-to-speech (or-)
+        "or-tts-gemini-2-5-flash" => "gemini-2.5-flash-tts",
+        "or-tts-gemini-2-5-pro"   => "gemini-2.5-pro-tts",
+        # speech-to-text (or-)
+        "or-stt-gemini-3-8-flash" => "gemini-3.8-flash",
+        "or-stt-gemini-3-7-flash" => "gemini-3.7-flash",
+        "or-stt-gemini-3-6-flash" => "gemini-3.6-flash",
+        "or-stt-gemini-3-5-flash" => "gemini-3.5-flash",
+        "or-stt-gemini-1-5-pro"   => "gemini-1.5-pro-002"
+      }.freeze
+
+      # real upstream model id → alias, for display. Includes the OpenRouter
+      # fallback ids (google/…-preview) the gateway records when Vertex is
+      # disabled, in addition to the primary Vertex ids in ALIAS_TO_REAL.
+      REAL_TO_ALIAS = ALIAS_TO_REAL.invert.merge(
+        "google/gemini-3.1-pro-preview"      => "or-gemini-3-1-pro",
+        "google/gemini-3-pro-image-preview"  => "or-gemini-3-pro-image",
+        # STT aliases reuse the chat real id; Hash#invert keeps the later STT
+        # key, so pin these back to the chat alias for display.
+        "gemini-3.8-flash" => "or-gemini-3-8-flash",
+        "gemini-3.7-flash" => "or-gemini-3-7-flash",
+        "gemini-3.6-flash" => "or-gemini-3-6-flash",
+        "gemini-3.5-flash" => "or-gemini-3-5-flash"
+      ).freeze
+
+      class << self
+        # Translate a real upstream model id back to the user-facing alias.
+        # Unknown ids pass through unchanged (other providers' local records).
+        def display_model(real_id)
+          REAL_TO_ALIAS.fetch(real_id, real_id)
+        end
+
+        # Translate a user-facing alias to the primary real upstream model id.
+        # Returns nil when the alias is not an openclacky model.
+        def real_model(alias_name)
+          ALIAS_TO_REAL[alias_name]
+        end
+
+        # Fetch and merge usage summaries across multiple openclacky keys
+        # (e.g. several accounts). The platform bills per key, so summing
+        # per-key results yields the combined total. Failing keys
+        # (invalid/revoked) are skipped; returns nil only when every key fails.
+        def fetch_summary_merged(api_keys, period:, model: nil)
+          summaries = Array(api_keys).uniq.map { |key| fetch_summary(key, period: period, model: model) }.compact
+          return nil if summaries.empty?
+
+          summaries.reduce { |acc, summary| merge_summaries(acc, summary) }
+        end
+
+        # Fetch and merge daily breakdowns across multiple openclacky keys.
+        # Same skip-on-failure semantics as fetch_summary_merged.
+        def fetch_daily_merged(api_keys, days:, model: nil)
+          dailies = Array(api_keys).uniq.map { |key| fetch_daily(key, days: days, model: model) }.compact
+          return nil if dailies.empty?
+
+          { days: merge_daily_entries(dailies.flat_map { |daily| daily[:days] }) }
+        end
+
+        # Fetch authoritative usage summary for the platform (openclacky).
+        # Returns a hash shaped like BillingStore#summary, or nil on failure.
+        def fetch_summary(api_key, period:, model: nil)
+          path = "/api/v1/usage/summary?period=#{period}"
+          path += "&model=#{URI.encode_www_form_component(model)}" if model && !model.empty?
+
+          data = request(api_key, path)
+          data && normalize_summary(data)
+        end
+
+        # Fetch authoritative daily breakdown for the platform (openclacky).
+        # Returns { days: [...] } or nil on failure.
+        def fetch_daily(api_key, days:, model: nil)
+          path = "/api/v1/usage/daily?days=#{days}"
+          path += "&model=#{URI.encode_www_form_component(model)}" if model && !model.empty?
+
+          data = request(api_key, path)
+          return nil unless data.is_a?(Hash)
+
+          days_data = data["days"] || data[:days] || []
+          days_data = days_data.map do |d|
+            next d unless d.is_a?(Hash)
+
+            align_prompt_tokens(d.transform_keys(&:to_sym))
+          end
+          { days: days_data }
+        end
+
+        private def request(api_key, path)
+          client = Clacky::PlatformHttpClient.new
+          result = client.get(path, headers: { "Authorization" => "Bearer #{api_key}" })
+          result[:success] ? result[:data] : nil
+        rescue StandardError
+          nil
+        end
+
+        private def merge_summaries(a, b)
+          merged = {}
+          (a.keys | b.keys).each do |key|
+            merged[key] =
+              case key
+              when :by_model then merge_by_model(a[:by_model], b[:by_model])
+              when :by_day   then merge_by_day(a[:by_day], b[:by_day])
+              else merge_value(a[key], b[key])
+              end
+          end
+          merged
+        end
+
+        private def merge_by_model(a, b)
+          merged = {}
+          (a || {}).each { |model, entry| merged[model] = entry }
+          (b || {}).each do |model, entry|
+            merged[model] = merged.key?(model) ? merge_entries(merged[model], entry) : entry
+          end
+          merged
+        end
+
+        private def merge_by_day(a, b)
+          merged = {}
+          (a || {}).each { |date, cost| merged[date] = cost.to_f }
+          (b || {}).each { |date, cost| merged[date] = (merged[date] || 0.0) + cost.to_f }
+          merged
+        end
+
+        private def merge_daily_entries(entries)
+          by_date = {}
+          entries.each do |entry|
+            next unless entry.is_a?(Hash)
+
+            date = entry[:date] || entry["date"]
+            next if date.nil?
+
+            by_date[date] = by_date.key?(date) ? merge_entries(by_date[date], entry) : entry
+          end
+          by_date.values.sort_by { |entry| entry[:date].to_s }
+        end
+
+        private def merge_entries(a, b)
+          merged = {}
+          (a.keys | b.keys).each { |key| merged[key] = merge_value(a[key], b[key]) }
+          merged
+        end
+
+        # Sum numeric leaf fields. Non-numeric fields (period, from/to,
+        # source) are identical across keys — they come from the same query
+        # shape — so the first value wins.
+        private def merge_value(a, b)
+          return b if a.nil?
+          return a if b.nil?
+          return a + b if a.is_a?(Numeric) && b.is_a?(Numeric)
+
+          a
+        end
+
+        # Normalise the platform summary (string keys) to the same shape as
+        # BillingStore#summary (symbol keys, symbol-keyed by_model entries).
+        private def normalize_summary(data)
+          return nil unless data.is_a?(Hash)
+
+          normalized = data.transform_keys(&:to_sym)
+          if normalized[:by_model].is_a?(Hash)
+            normalized[:by_model] = normalized[:by_model].transform_values do |entry|
+              entry.is_a?(Hash) ? entry.transform_keys(&:to_sym) : entry
+            end
+          end
+          align_prompt_tokens(normalized)
+          normalized
+        end
+
+        # The platform reports prompt_tokens as Anthropic's input_tokens (the
+        # post-cache tail), while local records store prompt_tokens with
+        # cache_read already folded in. Fold cache_read back so prompt/total
+        # line up and the UI's `prompt - cache_read` never goes negative.
+        private def align_prompt_tokens(entry)
+          cache_read = entry[:cache_read_tokens].to_i
+          entry[:prompt_tokens] = entry[:prompt_tokens].to_i + cache_read
+          entry[:total_tokens] = entry[:total_tokens].to_i + cache_read if entry.key?(:total_tokens)
+          entry[:tokens] = entry[:tokens].to_i + cache_read if entry.key?(:tokens)
+          entry
+        end
+      end
+    end
+  end
+end

data/lib/clacky/brand_config.rb

@@ -912,14 +912,15 @@ module Clacky
       { success: false, error: e.message }
     end
 
-    # Synchronise brand extensions in the background for activated installs.
+    # Synchronise brand extensions in the background for activated consumer
+    # installs. Brand administrators manage extensions through ext-studio and
+    # must not auto-install the extensions they publish for consumers.
     # Mirrors sync_brand_skills_async! but installs into the extension layer.
-    # Unlike brand skills, new extensions are auto-installed because a bundled
-    # extension is chosen by the brand administrator, not the end user.
     #
     # @return [Thread, nil]
     def sync_brand_extensions_async!(on_complete: nil)
       return nil unless activated?
+      return nil if user_licensed?
       return nil if ENV["CLACKY_TEST"] == "1"
 
       Clacky::ThreadRegistry.spawn(name: "brand-fetch-extensions") do

data/lib/clacky/cancel_flag.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Clacky
+  # A one-way, thread-safe cancellation flag shared across a parent agent and
+  # the subagents it forks. Fan-out runs each subagent on its own worker thread;
+  # when the parent is interrupted the worker threads must learn to stop, but
+  # they cannot see the parent's thread-local task epoch. Flipping this flag is
+  # the shared signal every subagent polls at its safe checkpoints.
+  class CancelFlag
+    def initialize
+      @mutex = Mutex.new
+      @cancelled = false
+    end
+
+    def cancel!
+      @mutex.synchronize { @cancelled = true }
+    end
+
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+  end
+end

data/lib/clacky/cli.rb

@@ -1349,8 +1349,8 @@ module Clacky
 
       # ── Security gate ──────────────────────────────────────────────────────
       # Binding to 0.0.0.0 exposes the server to the public network.
-      # Refuse to start unless CLACKY_ACCESS_KEY env var is set.
-      if options[:host] == "0.0.0.0" && !ENV.key?("CLACKY_ACCESS_KEY")
+      # Refuse to start unless an access key is available.
+      if options[:host] == "0.0.0.0" && !ENV.key?("CLACKY_ACCESS_KEY") && Clacky::AccessKey.from_file.nil?
         puts <<~MSG
           ╔══════════════════════════════════════════════════════════════╗
           ║  ⚠️  Security Warning: Refusing to start                      ║
@@ -1365,6 +1365,8 @@ module Clacky
           ║  Then export it:                                             ║
           ║    export CLACKY_ACCESS_KEY=<your-generated-key>             ║
           ║                                                              ║
+          ║  Or write it to ~/.clacky/access_key                         ║
+          ║                                                              ║
           ╚══════════════════════════════════════════════════════════════╝
         MSG
         exit(1)

data/lib/clacky/client.rb

@@ -44,6 +44,7 @@ module Clacky
       effective_api_format ||= "anthropic-messages" if anthropic_format
       resolved_type = Providers.api_type_for_model(provider_id, @model, user_override: effective_api_format)
       @use_anthropic_format = resolved_type == "anthropic-messages"
+      @use_responses_format = resolved_type == "openai-responses"
 
       # Remember the provider id so we can tune connection headers below
       # (OpenRouter's /v1/messages accepts either Bearer or x-api-key, but
@@ -66,6 +67,12 @@ module Clacky
       @use_anthropic_format && !@use_bedrock
     end
 
+    # Returns true when the client talks to the OpenAI Responses API
+    # (/v1/responses) instead of Chat Completions.
+    def responses_format?(model = nil)
+      @use_responses_format && !@use_bedrock
+    end
+
     # ── Connection test ───────────────────────────────────────────────────────
 
     # Test API connection by sending a minimal request.
@@ -81,6 +88,11 @@ module Clacky
         minimal_body = { model: api_model, max_tokens: 16,
                          messages: [{ role: "user", content: "hi" }] }.to_json
         response = anthropic_connection.post(anthropic_messages_path) { |r| r.body = minimal_body }
+      elsif responses_format?
+        minimal_body = MessageFormat::OpenAIResponses.build_request_body(
+          [{ role: "user", content: "hi" }], api_model, [], 16, false
+        ).to_json
+        response = openai_connection.post("responses") { |r| r.body = minimal_body }
       else
         minimal_body = { model: api_model, max_tokens: 16,
                          messages: [{ role: "user", content: "hi" }] }.to_json
@@ -113,6 +125,10 @@ module Clacky
         body     = MessageFormat::Anthropic.build_request_body(messages, api_model, [], max_tokens, false)
         response = anthropic_connection.post(anthropic_messages_path) { |r| r.body = body.to_json }
         parse_simple_anthropic_response(response)
+      elsif responses_format?
+        body     = MessageFormat::OpenAIResponses.build_request_body(messages, api_model, [], max_tokens, false)
+        response = openai_connection.post("responses") { |r| r.body = body.to_json }
+        parse_simple_openai_responses_response(response)
       else
         body     = MessageFormat::OpenAI.build_request_body(messages, api_model, [], max_tokens, false, reasoning_effort: reasoning_effort)
         response = openai_connection.post("chat/completions") { |r| r.body = body.to_json }
@@ -164,6 +180,9 @@ module Clacky
         elsif anthropic_format?
           streaming_used = !on_chunk.nil?
           send_anthropic_request(cloned, api_model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk)
+        elsif responses_format?
+          streaming_used = !on_chunk.nil?
+          send_openai_responses_request(cloned, api_model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk, capability_model: model)
         else
           streaming_used = !on_chunk.nil?
           send_openai_request(cloned, api_model, tools, max_tokens, caching_enabled, reasoning_effort: reasoning_effort, on_chunk: wrapped_on_chunk, capability_model: model)
@@ -206,6 +225,8 @@ module Clacky
         MessageFormat::Bedrock.format_tool_results(response, tool_results)
       elsif anthropic_format?
         MessageFormat::Anthropic.format_tool_results(response, tool_results)
+      elsif responses_format?
+        MessageFormat::OpenAIResponses.format_tool_results(response, tool_results)
       else
         MessageFormat::OpenAI.format_tool_results(response, tool_results)
       end
@@ -460,6 +481,92 @@ module Clacky
       content
     end
 
+    # ── OpenAI Responses API request / response ───────────────────────────────
+
+    def send_openai_responses_request(messages, model, tools, max_tokens, caching_enabled,
+                                      reasoning_effort: nil, on_chunk: nil, capability_model: nil)
+      # Override max_tokens when the model declares a higher output ceiling
+      model_for_limit = capability_model || model
+      model_limit = Providers.max_output_for(model_for_limit)
+      max_tokens = model_limit if model_limit
+
+      # Deliberately no apply_message_caching here: the Responses API does
+      # not recognize Anthropic-style cache_control markers, and OpenAI's
+      # Responses prompt caching is automatic server-side. Injecting
+      # cache_control would be silently ignored (or rejected by stricter
+      # endpoints).
+
+      cap_model = capability_model || model
+      body = MessageFormat::OpenAIResponses.build_request_body(
+        messages, model, tools, max_tokens, caching_enabled,
+        vision_supported: Providers.supports?(@provider_id, :vision, model_name: cap_model),
+        reasoning_effort: reasoning_effort
+      )
+      return send_openai_responses_stream_request(body, on_chunk) if on_chunk
+
+      response = openai_connection.post("responses") { |r| r.body = body.to_json }
+
+      raise_error(response) unless response.status == 200
+      check_html_response(response)
+
+      parsed_body = safe_json_parse(response.body, context: "LLM response")
+      MessageFormat::OpenAIResponses.parse_response(parsed_body)
+    end
+
+    # Streaming variant for the OpenAI Responses API.
+    # Posts to the "responses" endpoint with stream:true; the upstream returns
+    # typed SSE events (response.output_text.delta,
+    # response.function_call_arguments.delta, response.completed, etc.) that
+    # the aggregator reassembles into the non-streaming response shape.
+    private def send_openai_responses_stream_request(body, on_chunk)
+      stream_body = body.merge(stream: true)
+      aggregator = OpenAIResponsesStreamAggregator.new(on_chunk: on_chunk)
+      sse_buf = +""
+
+      response = openai_connection.post("responses") do |req|
+        req.headers["Accept"] = "text/event-stream"
+        req.body = stream_body.to_json
+        req.options.on_data = proc do |chunk, _bytes_received, _env|
+          sse_buf << chunk
+          drain_sse_frames(sse_buf) { |_event, data| aggregator.handle(data) }
+        end
+      end
+
+      unless response.status == 200
+        response.env.body = sse_buf if response.body.to_s.empty?
+        raise_error(response)
+      end
+
+      result = aggregator.to_h
+      log_stream_summary("openai-responses", aggregator, aggregator.saw_done? ? "completed" : nil)
+      # A complete Responses API stream always terminates with a
+      # response.completed / response.done (or response.incomplete) event.
+      # Its absence means the upstream cut the stream mid-response; retry
+      # rather than accept a silently truncated answer.
+      unless aggregator.saw_done?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without response.completed (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::OpenAIResponses.parse_response(result)
+    end
+
+    def parse_simple_openai_responses_response(response)
+      raise_error(response) unless response.status == 200
+      parsed_body = safe_json_parse(response.body, context: "LLM response")
+      result = MessageFormat::OpenAIResponses.parse_response(parsed_body)
+      content = result[:content]
+      if content.nil?
+        snippet = response.body.to_s[0, 1200]
+        if defined?(Clacky::Logger)
+          Clacky::Logger.warn("[parse_simple_openai_responses_response] no content. status=#{response.status} body=#{snippet}")
+        end
+        raise RetryableError,
+          "Upstream Responses API response missing text content. " \
+          "Body snippet: #{snippet}"
+      end
+      content
+    end
+
     # ── Prompt caching helpers ────────────────────────────────────────────────
 
     # Add cache_control markers to the last 2 messages in the array.

data/lib/clacky/default_extensions/advisor/advisors/general.md

@@ -7,29 +7,35 @@ choose from.
 
 ## Output format (strict)
 
-Output exactly 3 options, one per line, in this format:
-
-- [full instruction] reason
-
-- full instruction: a complete, ready-to-send instruction for the agent — the
-  user should be able to paste it into the input box and send it as-is, no
-  editing. Write it as an imperative sentence.
-- reason: one short sentence (under ~20 words).
+Respond with ONLY a JSON array of exactly 3 objects. No prose before or after,
+no markdown code fence:
+
+[{"action": "...", "reason": "..."}, {"action": "...", "reason": "..."}, {"action": "...", "reason": "..."}]
+
+- action: a complete, ready-to-send instruction for the agent — the user
+  should be able to paste it into the input box and send it as-is, no
+  editing. Write it in the USER's voice, speaking TO the agent (e.g. "Run
+  the test suite and show me the failures"), never in the agent's voice
+  speaking to the user (e.g. "Tell me what you'd like to do" is wrong — the
+  user would be asking the agent to ask them). Put NOTHING here but the
+  instruction itself: no leading dash, no rationale, no trailing commentary.
+- reason: one short sentence (under ~20 words) explaining why you suggest it.
 - The 3 options must be *mutually distinct directions* — e.g. one continue /
   fix path, one verification path, one wrap-up path. Do not rephrase the same
   idea three times.
-- If no reasonable options exist at all, output a single line: none
+- If no reasonable options exist at all, respond with an empty array: []
 
 ## Hard rules
 
 1. Base every option ONLY on facts present in the brief. Never invent file
    names, tasks, or project content that the brief does not mention.
 2. When the user's latest message is vague and there were no tool calls
-   (conversation just started, e.g. "hi"): your FIRST option must ask the user
-   what they want to do (e.g. "Tell me what you'd like me to build or help
-   with"). The other options may gently offer starting points, but only if
-   the brief shows real content to start from — never fabricate an exploration
-   target.
+   (conversation just started, e.g. "hi"): offer low-risk openers the user
+   could send right now, grounded in what the brief actually shows — e.g.
+   "Summarize what this project does and where its entry points are" when the
+   brief names a project. If the brief shows nothing to work from, respond
+   with an empty array rather than inventing an exploration target. Never
+   turn an option into a question aimed at the user.
 3. When the brief shows a clear task in progress (recent tool calls, files
    written, errors, tests), recommend directions tied to THAT task: continue
    the work, verify it (run the relevant tests), or wrap it up (review the
@@ -38,9 +44,9 @@ Output exactly 3 options, one per line, in this format:
 
 ## Judgement guide
 
-1. Conversation just started, no tool calls → ask what the user wants first;
-   optionally suggest a grounded starting point (only if the brief shows
-   actual project content).
+1. Conversation just started, no tool calls → suggest grounded openers the
+   user can send as-is (only if the brief shows actual project content);
+   otherwise return [].
 2. Brief shows errors or tool failures → include a fix/continue option.
 3. Files were written but no tests have run → include a verification option.
 4. Task looks complete → include a wrap-up option (review diff, run the full

data/lib/clacky/default_extensions/advisor/hooks/advisor.rb

@@ -29,7 +29,25 @@ module Clacky
     CONVERSATION_TURNS = 8
     SUMMARY_LIMIT = 200
     MESSAGE_LIMIT = 200
-
+    MAX_OPTIONS = 3
+    ACTION_LIMIT = 500
+    REASON_LIMIT = 200
+
+    # Models copy the panel's own " · " separator when they drop the JSON
+    # format. Deliberately structural: a localized "Reason:" label would need
+    # one pattern per language, so those lines keep the label inside the action.
+    FALLBACK_REASON_SEPARATOR = /\s+·\s+/.freeze
+
+    # Some providers keep thinking inline in `content` (e.g. MiniMax), and the
+    # closing tag is missing whenever the reply gets cut short.
+    THINK_BLOCK = %r{<think>.*?</think>}m.freeze
+    UNCLOSED_THINK = /<think>[\s\S]*\z/.freeze
+
+    # A degraded line only counts as an option when the model marked it up as
+    # one: a list bullet or a [action] wrapper. Without this, reasoning prose
+    # turns into three bogus suggestions.
+    FALLBACK_LIST_MARKER = /\A(?:[-*•]|\d+[.)])\s+/.freeze
+    FALLBACK_BRACKETED = /\A\[([^\]]+)\]\s*(.*)\z/m.freeze
     class << self
       def enabled_for?(agent)
         return false if agent.instance_variable_get(:@is_subagent)
@@ -137,14 +155,16 @@ module Clacky
       private def analyze(snapshot)
         cfg = Advisor.config_for(@agent)
         advice = generate_advice(cfg, snapshot)
+        options = parse_options(advice)
         Clacky::Logger.info("[Advisor] analyze",
                             session: @agent.session_id.to_s,
                             len: advice.length,
+                            options: options.size,
                             head: advice[0, 100].to_s)
-        if advice.empty? || advice.strip == "none"
+        if options.empty?
           @agent.emit_event("ext.advisor.done", reason: "empty")
         else
-          push_advice(advice)
+          push_advice(options)
         end
       rescue StandardError => e
         warn_error("analyze", e)
@@ -217,8 +237,87 @@ module Clacky
         nil
       end
 
-      private def push_advice(advice)
-        @agent.emit_event("ext.advisor.recommendations", content: advice)
+      # Turn the raw model reply into [{ action:, reason: }, ...]. The JSON path
+      # is authoritative; the line-based path exists because weak models still
+      # drift out of the requested format, and a rough clickable option beats
+      # showing nothing.
+      private def parse_options(raw)
+        text = strip_thinking(raw.to_s).strip
+        return [] if text.empty?
+
+        array = extract_json_array(text)
+        return normalize_options(array) if array
+
+        fallback_options(text)
+      end
+
+      private def strip_thinking(text)
+        text.gsub(THINK_BLOCK, "").sub(UNCLOSED_THINK, "")
+      end
+
+      private def extract_json_array(text)
+        body = text
+        body = body.gsub(/\A```[a-zA-Z]*\n?/, "").gsub(/```\z/, "").strip if body.start_with?("```")
+        parsed = begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          # Models still wrap the array in a sentence or a stray code fence.
+          match = body.match(/\[[\s\S]*\]/)
+          match && begin
+            JSON.parse(match[0])
+          rescue JSON::ParserError
+            nil
+          end
+        end
+        parsed.is_a?(Array) ? parsed : nil
+      end
+
+      private def normalize_options(array)
+        options = []
+        array.each do |entry|
+          next unless entry.is_a?(Hash)
+
+          action = entry["action"].to_s.strip
+          next if action.empty?
+
+          options << { action: action[0, ACTION_LIMIT], reason: entry["reason"].to_s.strip[0, REASON_LIMIT] }
+          break if options.size >= MAX_OPTIONS
+        end
+        options
+      end
+
+      # One option per line, splitting the reason off so it never leaks into
+      # `action` — that text is sent verbatim to the agent when clicked. Only
+      # list items qualify, so a reply that is plain prose yields nothing.
+      private def fallback_options(text)
+        options = []
+        text.split("\n").each do |line|
+          action, reason = split_fallback_line(line)
+          next if action.empty?
+
+          options << { action: action[0, ACTION_LIMIT], reason: reason[0, REASON_LIMIT] }
+          break if options.size >= MAX_OPTIONS
+        end
+        options
+      end
+
+      private def split_fallback_line(line)
+        stripped = line.strip
+        listed = FALLBACK_LIST_MARKER.match(stripped)
+        body = listed ? stripped.sub(FALLBACK_LIST_MARKER, "") : stripped
+        return ["", ""] if body.empty?
+
+        bracketed = body.match(FALLBACK_BRACKETED)
+        return [bracketed[1].strip, bracketed[2].strip] if bracketed
+
+        return listed ? [body, ""] : ["", ""] unless FALLBACK_REASON_SEPARATOR.match(body)
+
+        action, reason = body.split(FALLBACK_REASON_SEPARATOR, 2)
+        [action.to_s.strip, reason.to_s.strip]
+      end
+
+      private def push_advice(options)
+        @agent.emit_event("ext.advisor.recommendations", options: options)
       end
 
       private def advisor_model_name(cfg)