rubik 0.1.0

data/lib/rubik/tools/truncator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Tools
+    module Truncator
+      DEFAULT_MAX_CHARS = 12_000
+      DEFAULT_MAX_LINES = 300
+
+      def self.truncate(text, max_chars: DEFAULT_MAX_CHARS, max_lines: DEFAULT_MAX_LINES, strategy: :head_tail)
+        str = text.to_s
+        # byteslice truncation below cuts on byte boundaries and can split a
+        # multibyte character, producing invalid UTF-8 that then poisons the
+        # whole downstream pipeline (JSON generation, regex work, token
+        # estimation). Scrub exactly once, after the last byteslice.
+        str = str.scrub("") unless str.valid_encoding?
+        lines = str.lines
+
+        max_c = (max_chars || DEFAULT_MAX_CHARS).to_i
+        max_l = (max_lines || DEFAULT_MAX_LINES).to_i
+
+        return { text: str, truncated: false, omitted_lines: 0, omitted_chars: 0 } if str.bytesize <= max_c && lines.size <= max_l
+
+        strategy_sym = strategy.to_s.downcase.to_sym
+
+        case strategy_sym
+        when :head_only
+          kept_lines = lines.first(max_l)
+          kept_str = kept_lines.join
+          kept_str = kept_str.byteslice(0, max_c) if kept_str.bytesize > max_c
+          omitted_lines = [lines.size - kept_lines.size, 0].max
+          omitted_chars = [str.bytesize - kept_str.bytesize, 0].max
+          notice = "\n... [Truncated: omitted #{omitted_lines} lines / #{omitted_chars} chars] ...\n"
+          { text: finalize(kept_str, notice, prefix: true), truncated: true,
+            omitted_lines: omitted_lines, omitted_chars: omitted_chars }
+        when :tail_only
+          kept_lines = lines.last(max_l)
+          kept_str = kept_lines.join
+          kept_str = kept_str.byteslice(-max_c, max_c) if kept_str.bytesize > max_c
+          omitted_lines = [lines.size - kept_lines.size, 0].max
+          omitted_chars = [str.bytesize - kept_str.bytesize, 0].max
+          notice = "\n... [Truncated: omitted #{omitted_lines} lines / #{omitted_chars} chars] ...\n"
+          { text: finalize(kept_str, notice, prefix: false), truncated: true,
+            omitted_lines: omitted_lines, omitted_chars: omitted_chars }
+        else # :head_tail
+          half_lines = (max_l / 2).clamp(1, 150)
+          half_chars = (max_c / 2).clamp(1, 6000)
+
+          head_lines = lines.first(half_lines)
+          tail_lines = lines.last(half_lines)
+
+          head_str = head_lines.join
+          tail_str = tail_lines.join
+
+          head_str = head_str.byteslice(0, half_chars) if head_str.bytesize > half_chars
+          tail_str = tail_str.byteslice(-half_chars, half_chars) if tail_str.bytesize > half_chars
+
+          omitted_lines = [lines.size - (head_lines.size + tail_lines.size), 0].max
+          omitted_chars = [str.bytesize - (head_str.bytesize + tail_str.bytesize), 0].max
+          notice = "\n\n... [Truncated: #{omitted_lines} lines / #{omitted_chars} chars omitted to preserve token budget] ...\n\n"
+
+          { text: finalize(tail_str, finalize(head_str, notice, prefix: true), prefix: false), truncated: true,
+            omitted_lines: omitted_lines, omitted_chars: omitted_chars }
+        end
+      end
+
+      # Post-byteslice UTF-8 guard: a byte-boundary cut can split a multibyte
+      # character at either edge of the kept region. Dropping the partial
+      # sequence keeps the byte budget honest while the rendered output stays
+      # valid UTF-8 — the property every consumer below this point (JSON
+      # payload envelopes, regex-based token estimation, history joins)
+      # silently assumes.
+      def self.finalize(str, notice, prefix:)
+        str = str.scrub("") unless str.valid_encoding?
+        prefix ? "#{str}#{notice}" : "#{notice}#{str}"
+      end
+    end
+  end
+end

data/lib/rubik/tools/uri_resolver.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "../uris"
+require_relative "../coeffects"
+require_relative "../orchestrator/subagent/transcript_formatter"
+require_relative "output"
+require_relative "diagnostic_reporter"
+require_relative "../storage"
+
+module Rubik
+  module Tools
+    # rubik:// şema sevk yeri (uri-resolver-seam planı 2026-10-01).
+    # read_file ve show_file sanal URI'leri buradan geçirir; dosya
+    # düzlemi (file:// ve düz yollar) ReadFileTool'da kalır.
+    #
+    # Kayıt modeli Sandbox::Driver'ınkinin aynısı (AGENTS.md §4.D):
+    # Monitor korumalı şema→adapter haritası; ctx verilirse önceki değer
+    # anlık görüntüsü alınır ve kimlik-korumalı geri-yükleme lambda'sı
+    # ctx.on_dispose'a LIFO için itilir — dispose yalnızca yuvada HÂLÂ
+    # bizim adapter varsa geri yükler, böylece daha yeni bir kayıt eski
+    # bağlamın kapanışından sağ çıkar. Varsayılan adapterler dosya sonunda
+    # ctx'siz tohumlanır (süreç ömrü) — bare kurulumlu testler için diki
+    # kök gerekmez.
+    module UriResolver
+      @adapters = {}
+      @mutex = Monitor.new
+
+      class << self
+        def register(scheme, adapter, ctx: nil)
+          key = scheme.to_s.downcase
+          restore = @mutex.synchronize do
+            prior = @adapters[key] # snapshot BEFORE the overwrite
+            @adapters[key] = adapter
+            lambda do
+              @mutex.synchronize do
+                next unless @adapters.key?(key) && @adapters[key].equal?(adapter)
+
+                prior ? @adapters[key] = prior : @adapters.delete(key)
+              end
+            end
+          end
+          ctx&.on_dispose(&restore)
+          adapter
+        end
+
+        def unregister(scheme)
+          @mutex.synchronize { @adapters.delete(scheme.to_s.downcase) }
+        end
+
+        def registered_schemes
+          @mutex.synchronize { @adapters.keys.sort }
+        end
+
+        # Sevk. Adapterden String (başarı) ya da ToolOutput (dürüst hata)
+        # döner; bu çözümleyici URI'ye hizmet etmiyorsa nil:
+        #   - URI rubik:// değil
+        #   - şemaya kayıtlı adapter yok
+        #   - adapterın tam grameri (match?) URI'yi reddetmesi
+        #   - `only:` verilmiş ve URI'nin şemesi farklıysa (show_file
+        #     yalnız "storage" ister)
+        # Çağıranlar nil'i "kendi doğal düzlemime düş" olarak yorumlar —
+        # bilinmeyen şemalar buffer düzlemine düşer (bugünkü davranış).
+        def resolve(uri, ctx: nil, buffer_manager: nil, only: nil)
+          scheme = Rubik::Uris.scheme_of(uri)
+          return nil unless scheme
+          return nil if only && scheme != only.to_s.downcase
+
+          adapter = @mutex.synchronize { @adapters[scheme] }
+          return nil unless adapter
+          return nil unless adapter.match?(uri)
+
+          result = adapter.read(uri, ctx: ctx, buffer_manager: buffer_manager)
+          return result unless result.nil?
+
+          # Sözleşme ihlali (adapter read ASLA nil döndürmez) — gramer
+          # reddinden AYRT edilir: nil'i dosya düzlemine düşürmek yanlış
+          # yönlendiren bir dosya-not-found üretirdi; dürüst hata basılır.
+          warn "[UriResolver] '#{scheme}' adapter violated the read contract (returned nil); " \
+               "refusing to fall through to the file plane"
+          ToolOutput.error("rubik://#{scheme} read failed: the '#{scheme}' adapter returned no content " \
+                           "(contract violation — see runtime log).")
+        end
+
+        # Şema kayıtlı VE adapterın grameri URI'yi tanıyor mu — yalnızca
+        # belgelendirme/bekçi sorguları için; sevk yolu resolve'dur.
+        def handles?(uri)
+          scheme = Rubik::Uris.scheme_of(uri)
+          return false unless scheme
+
+          adapter = @mutex.synchronize { @adapters[scheme] }
+          !adapter.nil? && adapter.match?(uri)
+        end
+      end
+
+      # Adapter sözleşmesi: durumdan yoksuz strateji sınıfları (repo
+      # kuralı: ilgili sınıflar aynı dosyada, files.rb gibi). match? gramer
+      # kapısıdır — başarısızlığı sevk yerinin nil düşüşüdür. read ASLA nil
+      # döndürmez ve ASLA yükselmez; hata yükü kendi ToolOutput'undadır
+      # (kendi rescue StandardError'ıyla sarılır — StorageAdapter'da bu
+      # ödev UriReader.read'in içindeki rescue'ya delege edilmiştir).
+      # Çağrı anı durumu (ctx, buffer_manager) resolve argümanlarından
+      # akar — adapter ctx-provided servis DEĞİLDİR.
+
+      # rubik://storage/... — FS-DB okuma düzlemi. Alt-gramer (index/
+      # proje/tip-liste/varlık/refs, .json eki) UriReader'ındır; hata
+      # yükleri de orada yaşar.
+      class StorageAdapter
+        def match?(uri)
+          Rubik::Uris::STORAGE_PREFIX.match?(uri)
+        end
+
+        def read(uri, ctx:, **_)
+          Rubik::Storage::UriReader.read(uri, ctx: ctx)
+        end
+      end
+
+      # rubik://subagent/<storage-id>/transcript reads the transcript FILE
+      # directly — never through the buffer manager. The URL must carry the
+      # unique storage dir name: the absolute path advertised by
+      # manage_subagents status and Instance#to_h. A bare display id
+      # ("subagent-1") resolves to a nonexistent dir and returns an honest
+      # not-found — deliberately no glob-newest fallback, which would serve
+      # a previous session's transcript while a live unsaved instance may
+      # exist (the stale-evidence failure mode of 2026-09-27). One route,
+      # one truth. The sandbox workspace gate does not apply: the id is
+      # charset-validated and the path is an internal artifact under the
+      # transcript root, not a user-supplied filesystem location.
+      class SubagentTranscriptAdapter
+        def match?(uri)
+          Rubik::Uris::SUBAGENT_TRANSCRIPT.match?(uri)
+        end
+
+        def read(uri, ctx:, buffer_manager:)
+          sub_id = uri[Rubik::Uris::SUBAGENT_TRANSCRIPT, 1]
+          unless sub_id.match?(/\A[a-zA-Z0-9_-]+\z/)
+            return ToolOutput.error("Invalid subagent id: #{sub_id} (allowed: letters, digits, _ and -). Use the " \
+                                    "storage-id dir name from the absolute 'transcript' path in manage_subagents status.")
+          end
+
+          storage = Rubik::Coeffects.get(ctx, Rubik::Coeffects::STORAGE_STORE)
+          file = Rubik::Orchestrator::Subagent::TranscriptFormatter.resolve(buffer_manager.root_dir, sub_id, storage: storage)
+          return File.read(file) if File.exist?(file)
+
+          ToolOutput.error(DiagnosticReporter.render_file_not_found(file.to_s, candidates: []) +
+                           "\nHint: for a running subagent the live copy is manage_subagents action 'transcript' " \
+                           "(in-memory); the on-disk file appears only after the subagent's first save.")
+        rescue StandardError => e
+          ToolOutput.error("Transcript read failed: #{e.class}: #{e.message}")
+        end
+      end
+
+      # rubik://goal/state + rubik://goal/ledger: canlı !goal anlık
+      # görüntüleri (GoalState#to_xml / GoalLedger#to_xml) — coeffect
+      # üzerinden çözülür; bunlar dosya değildir, buffer manager devre
+      # dışıdır. Bağlam/yoksa dürüst not-found (subagent transcript
+      # stilinde); glob/fallback yok — yanlış koşunun durumu servis
+      # edilmez. goal şeması TEK adapter slotudur: state/ledger ayrımı
+      # İÇ dispatch'tir (ikinci kayıt mevcut adapter'ı gölgelerdi).
+      class GoalStateAdapter
+        def match?(uri)
+          Rubik::Uris::GOAL_STATE.match?(uri) || Rubik::Uris::GOAL_LEDGER.match?(uri)
+        end
+
+        def read(uri, ctx:, **_)
+          if Rubik::Uris::GOAL_LEDGER.match?(uri)
+            ledger = Rubik::Coeffects.get(ctx, Rubik::Coeffects::GOAL_LEDGER)
+            return ledger.to_xml if ledger
+
+            return ToolOutput.error("No goal ledger available: no !goal run is active (or goal.ledger.enabled=false). " \
+                                    "The ledger exists only while a goal loop runs; rubik://goal/state may still " \
+                                    "hold the last run's snapshot.")
+          end
+
+          state = Rubik::Coeffects.get(ctx, Rubik::Coeffects::GOAL_STATE)
+          return state.to_xml if state
+
+          ToolOutput.error("No goal state available: no !goal run has started in this session. " \
+                           "Goal state exists only while (or after) the operator runs !goal; " \
+                           "for subagent work use manage_subagents action: 'status'.")
+        rescue StandardError => e
+          ToolOutput.error("Goal state read failed: #{e.class}: #{e.message}")
+        end
+      end
+
+      DEFAULT_STORAGE_ADAPTER = StorageAdapter.new
+      DEFAULT_SUBAGENT_TRANSCRIPT_ADAPTER = SubagentTranscriptAdapter.new
+      DEFAULT_GOAL_STATE_ADAPTER = GoalStateAdapter.new
+
+      register(Rubik::Uris::STORAGE, DEFAULT_STORAGE_ADAPTER)
+      register(Rubik::Uris::SUBAGENT, DEFAULT_SUBAGENT_TRANSCRIPT_ADAPTER)
+      register(Rubik::Uris::GOAL, DEFAULT_GOAL_STATE_ADAPTER)
+    end
+  end
+end

data/lib/rubik/tools.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "tools/base"
+require_relative "tools/output"
+require_relative "tools/result"
+require_relative "tools/truncator"
+require_relative "tools/registry"
+require_relative "tools/builtins"
+require_relative "tools/catalog"
+
+module Rubik
+  module Tools
+  end
+end

data/lib/rubik/ui/approvals.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+
+module Rubik
+  module UI
+    # Fast-path approval surfaces (Antigravity-style): a warning card drawn
+    # above the prompt plus single-keypress answers.
+    #
+    # History note: an adaptive sandbox-network approval card
+    # (confirm_action/map_action, returning :yes_network/:yes_sandbox) lived
+    # here but never had a production caller — a phantom security control
+    # (Plan 111, F5). Sandbox network policy is config-only
+    # (`sandbox.allow_network`); if an approval gate is ever wired in, its
+    # design intent is preserved in _plan/80-sandbox-mimari-refaktoru…md and
+    # git history.
+    module Approvals
+      module_function
+
+      # Single-key yes/no. Returns the downcased answer String ("y"/"n"/...)
+      # exactly like Confirmations#ask_yes_no so call sites keep their word
+      # matching. Enter/Esc/EOF/Ctrl+C resolve to the default answer.
+      def keypress_yes_no(shell, question, theme:, default: "n")
+        default_answer = default.to_s.downcase
+        return default_answer unless Capability.interactive?(input: shell.input, output: shell.output)
+
+        hint = default_answer.start_with?("y") ? "Y/n" : "y/N"
+        prompt = build_prompt(shell)
+
+        answer = prompt.keypress("#{question} #{theme.paint("[#{hint}]", :dim)} ")
+        normalize_answer(answer, default_answer)
+      rescue Interrupt
+        Rubik::REPL::InterruptHandler.restore_console_after_interrupt
+        default_answer
+      rescue StandardError
+        default_answer
+      end
+
+      def normalize_answer(answer, default_answer)
+        answer = answer.is_a?(String) ? answer.strip.downcase : ""
+        answer.empty? || answer == "\r" || answer == "\e" ? default_answer : answer
+      end
+
+      # TTY::Prompt must talk to the real terminal: unwrap TeeIO capture the
+      # same way Confirmations#interactive_input? does.
+      def build_prompt(shell)
+        out = Capability.unwrap_tee(shell.output) || $stdout
+        TTY::Prompt.new(input: shell.input || $stdin, output: out)
+      end
+    end
+  end
+end

data/lib/rubik/ui/banner.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+
+module Rubik
+  module UI
+    # Startup banner: brand, version, active model and quick hints inside a
+    # rounded frame. Only rendered for interactive TTY sessions honoring
+    # `ui.banner`; piped/scripted runs stay silent for clean automation.
+    module Banner
+      module_function
+
+      def render(shell, theme)
+        return nil unless shell.config.fetch("ui.banner", true)
+        return nil unless Capability.interactive?(input: shell.input, output: shell.output)
+
+        routed = Statusline.current_route(shell)
+        model = routed ? Statusline.model_label(routed) : "model yapılandırılmamış"
+        project = File.basename(shell.buffer_manager&.root_dir || Dir.pwd)
+        branch = shell.detect_git_branch || "no-git"
+
+        lines = [
+          "🎲 Rubik v#{Rubik::VERSION}",
+          theme.paint(model, :info),
+          theme.paint("#{project} · #{branch}", :dim),
+          theme.paint("!help komutlar · ctrl+c kes · !config ayarlar", :dim)
+        ]
+
+        if Rubik::Platform.linux? && Rubik::Platform.which("bwrap") &&
+           !shell.config.fetch("sandbox.enabled", false) &&
+           shell.config.fetch("sandbox.prompt_on_startup", true)
+          lines << theme.paint("💡 Linux & bwrap algılandı: '!sandbox on' ile donanımsal OS izolasyonu açılabilir", :warn)
+        end
+
+        Frame.draw(
+          lines,
+          theme: theme,
+          title: theme.paint("rubik", :accent)
+        )
+      end
+    end
+  end
+end

data/lib/rubik/ui/capability.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "strings-ansi"
+
+module Rubik
+  module UI
+    # Terminal capability detection: decides whether ANSI color, box-drawing
+    # and live spinner surfaces may be used for a given IO target.
+    #
+    # Resolution order:
+    #   1. RUBIK_TEST=1                     -> never (deterministic test output)
+    #   2. NO_COLOR set                     -> never (https://no-color.org)
+    #   3. CLICOLOR_FORCE=1                 -> always (CI with color-capable logs)
+    #   4. ui.color config: always|never    -> explicit override
+    #   5. output not a TTY                 -> never (pipe/redirect safety)
+    #   6. TERM=dumb                        -> never
+    #   7. Windows legacy conhost           -> try enabling VT, else never
+    module Capability
+      module_function
+
+      # Strips ANSI SGR escape sequences from a string. Used on the recording
+      # path (TeeIO -> StringIO) so session files and LLM context stay clean.
+      def strip_ansi(str)
+        return str unless str.is_a?(String) && str.include?("\e[")
+
+        Strings::ANSI.sanitize(str)
+      end
+
+      # True when ANSI color output is allowed for `io` under `config`.
+      def color?(io, config = nil)
+        case resolve_mode(io, config)
+        when :always then true
+        when :never then false
+        else io.respond_to?(:tty?) ? io.tty? : false
+        end
+      end
+
+      # True when the target can animate a spinner line (real terminal only).
+      def spinner?(io, config = nil)
+        color?(io, config) && io.respond_to?(:tty?) && io.tty? && interactive_env?
+      end
+
+      def interactive_env?
+        ENV["RUBIK_TEST"] != "1"
+      end
+
+      # True when both the input and the *real* output are interactive TTYs.
+      # Single canonical interactivity predicate for UI surfaces: a TeeIO
+      # wrapping a real terminal (REPL command capture) still counts as
+      # interactive; pure StringIO captures and pipes never do.
+      def interactive?(input:, output:)
+        return false unless interactive_env?
+
+        out_io = unwrap_tee(output)
+        return false unless out_io
+
+        input.respond_to?(:tty?) && input.tty? &&
+          out_io.respond_to?(:tty?) && out_io.tty?
+      end
+
+      # Resolves the real terminal behind a TeeIO (first target that is a
+      # live TTY); returns nil when every target is a capture buffer
+      # (StringIO#tty? is defined but false), and the IO itself when it is
+      # not a TeeIO.
+      def unwrap_tee(io)
+        return io unless io.is_a?(Rubik::REPL::TeeIO)
+
+        io.targets.compact.find(&:tty?)
+      end
+
+      def resolve_mode(io, config)
+        return :never if ENV["RUBIK_TEST"] == "1"
+        return :never if ENV["NO_COLOR"] && !ENV["NO_COLOR"].to_s.empty?
+        return :always if ENV["CLICOLOR_FORCE"] && ENV["CLICOLOR_FORCE"].to_s == "1"
+
+        cfg_mode = config&.fetch("ui.color", "auto").to_s.downcase if config
+        return :always if cfg_mode == "always"
+        return :never if cfg_mode == "never"
+
+        return :never if ENV["TERM"] && ENV["TERM"].downcase == "dumb"
+        return :never unless io.respond_to?(:tty?) && io.tty?
+
+        enable_windows_virtual_terminal_if_needed
+        :auto
+      end
+
+      # On legacy Windows consoles ANSI sequences are only rendered after
+      # ENABLE_VIRTUAL_TERMINAL_PROCESSING is set on the output handle.
+      # Modern terminals (Windows Terminal, WezTerm, Alacritty) already have
+      # it on; this is a best-effort, failure-tolerant probe.
+      def enable_windows_virtual_terminal_if_needed
+        return unless Gem.win_platform?
+        return if @vt_enabled
+
+        @vt_enabled = begin
+          require "fiddle"
+          kernel32 = Fiddle.dlopen("kernel32.dll")
+          get_std_handle = Fiddle::Function.new(kernel32["GetStdHandle"], [Fiddle::TYPE_LONG], Fiddle::TYPE_LONG)
+          get_console_mode = Fiddle::Function.new(kernel32["GetConsoleMode"],
+                                                  [Fiddle::TYPE_LONG, Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT)
+          set_console_mode = Fiddle::Function.new(kernel32["SetConsoleMode"],
+                                                  [Fiddle::TYPE_LONG, Fiddle::TYPE_LONG], Fiddle::TYPE_INT)
+          handle = get_std_handle.call(-11) # STD_OUTPUT_HANDLE
+          mode_buf = [0].pack("L")
+          ok = get_console_mode.call(handle, mode_buf)
+          if ok != 0
+            mode = mode_buf.unpack1("L")
+            vt_flag = 0x0004 # ENABLE_VIRTUAL_TERMINAL_PROCESSING
+            set_console_mode.call(handle, mode | vt_flag) != 0 if mode.nobits?(vt_flag)
+          end
+          true
+        rescue StandardError
+          false
+        end
+      end
+
+      def reset_memoization!
+        @vt_enabled = nil
+      end
+    end
+  end
+end

data/lib/rubik/ui/dialog.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+require_relative "capability"
+require_relative "frame"
+require_relative "theme"
+require_relative "../repl/interrupt_handler"
+
+module Rubik
+  module UI
+    # Interactive question and decision dialog for the human operator (Plan 92).
+    # Presents single-choice and multi-choice menus with clean ANSI/VT100 cards
+    # and handles keyboard interrupts gracefully.
+    class Dialog
+      attr_reader :shell, :theme
+
+      def initialize(shell: nil, theme: nil, prompt: nil)
+        @shell = shell
+        @theme = theme || Theme.for(shell&.output || $stdout, shell&.config)
+        @prompt = prompt
+      end
+
+      # Prompts the user with a single-choice question.
+      #
+      # @param question [String] Question text
+      # @param options [Array<String>] List of selectable options
+      # @param allow_custom [Boolean] Whether to provide a free-text write-in option
+      # @return [String, Symbol] Selected answer, custom string, or :cancelled
+      def ask_single(question, options, allow_custom: true)
+        return :non_interactive unless interactive?
+
+        render_card(question, multi: false)
+        p = build_prompt
+        choices = options.uniq.dup
+        choices << "Other (write-in response)" if allow_custom
+
+        answer = p.select("Seçiminizi yapın / Select an option:", choices, filter: true, per_page: 10)
+        if answer == "Other (write-in response)"
+          custom = p.ask("Yanıtınız / Your answer:")
+          custom.to_s.strip.empty? ? options.first : "Other (write-in): #{custom.strip}"
+        else
+          answer
+        end
+      rescue Interrupt, StandardError
+        :cancelled
+      ensure
+        restore_console
+      end
+
+      # Prompts the user with a multi-choice question.
+      #
+      # @param question [String] Question text
+      # @param options [Array<String>] List of selectable options
+      # @return [Array<String>, Symbol] Array of selected answers, or :cancelled
+      def ask_multi(question, options)
+        return :non_interactive unless interactive?
+
+        render_card(question, multi: true)
+        p = build_prompt
+        answers = p.multi_select("Seçenekleri belirleyin / Select options (Space: toggle, Enter: confirm):",
+                                 options.uniq, filter: true, per_page: 10)
+        answers.empty? ? [options.first] : answers
+      rescue Interrupt, StandardError
+        :cancelled
+      ensure
+        restore_console
+      end
+
+      # True when the input/output streams are interactive TTYs.
+      def interactive?
+        return true if @prompt # Injected prompt for test mockability
+
+        inp = @shell&.input || $stdin
+        out = @shell&.output || $stdout
+        Capability.interactive?(input: inp, output: out)
+      end
+
+      private
+
+      def render_card(question, multi: false)
+        return unless @shell&.output
+
+        subtitle = multi ? "Çoklu Seçim (Boşluk: Seç/Kaldır · Enter: Onayla)" : "Tekli Seçim (Ok tuşları: Gezin · Enter: Onayla)"
+        card = Frame.draw(
+          [@theme.paint(question, :bold), @theme.paint(subtitle, :dim)],
+          theme: @theme,
+          title: @theme.paint("#{@theme.glyph(:action)} AJAN SORUSU", :accent)
+        )
+        @shell.output.puts(card)
+      end
+
+      def build_prompt
+        return @prompt if @prompt
+
+        out = Capability.unwrap_tee(@shell&.output) || $stdout
+        TTY::Prompt.new(input: @shell&.input || $stdin, output: out)
+      end
+
+      def restore_console
+        Rubik::REPL::InterruptHandler.restore_console_after_interrupt
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end