rubik 0.2.0 → 0.3.1

data/lib/rubik/sandbox/driver/docker.rb

@@ -18,7 +18,6 @@ module Rubik
         end
 
         def run(cmd, timeout: 15, chdir: Dir.pwd, allow_network: false, memory_limit_mb: 512, cpus: "1.0")
-          start_time = Time.now
           image = @options[:image] || DEFAULT_IMAGE
           workspace = File.expand_path(chdir)
           container_name = "rubik-box-#{SecureRandom.hex(6)}"
@@ -40,70 +39,25 @@ module Rubik
           docker_args.push("--network", "none") unless allow_network
           docker_args.push(image, "sh", "-c", cmd)
 
-          stdout_str = ""
-          stderr_str = ""
-          exit_code = 127
-          wait_thr_ref = nil
-
-          begin
-            Timeout.timeout(timeout) do
-              Open3.popen3(*docker_args) do |stdin, stdout, stderr, wait_thr|
-                wait_thr_ref = wait_thr
-                begin
-                  stdin.close
-                rescue StandardError
-                  nil
-                end
-                t_out = Thread.new do
-                  stdout.read
-                rescue StandardError
-                  ""
-                end
-                t_err = Thread.new do
-                  stderr.read
-                rescue StandardError
-                  ""
-                end
-                begin
-                  stdout_str = t_out.value.to_s
-                  stderr_str = t_err.value.to_s
-                  status = wait_thr.value
-                  exit_code = status.exitstatus || (status.signaled? ? (128 + (status.termsig || 1)) : 1)
-                ensure
-                  begin
-                    t_out.kill
-                  rescue StandardError
-                    nil
-                  end
-                  begin
-                    t_err.kill
-                  rescue StandardError
-                    nil
-                  end
-                end
-              end
-            end
-          rescue Timeout::Error
-            Rubik::Platform.kill_tree(wait_thr_ref.pid) if wait_thr_ref.respond_to?(:pid) && wait_thr_ref.pid
-            system("docker rm -f #{container_name} > #{Rubik::Platform.dev_null} 2>&1")
-            stderr_str = "Docker sandbox execution timed out after #{timeout} seconds"
-            exit_code = 124
-          rescue StandardError => e
-            stderr_str = "Docker sandbox error: #{e.message}"
-            exit_code = 1
+          res = begin
+            Rubik::Platform.popen_capture(
+              *docker_args,
+              timeout: timeout,
+              chdir: workspace,
+              timeout_message: "Docker sandbox execution timed out after #{timeout} seconds",
+              error_message: "Docker sandbox error"
+            )
           ensure
-            Rubik::Platform.kill_tree(wait_thr_ref.pid) if wait_thr_ref.respond_to?(:pid) && wait_thr_ref.pid
             system("docker rm -f #{container_name} > #{Rubik::Platform.dev_null} 2>&1")
           end
 
-          duration = Time.now - start_time
           {
-            ok: exit_code.zero?,
-            exit_code: exit_code,
-            stdout: stdout_str,
-            stderr: stderr_str,
-            output: [stdout_str, stderr_str].reject(&:empty?).join("\n"),
-            duration: duration.round(4),
+            ok: res[:ok],
+            exit_code: res[:exit_code],
+            stdout: res[:stdout],
+            stderr: res[:stderr],
+            output: res[:output],
+            duration: res[:duration],
             driver: "docker"
           }
         end

data/lib/rubik/sandbox/driver/podman.rb

@@ -16,7 +16,6 @@ module Rubik
         end
 
         def run(cmd, timeout: 15, chdir: Dir.pwd, allow_network: false, memory_limit_mb: 512, cpus: "1.0")
-          start_time = Time.now
           image = @options[:image] || DEFAULT_IMAGE
           workspace = File.expand_path(chdir)
 
@@ -32,63 +31,21 @@ module Rubik
           podman_args.push("--network", "none") unless allow_network
           podman_args.push(image, "sh", "-c", cmd)
 
-          stdout_str = ""
-          stderr_str = ""
-          exit_code = 127
+          res = Rubik::Platform.popen_capture(
+            *podman_args,
+            timeout: timeout,
+            chdir: workspace,
+            timeout_message: "Podman sandbox execution timed out after #{timeout} seconds",
+            error_message: "Podman sandbox error"
+          )
 
-          begin
-            Timeout.timeout(timeout) do
-              Open3.popen3(*podman_args) do |stdin, stdout, stderr, wait_thr|
-                begin
-                  stdin.close
-                rescue
-                  nil
-                end
-                t_out = Thread.new do
-                  stdout.read
-                rescue
-                  ""
-                end
-                t_err = Thread.new do
-                  stderr.read
-                rescue
-                  ""
-                end
-                begin
-                  stdout_str = t_out.value.to_s
-                  stderr_str = t_err.value.to_s
-                  status = wait_thr.value
-                  exit_code = status.exitstatus || (status.signaled? ? (128 + (status.termsig || 1)) : 1)
-                ensure
-                  begin
-                    t_out.kill
-                  rescue
-                    nil
-                  end
-                  begin
-                    t_err.kill
-                  rescue
-                    nil
-                  end
-                end
-              end
-            end
-          rescue Timeout::Error
-            stderr_str = "Podman sandbox execution timed out after #{timeout} seconds"
-            exit_code = 124
-          rescue StandardError => e
-            stderr_str = "Podman sandbox error: #{e.message}"
-            exit_code = 1
-          end
-
-          duration = Time.now - start_time
           {
-            ok: exit_code.zero?,
-            exit_code: exit_code,
-            stdout: stdout_str,
-            stderr: stderr_str,
-            output: [stdout_str, stderr_str].reject(&:empty?).join("\n"),
-            duration: duration.round(4),
+            ok: res[:ok],
+            exit_code: res[:exit_code],
+            stdout: res[:stdout],
+            stderr: res[:stderr],
+            output: res[:output],
+            duration: res[:duration],
             driver: "podman"
           }
         end

data/lib/rubik/sandbox/driver/process.rb

@@ -15,80 +15,28 @@ module Rubik
         end
 
         def run(cmd, timeout: 15, chdir: Dir.pwd, allow_network: false, memory_limit_mb: 512, cpus: "1.0") # rubocop:disable Lint/UnusedMethodArgument -- sürücü arayüzü kwarg'leri korunuyor
-          start_time = Time.now
-          stdout_str = ""
-          stderr_str = ""
-          exit_code = 127
-
-          # Explicit-argv spawn (Plan 55 D-1): never leave interpreter choice
-          # to Open3's string form — on Windows that silently means cmd.exe.
           resolved = ShellResolver.resolve(cmd, preference: @options[:shell] || "auto")
-
           env = {}
-          # Direct host execution does NOT inject misleading dead proxy variables (127.0.0.1:9999).
-          # Hardware/namespace network isolation is only provided when a true sandbox
-          # (Bubblewrap, Docker, Podman) is enabled.
 
-          pid = nil
-          begin
-            Timeout.timeout(timeout) do
-              Open3.popen3(env, *spawn_args_for(resolved, cmd), chdir: chdir) do |stdin, stdout, stderr, wait_thr|
-                pid = wait_thr.pid
-                begin
-                  stdin.close
-                rescue
-                  nil
-                end
-                t_out = Thread.new do
-                  stdout.read
-                rescue
-                  ""
-                end
-                t_err = Thread.new do
-                  stderr.read
-                rescue
-                  ""
-                end
-                begin
-                  stdout_str = t_out.value.to_s
-                  stderr_str = t_err.value.to_s
-                  status = wait_thr.value
-                  exit_code = status.exitstatus || (status.signaled? ? (128 + (status.termsig || 1)) : 1)
-                ensure
-                  begin
-                    t_out.kill
-                  rescue
-                    nil
-                  end
-                  begin
-                    t_err.kill
-                  rescue
-                    nil
-                  end
-                end
-              end
-            end
-          rescue Timeout::Error
-            Rubik::Platform.kill_tree(pid) if pid
-            stderr_str = "Execution timed out after #{timeout} seconds"
-            exit_code = 124
-          rescue StandardError => e
-            stderr_str = "Execution error: #{e.message}"
-            exit_code = 1
-          end
+          res = Rubik::Platform.popen_capture(
+            env,
+            *spawn_args_for(resolved, cmd),
+            timeout: timeout,
+            chdir: chdir
+          )
 
-          duration = Time.now - start_time
-          stderr_out = resolved[:note] ? "#{resolved[:note]}\n#{stderr_str}" : stderr_str
+          stderr_out = resolved[:note] ? "#{resolved[:note]}\n#{res[:stderr]}" : res[:stderr]
           require_relative "../../security/redactor" unless defined?(Rubik::Security::Redactor)
-          clean_stdout = Rubik::Security::Redactor.redact(stdout_str)
+          clean_stdout = Rubik::Security::Redactor.redact(res[:stdout])
           clean_stderr = Rubik::Security::Redactor.redact(stderr_out)
+
           {
-            ok: exit_code.zero?,
-            exit_code: exit_code,
+            ok: res[:ok],
+            exit_code: res[:exit_code],
             stdout: clean_stdout,
             stderr: clean_stderr,
             output: [clean_stdout, clean_stderr].reject(&:empty?).join("\n"),
-            duration: duration.round(4),
+            duration: res[:duration],
             driver: "process",
             shell: resolved[:shell]
           }

data/lib/rubik/security/guard.rb

@@ -808,7 +808,7 @@ module Rubik
 
       # ── Synthesis capability table (Candidate 07) ───────────────────────
       # The ONE declaration point for everything the synthesis AST walk
-      # denies (ARCHITECTURE.md §2 "single declaration point" doctrine; §8.3
+      # denies (docs/explanation/architecture.md §2 "single declaration point" doctrine; §8.3
       # "the seam is enforced where it is declared"). Each row is a capability
       # a synthesized tool must never exercise; layer fields say WHERE the
       # denial bites:

data/lib/rubik/storage/store.rb

@@ -178,7 +178,8 @@ module Rubik
             next if records.empty?
 
             haystacks = haystacks_for(t, records)
-            { records: records, haystacks: haystacks,
+            folded_fields = folded_fields_for(t, records)
+            { records: records, haystacks: haystacks, folded_fields: folded_fields,
               has: tokens.map { |token| haystacks.map { |h| h.include?(token) } } }
           end
           return [] if corpus.empty?
@@ -194,14 +195,17 @@ module Rubik
                 df = dfs[ti]
                 next 0.0 if df.zero?
 
-                tf = c[:haystacks][i].scan(token).size
+                # PERF: count_occurrences using String#index avoids Array allocation of String#scan
+                tf = count_occurrences(c[:haystacks][i], token)
                 next 0.0 if tf.zero?
 
                 idf = Math.log(((total - df + 0.5) / (df + 0.5)) + 1)
                 dl = c[:haystacks][i].bytesize
                 idf * (tf * (BM25_K1 + 1)) / (tf + (BM25_K1 * (1 - BM25_B + (BM25_B * dl / avgdl))))
               end
-              [score + field_tier_bonus(tokens, c[:records][i]), c[:records][i]]
+              # PERF: pass cached folded title and tags to avoid String folding & array join allocations per score
+              f_title, f_tags = c[:folded_fields][i]
+              [score + field_tier_bonus(tokens, f_title, f_tags), c[:records][i]]
             end
           end
           ordered = scored.sort do |(score_a, rec_a), (score_b, rec_b)|
@@ -224,22 +228,44 @@ module Rubik
         end
       end
 
+      # PERF: Zero-allocation string occurrence counting via String#index loop.
+      # Replaces String#scan(token).size to avoid array allocation per matched term.
+      def count_occurrences(haystack, token)
+        return 0 if token.empty?
+
+        count = 0
+        offset = 0
+        token_len = token.length
+        while (idx = haystack.index(token, offset))
+          count += 1
+          offset = idx + token_len
+        end
+        count
+      end
+
       # Terim başına alan izi: katlanmış başlıkta geçen terim +1.0,
       # yalnız katlanmış etiketlerde geçen +0.5, gövde izi 0 — bkz.
       # TITLE_TIER_BONUS/TAGS_TIER_BONUS. Yalnız AND eşiğini geçen
       # kayıtlar için hesaplanır (ek tarama yok).
-      def field_tier_bonus(tokens, record)
-        title = Folding.fold(record["title"])
-        tags = Folding.fold(Array(record["tags"]).join("\n"))
-        tokens.sum do |token|
+      # PERF: accepts pre-folded title & tags strings or fallback record for backward compatibility.
+      def field_tier_bonus(tokens, title_or_record, tags = nil)
+        if tags.nil? && title_or_record.is_a?(Hash)
+          title = Folding.fold(title_or_record["title"])
+          tags = Folding.fold(Array(title_or_record["tags"]).join("\n"))
+        else
+          title = title_or_record.to_s
+          tags = tags.to_s
+        end
+
+        sum = 0.0
+        tokens.each do |token|
           if title.include?(token)
-            TITLE_TIER_BONUS
+            sum += TITLE_TIER_BONUS
           elsif tags.include?(token)
-            TAGS_TIER_BONUS
-          else
-            0.0
+            sum += TAGS_TIER_BONUS
           end
         end
+        sum
       end
 
       def set_ref(name, id)
@@ -430,6 +456,21 @@ module Rubik
         entry[:haystacks] ||= records.map { |r| haystack_of(r) }.freeze
       end
 
+      # PERF: Memoize folded title and tags per record in @records_cache
+      # to avoid re-folding and array joining on every search_ranked query.
+      def folded_fields_for(type, records)
+        entry = @records_cache[type]
+        unless entry
+          return records.map do |r|
+            [Folding.fold(r["title"]), Folding.fold(Array(r["tags"]).join("\n"))]
+          end
+        end
+
+        entry[:folded_fields] ||= records.map do |r|
+          [Folding.fold(r["title"]), Folding.fold(Array(r["tags"]).join("\n"))].freeze
+        end.freeze
+      end
+
       def haystack_of(record)
         Folding.fold("#{record['title']}\n#{record['body']}\n#{Array(record['tags']).join("\n")}")
       end

data/lib/rubik/tools/builtins/define_subagent.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../orchestrator/subagent/profile_contract"
+require_relative "subagent"
+
+module Rubik
+  module Tools
+    # Tool for dynamically defining a new subagent archetype at runtime (Plan 94).
+    class DefineSubagentTool < BaseTool
+      include SubagentToolHelpers
+
+      DECLARATION = Declaration.new(
+        name: "define_subagent", aliases: ["register_subagent_type", "create_subagent_type"],
+        description: "Defines a new archetype of subagent that can be invoked via invoke_subagent.",
+        risk: :execute, subagent_spawn: true, maestro_blocked: false, # self-evolution plane (TOOLS.md maestro policy)
+        params_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", maxLength: Rubik::Orchestrator::Subagent::ProfileContract::FIELD_LIMITS.fetch(:name),
+                    description: "Unique name for archetype" },
+            description: { type: "string", maxLength: Rubik::Orchestrator::Subagent::ProfileContract::FIELD_LIMITS.fetch(:description),
+                           description: "Human-readable description" },
+            system_prompt: { type: "string", maxLength: Rubik::Orchestrator::Subagent::ProfileContract::FIELD_LIMITS.fetch(:system_prompt),
+                             description: "Detailed system prompt" },
+            requires: { type: "array", maxItems: Rubik::Orchestrator::Subagent::ProfileContract::MAX_COEFFECTS,
+                        items: { type: "string", maxLength: Rubik::Orchestrator::Subagent::ProfileContract::MAX_COEFFECT_LENGTH },
+                        description: "Runtime coeffect keys required by this profile" },
+            grants: { type: "array", maxItems: Rubik::Orchestrator::Subagent::ProfileContract::MAX_GRANTS,
+                      items: { type: "string", enum: Rubik::Orchestrator::Subagent::ProfileContract::CAPABILITY_GRANTS },
+                      description: "Optional capabilities: write and subagent_spawn (default: none)" },
+            replace: { type: "boolean", description: "Explicitly allow replacing an existing dynamic archetype (default: false)" }
+          },
+          required: ["name", "description", "system_prompt"]
+        }
+      )
+
+      def initialize(supervisor: nil, runtime_context: nil)
+        super(DECLARATION)
+        @supervisor = supervisor
+        @runtime_context = runtime_context
+      end
+
+      def execute(args = {})
+        sup = resolve_supervisor(@supervisor, @runtime_context)
+        return ToolOutput.error("SubagentSupervisor is not available in runtime context.") unless sup
+
+        argument = ->(key) { args.key?(key.to_s) ? args[key.to_s] : args[key.to_sym] }
+        provided = ->(key) { args.key?(key.to_s) || args.key?(key.to_sym) }
+
+        owner_ctx = @runtime_context || (sup.respond_to?(:root_context) ? sup.root_context : nil)
+        kwargs = {
+          name: argument.call(:name), description: argument.call(:description),
+          system_prompt: argument.call(:system_prompt), replace: argument.call(:replace) || false
+        }
+        [:requires, :grants, :enable_write_tools, :enable_subagent_tools].each do |key|
+          kwargs[key] = argument.call(key) if provided.call(key)
+        end
+        kwargs[:context] = owner_ctx if owner_ctx
+
+        type_def = sup.type_registry.define_custom(**kwargs)
+        "Subagent archetype '#{type_def.name}' successfully defined and available for invoke_subagent."
+      rescue ArgumentError => e
+        ToolOutput.error(e.message)
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/storage.rb

@@ -24,9 +24,12 @@ module Rubik
       DECLARATION = Declaration.new(
         name: "storage", aliases: ["rubik_storage"],
         description: "Central rubik://storage database for goals, plans, memory, wiki, transcripts, reviews, " \
-                     "and notes. Actions: 'put' (create/update; returns id rubik://storage URI), 'get', 'list', " \
-                     "'search', 'set_ref' (alias), 'delete'. Keep agent workfiles HERE — not in the worktree. " \
-                     "Read back any entity with read_file path 'rubik://storage/<type>/<id>'.",
+                     "and notes. Actions: 'put' (create/update work artifacts — goal, plan, review, note; " \
+                     "returns id and rubik://storage URI), 'get', 'list', 'search', 'set_ref' (alias), 'delete'. " \
+                     "When `vakanuvis` is in your toolbelt, write durable `memory` via `vakanuvis(action: 'record')` " \
+                     "and compiled `wiki` via `vakanuvis(action: 'digest')`, reserving direct `put` on `memory`/`wiki` " \
+                     "for roles or sessions where `vakanuvis` is unavailable. Keep agent workfiles HERE — not in " \
+                     "the worktree. Read back any entity with read_file path 'rubik://storage/<type>/<id>'.",
         risk: :write, archetypes: [:coder], write_grant: true,
         maestro_blocked: false, # storage plane stays direct at root (TOOLS.md maestro policy)
         params_schema: {
@@ -35,12 +38,12 @@ module Rubik
             action: {
               type: "string",
               enum: ["put", "get", "list", "search", "set_ref", "delete"],
-              description: "Operation (default: 'list')."
+              description: "Operation (default: 'list'). Use 'put' for goal/plan/review/note workfiles (or fallback writes when vakanuvis is unavailable)."
             },
             type: {
               type: "string",
               enum: Rubik::Storage::Store::TYPES,
-              description: "Entity type: goal, plan, memory, wiki, transcript, review, or note."
+              description: "Entity type: goal, plan, memory, wiki, transcript, review, or note (prefer vakanuvis record/digest for memory/wiki writes when available)."
             },
             title: { type: "string", description: "Entity title (required for put)." },
             body: { type: "string", description: "Entity body (markdown text)." },

data/lib/rubik/tools/builtins/subagent.rb

@@ -101,20 +101,32 @@ module Rubik
           return ToolOutput.error("Failed to invoke subagent(s): #{e.message}")
         end
 
-        launched, queued = results.partition { |outcome, _obj| outcome == :launched }
-        lines = ["Launched #{launched.size} background subagent(s):"] +
-                launched.map do |_o, i|
-                  "  • [#{i.id}] '#{i.role}' (#{i.type_name}) - #{i.state.to_s.upcase} | transcript: #{i.transcript_ref}"
-                end
+        launched, remaining = results.partition { |outcome, _obj| outcome == :launched }
+        queued, failed = remaining.partition { |outcome, _obj| outcome == :queued }
+        lines = launched.empty? ? ["No subagents launched."] : ["Launched #{launched.size} background subagent(s):"]
+        lines.concat(launched.map do |_o, i|
+          "  • [#{i.id}] '#{i.role}' (#{i.type_name}) - #{i.state.to_s.upcase} | transcript: #{i.transcript_ref}"
+        end)
         unless queued.empty?
           rows = queued.map { |_o, s| "  • [#{s.id}] '#{s.role}' - QUEUED (waiting on: #{s.depends_on.join(', ')})" }
           lines << ("\nQueued #{queued.size} subagent(s) on unmet dependencies (no slot, no cost until released): " + rows.join("\n"))
         end
+        unless failed.empty?
+          rows = failed.map do |_outcome, spec|
+            reason = spec.respond_to?(:last_error) && spec.last_error
+            reason = "cancelled before launch" if reason.to_s.empty?
+            "  • [#{spec.id}] '#{spec.role}' - FAILED TO START (#{reason})"
+          end
+          lines << ("\n#{failed.size} subagent(s) failed to start: " + rows.join("\n"))
+        end
         all_ids = (launched + queued).map { |_o, obj| obj.id }
 
-        lines << "\nSubagents run asynchronously in the background. Conclude your turn to yield the prompt to the user, or call " \
-                 "#{Rubik::Orchestrator::Subagent::Notices.wait_hint(all_ids)} only if you strictly need results in this turn (queued ids block until the chain settles)."
-        lines.join("\n")
+        unless all_ids.empty?
+          lines << "\nSubagents run asynchronously in the background. Conclude your turn to yield the prompt to the user, or call " \
+                   "#{Rubik::Orchestrator::Subagent::Notices.wait_hint(all_ids)} only if you strictly need results in this turn (queued ids block until the chain settles)."
+        end
+        result = lines.join("\n")
+        failed.empty? ? result : ToolOutput.error(result)
       end
 
       private
@@ -315,50 +327,5 @@ module Rubik
         "Result: #{res[0, 1500]}... [truncated — full result: #{more}]"
       end
     end
-
-    # Tool for dynamically defining a new subagent archetype at runtime (Plan 94).
-    class DefineSubagentTool < BaseTool
-      include SubagentToolHelpers
-
-      DECLARATION = Declaration.new(
-        name: "define_subagent", aliases: ["register_subagent_type", "create_subagent_type"],
-        description: "Defines a new archetype of subagent that can be invoked via invoke_subagent.",
-        risk: :execute, subagent_spawn: true, maestro_blocked: false, # self-evolution plane (TOOLS.md maestro policy)
-        params_schema: {
-          type: "object",
-          properties: {
-            name: { type: "string", description: "Unique name for archetype" },
-            description: { type: "string", description: "Human-readable description" },
-            system_prompt: { type: "string", description: "Detailed system prompt" },
-            enable_write_tools: { type: "boolean", description: "Equip subagent with write tools (default: false)" },
-            enable_subagent_tools: { type: "boolean", description: "Allow subagent to spawn subagents (default: false)" }
-          },
-          required: ["name", "description", "system_prompt"]
-        }
-      )
-      def initialize(supervisor: nil, runtime_context: nil)
-        super(DECLARATION)
-        @supervisor = supervisor
-        @runtime_context = runtime_context
-      end
-
-      def execute(args = {})
-        sup = resolve_supervisor(@supervisor, @runtime_context)
-        return ToolOutput.error("SubagentSupervisor is not available in runtime context.") unless sup
-
-        name = (args["name"] || args[:name]).to_s.strip
-        desc = (args["description"] || args[:description]).to_s.strip
-        prompt = (args["system_prompt"] || args[:system_prompt]).to_s.strip
-        return ToolOutput.error("Parameters 'name', 'description', and 'system_prompt' are required.") if name.empty? || desc.empty? || prompt.empty?
-
-        type_def = sup.type_registry.define_custom(
-          name: name, description: desc, system_prompt: prompt,
-          enable_write_tools: args["enable_write_tools"] || args[:enable_write_tools] || false,
-          enable_subagent_tools: args["enable_subagent_tools"] || args[:enable_subagent_tools] || false
-        )
-
-        "Subagent archetype '#{type_def.name}' successfully defined and available for invoke_subagent."
-      end
-    end
   end
 end

data/lib/rubik/tools/builtins/synthesis.rb

@@ -176,7 +176,12 @@ module Rubik
                      description: "Storage scope: session (in-memory only), project (.rubik/tools), global (~/.rubik/tools)" },
             risk: { type: "string", enum: ["read", "write", "execute"], default: "execute",
                     description: "Risk level of tool (optional; read/write/execute, default: execute)" },
-            params_schema: { type: "object", description: "JSON Schema definition of the tool parameters" },
+            params_schema: {
+              type: "object",
+              description: "JSON Schema definition of the tool parameters (provide properties/required when the tool " \
+                           "accepts arguments; defaults to an empty object schema `{ type: 'object', properties: {} }` " \
+                           "for tools that take no arguments)"
+            },
             code: { type: "string", description: "Ruby implementation of tool handler: ->(args) { ... } or class extending Rubik::Tools::BaseTool" },
             test_args: { type: "object", description: "Optional test arguments to perform pre-flight verification in an isolated sandbox" }
           },

data/lib/rubik/tools/builtins.rb

@@ -20,6 +20,7 @@ require_relative "builtins/runtime"
 require_relative "builtins/lifecycle"
 require_relative "builtins/interactive"
 require_relative "builtins/subagent"
+require_relative "builtins/define_subagent"
 require_relative "builtins/send_message"
 require_relative "builtins/subagent_lifecycle"
 require_relative "builtins/dmesg"

data/lib/rubik/tools/diagnostic_reporter.rb

@@ -119,7 +119,8 @@ module Rubik
 
         lines << "💡 Need a specialized capability?"
         lines << "    You can dynamically create and register your own custom tool at runtime using:"
-        lines << "    `synthesize_tool(name: '#{tool_name.to_s.downcase}', description: '...', code: '->(args) { ... }')`"
+        lines << "    `synthesize_tool(name: '#{tool_name.to_s.downcase}', description: '...', " \
+                 "params_schema: { type: 'object', properties: { ... } }, code: '->(args) { ... }')`"
 
         lines.join("\n")
       end