rubyn-code 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5cbf6f4737790408893a904d64412c2dd695e81a2cd2e5960b4da3196e48f4f
-  data.tar.gz: f0e9b80f10c77d6eb6c357db7518851344670653546d5eca2784d017d490608c
+  metadata.gz: d43be98f4e24cc9bc78bc541ed0554731ed88985adb56ec5700d643dc4fd2ba2
+  data.tar.gz: d6adda167ad528fde80900dfb4c5d7114029695c4ae83f814ad2130b2f531781
 SHA512:
-  metadata.gz: bc4553f04fbac43903e1515cec43cf595245d36223bca70342ddafb2a2920f38f502b356eb353b4b6e5284d128688e07c015e0a3ebb4aa06f7029fac0ba42a37
-  data.tar.gz: b9f8ab09a40e073bff1657ef9d829b7551a5ca56ce9f77b65bd59b835d079665d3663faf92ccf44fd84d4ff3674f835c09d102b4f449c175c77bcafb466dd934
+  metadata.gz: 3352ad014212276c17d5a96adb3d3dcf43165dffb77b8a95d01ce22bf3fdd57786abca291c4604e937cef26b070b3d43ae791430da30d84baa49a76e753d8f28
+  data.tar.gz: 767c3be54cee4d94e157dd7ae73287c5306159586f3057eac199175aa0ac79aba3ef35046cc4eef6936c6f80802277bf578e5588c35b2fd8940d8aa58037c07e

data/README.md

@@ -15,7 +15,7 @@
   <a href="https://github.com/MatthewSuttles/rubyn-code/actions/workflows/ci.yml"><img src="https://github.com/MatthewSuttles/rubyn-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
 </p>
 
-Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code for anti-patterns, and build entire features — all context-aware with your schema, routes, and specs. Powered by Claude Opus 4.6, running on your existing Claude subscription.
+Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code for anti-patterns, and build entire features — all context-aware with your schema, routes, and specs. Powered by Claude Opus 5, running on your existing Claude subscription.
 
 <img width="1230" height="280" alt="image" src="https://github.com/user-attachments/assets/14e07ce8-def0-4a8f-ac89-46661361a4eb" />
 
@@ -31,7 +31,7 @@ Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code f
 - [Quick Start](#quick-start)
 - [What Can Rubyn Do?](#what-can-rubyn-do)
 - [VS Code Extension](#vs-code-extension)
-- [29 Built-in Tools](#29-built-in-tools)
+- [32 Built-in Tools](#32-built-in-tools)
 - [MCP — External Tool Servers](#mcp--external-tool-servers)
 - [Codebase Indexing](#codebase-indexing)
 - [112 Best Practice Skills](#112-best-practice-skills)
@@ -69,6 +69,22 @@ Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code f
 - **IDE-ready** — works in the terminal and inside VS Code with full bidirectional communication
 - **Extensible** — connect external tool servers via MCP, add custom skills, or wire up your own providers
 
+## Claude Code Feature Parity
+
+Phase 4 ships nine parity features with Claude Code:
+
+- **Extended thinking** — `/think <budget>` toggles per-session reasoning; the Anthropic adapter emits `thinking: {type: 'adaptive'}` on Claude 4.6+ models (`{type: 'enabled', budget_tokens}` on older ones).
+- **Reasoning effort** — `/effort <low|medium|high|xhigh|max>` sets the request-level reasoning depth; the Anthropic adapter emits `output_config: {effort}` on the wire. GA on Claude 4.6+ (Opus 4.6/4.7/4.8/5, Sonnet 4.6/5, Fable 5); `xhigh` needs Opus 4.7+ / Sonnet 5 / Fable 5. Model default is `high`.
+- **Task budgets (beta)** — the agent loop's remaining token budget is sent as `output_config: {task_budget: {type: 'tokens', total}}` on supported models (Fable 5, Sonnet 5, Opus 5, Opus 4.7/4.8), advisory pacing only — `max_tokens` stays the enforced per-response cap.
+- **Image / vision input** — `@chart.png` (and `.jpg` / `.jpeg` / `.gif` / `.webp`) becomes a real image content block attached to the user turn; Anthropic and OpenAI each emit their native shape.
+- **TodoWrite live checklist** — `TodoWrite` tool; the checklist refreshes above the spinner on every tool result so you see in-turn progress at a glance.
+- **Custom-command frontmatter** — `argument-hint`, `allowed-tools`, and `model:` keys in `~/.rubyn-code/commands/*.md`; the loop honors the per-prompt tool restriction and model override.
+- **`.mcp.json` auto-discovery** — project-root MCP servers flow into the REPL automatically; `/mcp` shows entries prefixed `[project]` or `[user]`. OAuth for URL transports is still deferred.
+- **`/export` transcript** — `/export <path>` writes the conversation as Markdown (default) or `--jsonl` for tooling.
+- **Fable 5 refusal handling** — a declined request (`stop_reason: "refusal"`) surfaces a clear message instead of an empty turn; `claude-fable-5` / `claude-mythos-5` requests opt into a server-side Opus 4.8 fallback by default, so most refusals are transparently re-served in the same call.
+
+See `docs/04-feature-parity/` for per-feature design + tasks docs.
+
 ## Install
 
 Requires **Ruby 4.0.2+**. Install with your latest Ruby, then pin it so it works in every project:
@@ -199,7 +215,7 @@ Rubyn Code includes a VS Code extension that provides a full IDE experience with
 - Full session management — resume, list, fork, and reset conversations
 - Structured code review feedback with severity ratings
 - IDE config get/set for persistent settings
-- All 29 tools available, including MCP tools
+- All 32 tools available, including MCP tools
 
 **Permission modes:**
 
@@ -210,19 +226,19 @@ Rubyn Code includes a VS Code extension that provides a full IDE experience with
 
 The extension communicates over 19 RPC methods: `initialize`, `prompt`, `cancel`, `review`, `approveToolUse`, `acceptEdit`, `session/*`, `config/*`, `models/list`, `plan/propose`, `plan/interview/*` (chat-resident [megaplan](#megaplan--phased-planning)), `recover_ci`, and `shutdown`.
 
-## 29 Built-in Tools
+## 32 Built-in Tools
 
 | Category | Tools |
 |----------|-------|
 | **File I/O** | `read_file`, `write_file`, `edit_file` |
-| **Search** | `glob`, `grep` |
+| **Search** | `glob`, `grep`, `code_graph` |
 | **Execution** | `bash` (sandboxed, dangerous commands blocked) |
 | **Web** | `web_search`, `web_fetch` |
 | **Git** | `git_status`, `git_diff`, `git_log`, `git_commit` |
 | **Rails** | `rails_generate`, `db_migrate`, `run_specs`, `bundle_install`, `bundle_add` |
 | **Review** | `review_pr` (diff-based best practice code review) |
-| **Agents** | `spawn_agent`, `spawn_teammate`, `background_run` |
-| **Context** | `compact`, `load_skill`, `task` |
+| **Agents** | `spawn_agent`, `spawn_teammate`, `background_run`, `phone_a_friend` |
+| **Context** | `compact`, `load_skill`, `task`, `todo_write` |
 | **Memory** | `memory_search`, `memory_write` |
 | **Teams** | `send_message`, `read_inbox` |
 | **Interactive** | `ask_user` (ask clarifying questions mid-task) |
@@ -502,6 +518,18 @@ rubyn > Send alice a message to write specs for the User model
 
 Teammates run in background threads with their own agent loop and mailbox.
 
+### Phone a Friend (second opinion)
+
+When the agent is stuck or weighing two approaches, the `phone_a_friend` tool asks a *different* model for a one-shot second opinion. The friend is picked for perspective diversity: the top-tier model of another configured provider whose API key is present (a genuinely different model family), falling back to the active provider's top tier. The friend gets no tools and no conversation history — only the question and whatever context the agent chooses to send — and its answer comes back as plain text labeled with the provider and model that gave it.
+
+```
+rubyn > I keep going back and forth on STI vs polymorphic here...
+
+[tool] phone_a_friend
+## Second Opinion — openai/gpt-5.4
+Commit to the polymorphic association. The key reason: ...
+```
+
 ## GOLEM — Autonomous Daemon
 
 GOLEM is an always-on autonomous agent that claims tasks from a queue and works through them independently. It runs a full agent loop per task with access to all tools, MCP servers, and memory.
@@ -675,7 +703,7 @@ Rubyn snapshots a checkpoint at the start of every turn — capturing the conver
 | 2 | Token file | `~/.rubyn-code/tokens.yml` |
 | 3 | Environment | `export ANTHROPIC_API_KEY=sk-ant-...` |
 
-Works with Claude Pro, Max, Team, and Enterprise. Default model: **Claude Opus 4.6**.
+Works with Claude Pro, Max, Team, and Enterprise. Default model: **Claude Opus 5**.
 
 ### OpenAI
 
@@ -693,7 +721,7 @@ Add a provider and its API key in one command:
 /provider add groq https://api.groq.com/openai/v1 --key gsk-xxx --models llama-3.3-70b
 
 # For Anthropic-format proxies (e.g., Bedrock, custom gateways)
-/provider add my-proxy https://proxy.example.com/v1 --format anthropic --key sk-xxx --models claude-sonnet-4-6
+/provider add my-proxy https://proxy.example.com/v1 --format anthropic --key sk-xxx --models claude-sonnet-5
 
 # Update a key later
 /provider set-key groq gsk-new-key
@@ -724,7 +752,7 @@ providers:
     base_url: https://proxy.example.com/v1
     env_key: PROXY_API_KEY
     models:
-      top: claude-sonnet-4-6
+      top: claude-sonnet-5
 ```
 
 Then switch with `/model groq:llama-3.3-70b`.
@@ -751,7 +779,7 @@ Local providers (Ollama, LM Studio) running on `localhost`/`127.0.0.1` don't req
 │  Layer 5:  Skills (112 best practice docs, on-demand loading) │
 │  Layer 4:  Context Management (3-layer compression pipeline)  │
 │  Layer 3:  Permissions (tiered access + deny lists + hooks)   │
-│  Layer 2:  Tool System (29 tools, dispatch map registry)      │
+│  Layer 2:  Tool System (32 tools, dispatch map registry)      │
 │  Layer 1:  THE AGENT LOOP (while tool_use → execute → repeat) │
 └──────────────────────────────────────────────────────────────┘
 ```
@@ -764,7 +792,7 @@ These must match a provider defined in the `providers` section (or a built-in li
 ```yaml
 # ~/.rubyn-code/config.yml (global)
 provider: anthropic              # default provider on startup
-model: claude-opus-4-6           # default model on startup
+model: claude-opus-5             # default model on startup
 permission_mode: allow_read
 session_budget: 5.00
 daily_budget: 10.00
@@ -782,15 +810,15 @@ Rubyn can automatically route tasks to different AI models based on complexity.
 ```yaml
 # ~/.rubyn-code/config.yml
 provider: anthropic
-model: claude-opus-4-6
+model: claude-opus-5
 
 providers:
   anthropic:
     env_key: ANTHROPIC_API_KEY
     models:
       cheap: claude-haiku-4-5      # file search, git ops, formatting
-      mid: claude-sonnet-4-6       # code gen, specs, refactors, reviews
-      top: claude-opus-4-6         # architecture, security, complex work
+      mid: claude-sonnet-5         # code gen, specs, refactors, reviews
+      top: claude-opus-5           # architecture, security, complex work
 
   openai:
     env_key: OPENAI_API_KEY
@@ -822,8 +850,8 @@ providers:
 | Tier | Task types | Default model |
 |------|-----------|---------------|
 | **cheap** | File search, git ops, formatting, summaries | `claude-haiku-4-5` |
-| **mid** | Code generation, specs, refactors, code review, bug fixes | `claude-sonnet-4-6` |
-| **top** | Architecture, security review, complex refactors, planning | `claude-opus-4-6` |
+| **mid** | Code generation, specs, refactors, code review, bug fixes | `claude-sonnet-5` |
+| **top** | Architecture, security review, complex refactors, planning | `claude-opus-5` |
 
 You can also set custom pricing per model so `/cost` reports accurate spending for third-party providers.
 

data/lib/rubyn_code/agent/conversation.rb

@@ -14,7 +14,10 @@ module RubynCode
 
       # Append a user turn to the conversation.
       #
-      # @param content [String]
+      # @param content [String, Array<Hash>] either a plain string or an
+      #   array of content blocks (text, image, etc.). Strings get wrapped
+      #   as `[{ type: 'text', text: content }]` only if there's a planned
+      #   Array; we keep raw String for backward compatibility with the API.
       # @return [Hash] the appended message
       def add_user_message(content)
         message = { role: 'user', content: content }
@@ -155,6 +158,13 @@ module RubynCode
         reset_derived_state!
       end
 
+      # Alias for `messages`. Common shorthand for callers that want to
+      # treat the conversation as an Array of message hashes.
+      def to_a
+        @messages
+      end
+      alias to_ary to_a
+
       private
 
       # Derived bookkeeping kept in sync with @messages so hot paths stay

data/lib/rubyn_code/agent/dynamic_tool_schema.rb

@@ -8,7 +8,7 @@ module RubynCode
     # prompt overhead by 30-50%.
     module DynamicToolSchema
       BASE_TOOLS = %w[
-        read_file write_file edit_file glob grep bash
+        read_file write_file edit_file glob grep code_graph bash
       ].freeze
 
       TASK_TOOLS = {

data/lib/rubyn_code/agent/llm_caller.rb

@@ -25,7 +25,7 @@ module RubynCode
       def build_llm_opts
         opts = {
           messages: @conversation.to_api_format,
-          tools: @plan_mode ? read_only_tool_definitions : tool_definitions,
+          tools: filtered_tool_definitions,
           system: build_system_prompt,
           on_text: @on_text
         }
@@ -36,6 +36,8 @@ module RubynCode
             total: UsageTracker::TASK_BUDGET_TOTAL, remaining: @task_budget_remaining
           }
         end
+        budget = @llm_client.respond_to?(:thinking_budget_tokens) ? @llm_client.thinking_budget_tokens.to_i : 0
+        opts[:thinking] = { budget_tokens: budget } if budget.positive?
         opts
       end
 
@@ -45,6 +47,8 @@ module RubynCode
       # Falls back to nil (use client's default) if routing fails.
       # -- guard clauses for provider/mode checks
       def routed_model
+        return @model_override if @model_override
+
         return nil if manual_model_mode?
 
         last_user = last_user_message_text

data/lib/rubyn_code/agent/loop.rb

@@ -53,8 +53,11 @@ module RubynCode
       # response is produced or the iteration limit is reached.
       #
       # @param user_input [String]
+      # @param blocks [Array<Hash>, nil] extra content blocks to attach to the
+      #   user message (e.g. image blocks from @-mentions). When non-empty the
+      #   user message is stored as a mixed content array instead of a string.
       # @return [String] the final assistant text response
-      def send_message(user_input)
+      def send_message(user_input, blocks: nil)
         initialize_session!
         check_user_feedback(user_input)
         drain_background_notifications
@@ -62,7 +65,7 @@ module RubynCode
         @decision_compactor&.detect_topic_switch(user_input)
         @skill_ttl&.tick!
         autoload_triggered_skills(user_input)
-        @conversation.add_user_message(user_input)
+        append_user_message(user_input, blocks)
         reset_system_prompt_cache!
         reset_iteration_state
 
@@ -79,8 +82,38 @@ module RubynCode
         max_iterations_warning(iteration)
       end
 
+      # Append the user turn to the conversation. If image blocks were passed
+      # via `blocks:`, the message is stored as a mixed content array with a
+      # leading text block and the image blocks appended in order.
+      def append_user_message(user_input, blocks)
+        if blocks.is_a?(Array) && !blocks.empty?
+          content = [{ type: 'text', text: user_input.to_s }, *blocks]
+          @conversation.add_user_message(content)
+        else
+          @conversation.add_user_message(user_input)
+        end
+      end
+
+      # @return [Tools::TodoStore] shared checklist store, exposed for the REPL renderer
+      attr_reader :todo_store
+
+      # Apply a one-shot model override for the duration of the next LLM call.
+      # Used by `Context#with_optional_model` for custom-command frontmatter.
+      def model_override=(model_name)
+        stripped = model_name.to_s.strip
+        @model_override = stripped.empty? ? nil : stripped
+      end
+
+      # Restrict the available tool set for the next LLM call only.
+      # @param allowed [Array<String>, nil] tool names, or nil to clear the override.
+      def allowed_tools_override=(allowed)
+        @allowed_tools_override = allowed.is_a?(Array) && !allowed.empty? ? allowed : nil
+      end
+
       private
 
+      # Overrides the region above. The internal helpers below are private.
+
       # Decide whether the loop should run another iteration after `iteration`
       # turns. Normally capped at MAX_ITERATIONS, but while a Stop hook (e.g. an
       # active /goal) is keeping the agent alive we extend up to a hard ceiling
@@ -119,6 +152,8 @@ module RubynCode
         @tool_wrapper       = opts[:tool_wrapper]
         @decision_compactor = build_decision_compactor
         @skill_ttl          = Skills::TtlManager.new
+        @todo_store         = opts.fetch(:todo_store, Tools::TodoStore.new)
+        @tool_executor.todo_store = @todo_store
         @session_initialized = false
       end
 
@@ -133,6 +168,7 @@ module RubynCode
       def initialize_session!
         return if @session_initialized || !@project_root
 
+        @todo_store&.clear
         @session_initialized = true
         build_project_profile!
         build_codebase_index!
@@ -168,13 +204,17 @@ module RubynCode
         @output_recovery_count = 0
         @task_budget_remaining = nil
         @stop_block_active     = false # true while a Stop hook keeps us going
+        @allowed_tools_override = nil   # set by Context#with_allowed_tools
+        @model_override         = nil   # set by Context#with_optional_model
       end
 
       def run_iteration(iteration)
         log_iteration(iteration)
         @context_manager.advance_turn!
         compact_if_needed # ensure context is under threshold before LLM call
-        response   = call_llm
+        response = call_llm
+        return handle_refusal(response) if extract_stop_reason(response) == 'refusal'
+
         tool_calls = extract_tool_calls(response)
         log_response(response, tool_calls)
 
@@ -183,6 +223,20 @@ module RubynCode
         handle_tool_response(response, tool_calls, iteration)
       end
 
+      # Claude's safety classifiers declined the request outright (HTTP 200,
+      # stop_reason: "refusal"). Surface a clear message instead of falling
+      # through to text/empty-response handling, which would misread the
+      # empty or partial content as "waiting on background jobs".
+      def handle_refusal(response)
+        details = extract_stop_details(response)
+        category = details.is_a?(Hash) ? (details['category'] || details[:category]) : nil
+        RubynCode::Debug.llm("Refusal: category=#{category || 'unknown'}")
+
+        message = "Claude's safety system declined this request (category: #{category || 'unknown'})."
+        @conversation.add_assistant_message([{ type: 'text', text: message }])
+        message
+      end
+
       def log_iteration(iteration)
         RubynCode::Debug.loop_tick(
           "iteration=#{iteration} messages=#{@conversation.length} " \

data/lib/rubyn_code/agent/response_parser.rb

@@ -61,6 +61,14 @@ module RubynCode
         end
       end
 
+      def extract_stop_details(response)
+        if response.respond_to?(:stop_details)
+          response.stop_details
+        elsif response.is_a?(Hash)
+          response[:stop_details] || response['stop_details']
+        end
+      end
+
       def recover_truncated_response(response)
         @max_tokens_override ||= Config::Defaults::ESCALATED_MAX_OUTPUT_TOKENS
         @conversation.add_assistant_message(response_content(response))

data/lib/rubyn_code/agent/system_prompt_builder.rb

@@ -101,6 +101,9 @@ module RubynCode
         return unless index&.nodes&.any?
 
         parts << "\n## #{index.to_structural_summary}"
+        parts << 'This project has a code graph. To locate or understand code, call `code_graph` FIRST — ' \
+                 'it returns matching symbols with source, callers, and callees in one call. ' \
+                 'Fall back to grep/glob only when code_graph finds nothing.'
       rescue StandardError
         nil
       end

data/lib/rubyn_code/agent/tool_processor.rb

@@ -52,6 +52,16 @@ module RubynCode
         Tools::Registry.all.select { |t| PLAN_MODE_RISK_LEVELS.include?(t::RISK_LEVEL) }.map(&:to_schema)
       end
 
+      # Tool definitions for the next LLM call: plan mode narrows to
+      # read-only tools; a per-turn allowed-tools override (custom-command
+      # frontmatter, set via Loop#allowed_tools_override=) narrows by name.
+      def filtered_tool_definitions
+        defs = @plan_mode ? read_only_tool_definitions : tool_definitions
+        return defs unless @allowed_tools_override
+
+        DynamicToolSchema.filter(defs, active_names: @allowed_tools_override)
+      end
+
       # -- tool dispatch with budget + signals
       def process_tool_calls(tool_calls)
         aggregate_chars = 0

data/lib/rubyn_code/autonomous/daemon.rb

@@ -212,7 +212,7 @@ module RubynCode
         tokens = extract_token_counts(cm)
         return if tokens.values.all?(&:zero?)
 
-        model = @llm_client.respond_to?(:model) ? @llm_client.model : 'claude-sonnet-4-6'
+        model = @llm_client.respond_to?(:model) ? @llm_client.model : 'claude-sonnet-5'
         @total_cost += Observability::CostCalculator.calculate(model: model, **tokens)
       rescue StandardError
         # Non-critical — cost tracking is best-effort

data/lib/rubyn_code/cli/commands/context.rb

@@ -40,6 +40,33 @@ module RubynCode
 
         # @return [Boolean]
         def plan_mode? = plan_mode
+
+        # Restrict the tool set for a single agent invocation. The next
+        # `send_message` call inside the block sees only the tools in
+        # `allowed`; the override is cleared after the call.
+        def with_allowed_tools(allowed = nil, &block)
+          apply_loop_override(:allowed_tools_override=, allowed, &block)
+        end
+
+        # Apply a one-shot model override for the duration of a block.
+        def with_optional_model(model_name = nil, &block)
+          apply_loop_override(:model_override=, model_name, &block)
+        end
+
+        private
+
+        # Set an override on the agent loop (when one is wired in) for the
+        # duration of the block, then clear it. Custom commands without
+        # a loop (e.g. test doubles) fall through to a plain yield.
+        def apply_loop_override(method, value)
+          loop = agent_loop
+          return yield unless loop.respond_to?(method)
+
+          loop.public_send(method, value)
+          yield
+        ensure
+          loop&.public_send(method, nil) if loop.respond_to?(method)
+        end
       end
     end
   end

data/lib/rubyn_code/cli/commands/custom_command.rb

@@ -14,13 +14,24 @@ module RubynCode
         attr_reader :name
         # @return [String] one-line description for /help
         attr_reader :description
+        # @return [String, nil] argument hint shown next to the name in /help
+        attr_reader :argument_hint
+        # @return [Array<String>, nil] tool names the command restricts to
+        attr_reader :allowed_tools
+        # @return [String, nil] model override for this prompt
+        attr_reader :model
         # @return [String, nil] originating file path
         attr_reader :source
 
-        def initialize(name:, description:, body:, source: nil)
+        def initialize(name:, description:, body:, # rubocop:disable Metrics/ParameterLists -- explicit kwargs document the frontmatter surface
+                       source: nil,
+                       argument_hint: nil, allowed_tools: nil, model: nil)
           @name = name
           @description = description
           @template = CommandTemplate.new(body)
+          @argument_hint = argument_hint
+          @allowed_tools = allowed_tools
+          @model = model
           @source = source
         end
 
@@ -29,11 +40,42 @@ module RubynCode
         def hidden? = false
         def all_names = [command_name].freeze
 
+        # Render the help label, including [hint] when frontmatter provides one.
+        # The argument_hint is expected to be the placeholder text already wrapped
+        # in [ ] (e.g. "[env]") — we don't add another set of brackets.
+        def help_label
+          hint = @argument_hint.to_s.strip
+          hint.empty? ? description : "#{description}  #{hint}"
+        end
+
+        # @return [Boolean] true if the frontmatter restricted the tool set
+        def restricts_tools?
+          !@allowed_tools.nil? && !@allowed_tools.empty?
+        end
+
+        # @return [Boolean] true if the frontmatter overrode the model
+        def overrides_model?
+          !@model.to_s.strip.empty?
+        end
+
         # @param args [Array<String>]
         # @param ctx [Commands::Context]
         # @return [nil]
         def execute(args, ctx)
-          ctx.send_message(@template.render(args))
+          rendered = @template.render(args)
+          if restricts_tools?
+            ctx.with_allowed_tools(@allowed_tools) do
+              ctx.with_optional_model(@model) do
+                ctx.send_message(rendered)
+              end
+            end
+          elsif overrides_model?
+            ctx.with_optional_model(@model) do
+              ctx.send_message(rendered)
+            end
+          else
+            ctx.send_message(rendered)
+          end
           nil
         end
       end

data/lib/rubyn_code/cli/commands/custom_loader.rb

@@ -40,9 +40,18 @@ module RubynCode
             name = File.basename(path, '.md').strip
             return nil unless name.match?(NAME)
 
-            description, body = parse(File.read(path))
-            description = "Custom command: /#{name}" if description.to_s.strip.empty?
-            CustomCommand.new(name: name, description: description, body: body, source: path)
+            meta, body = parse(File.read(path))
+            description = meta['description'].to_s
+            description = "Custom command: /#{name}" if description.strip.empty?
+            CustomCommand.new(
+              name: name,
+              description: description,
+              body: body,
+              source: path,
+              argument_hint: blank_to_nil(stringify(meta['argument_hint'] || meta['argument-hint'])),
+              allowed_tools: list_of_tools(meta['allowed_tools'] || meta['allowed-tools']),
+              model: blank_to_nil(stringify(meta['model']))
+            )
           rescue StandardError => e
             RubynCode::Debug.warn("Failed to load custom command #{path}: #{e.message}")
             nil
@@ -51,13 +60,35 @@ module RubynCode
           def parse(content)
             if (match = FRONTMATTER.match(content))
               frontmatter = YAML.safe_load(match[1]) || {}
-              [frontmatter['description'].to_s, match[2].to_s.strip]
+              [frontmatter, match[2].to_s.strip]
             else
               body = content.to_s.strip
-              [first_line(body), body]
+              [{ 'description' => first_line(body) }, body]
             end
           end
 
+          def blank_to_nil(value)
+            value.to_s.strip.empty? ? nil : value
+          end
+
+          def stringify(value)
+            return '' if value.nil?
+
+            # YAML's flow-style `[env]` is parsed as a single-element array.
+            # Stringify the array element directly so users see exactly the
+            # characters they typed.
+            str = value.is_a?(Array) ? value.join : value
+            str.to_s.strip
+          end
+
+          def list_of_tools(value)
+            return nil if value.nil?
+
+            arr = value.is_a?(Array) ? value : value.to_s.split(',')
+            cleaned = arr.map { |name| name.to_s.strip }.reject(&:empty?)
+            cleaned.empty? ? nil : cleaned
+          end
+
           def first_line(body)
             line = body.lines.first.to_s.strip
             line.sub(/\A#+\s*/, '')[0, 80]

data/lib/rubyn_code/cli/commands/effort.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # Set or clear the reasoning effort level (output_config.effort).
+      #
+      #   /effort             # show current value
+      #   /effort off         # clear back to model default
+      #   /effort <level>     # low | medium | high | xhigh | max
+      class Effort < Base
+        LEVELS = %w[low medium high xhigh max].freeze
+
+        def self.command_name = '/effort'
+        def self.description = 'Set reasoning effort (low/medium/high/xhigh/max)'
+
+        def execute(args, ctx)
+          arg = args.first
+
+          current = ctx.llm_client.respond_to?(:effort) ? ctx.llm_client.effort : nil
+
+          case arg
+          when nil
+            show_status(current, ctx)
+          when 'off'
+            ctx.llm_client.effort = nil
+            ctx.renderer.info('Reasoning effort cleared — using model default 🎚️')
+          when *LEVELS
+            ctx.llm_client.effort = arg
+            ctx.renderer.info("Reasoning effort set to #{arg} 🎚️")
+          else
+            ctx.renderer.warning("Usage: /effort [off|#{LEVELS.join('|')}]. Got: #{arg}")
+          end
+        end
+
+        private
+
+        def show_status(current, ctx)
+          state = current || 'not set (model default: high on 4.6+)'
+          ctx.renderer.info("Reasoning effort: #{state}")
+          ctx.renderer.info("Usage: /effort <level>  levels: #{LEVELS.join(', ')}   (or /effort off)")
+          ctx.renderer.info('Supported on Claude 4.6+ models; xhigh requires Opus 4.7+ / Sonnet 5 / Fable 5.')
+        end
+      end
+    end
+  end
+end