rubik 0.1.6 → 0.3.0

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/lifecycle.rb

@@ -3,6 +3,8 @@
 require_relative "../base"
 require_relative "../output"
 require_relative "../../runtime"
+require_relative "../../runtime/repair_probe"
+require_relative "../../buffer/apply_contract"
 
 module Rubik
   module Tools
@@ -33,7 +35,9 @@ module Rubik
       def execute(args = {})
         return ToolOutput.error("Buffer manager is not connected.") unless @buffer_manager
 
-        if @shell&.config && @shell.config.fetch("buffer.model_can_apply", true) == false
+        shell_config = @shell.respond_to?(:config) ? @shell.config : nil
+        manager_config = @buffer_manager.respond_to?(:config) ? @buffer_manager.config : nil
+        unless Rubik::Buffer::ApplyContract.model_can_apply?(shell_config: shell_config, manager_config: manager_config)
           return ToolOutput.error("Model buffer application is disabled by configuration " \
                                   "(buffer.model_can_apply: false). The human operator will review and apply changes.")
         end
@@ -43,7 +47,15 @@ module Rubik
         policy = force ? "overwrite" : nil
 
         if @buffer_manager.dirty?
-          applied = @buffer_manager.apply!(policy: policy)
+          applied = nil
+          begin
+            applied = @buffer_manager.apply!(policy: policy)
+          rescue Rubik::Buffer::ApplyFailedError => e
+            # Partial apply: files in e.applied ARE on disk — sync the model's
+            # view for them and report the remainder honestly (issue #146).
+            lines = Rubik::Buffer::ApplyContract.failure_lines(e, sync: ->(paths) { @shell&.sync_context_and_ast(paths) })
+            return ToolOutput.error(lines.join("\n"))
+          end
           conflicts = @buffer_manager.last_conflicts || []
           @shell&.sync_context_and_ast(applied) unless applied.empty?
 
@@ -68,30 +80,16 @@ module Rubik
             messages.join("\n")
           end
         else
-          clean_buffer_message
+          Rubik::Buffer::ApplyContract.clean_buffer_message(@buffer_manager.last_applied, auto_apply_mode)
         end
       end
 
       private
 
-      # "Buffer is clean" alone reads as "nothing happened" when an earlier
-      # apply (apply_buffer itself or the auto-apply policy) already flushed
-      # the edits to disk. Surface the last successful apply so the model can
-      # verify against reality instead of re-editing or force-applying
-      # (issue #97 finding 6). When the mode cannot be read, the origin stays
-      # deliberately two-sided rather than inventing a specific cause.
-      def clean_buffer_message
-        last = @buffer_manager.last_applied
-        return "No unapplied buffer changes to write (buffer is clean)." unless last.is_a?(Hash) && Array(last[:paths]).any?
-
-        mode = @shell.respond_to?(:config) && @shell.config.respond_to?(:fetch) ? @shell.config.fetch("buffer.auto_apply", "manual") : nil
-        origin = if !mode.nil? && !mode.to_s.strip.empty? && mode.to_s.downcase != "manual"
-                   "the auto-apply policy (buffer.auto_apply: #{mode})"
-                 else
-                   "an earlier apply_buffer call or the auto-apply policy"
-                 end
-        "No unapplied buffer changes to write (buffer is clean): #{last[:paths].size} file(s) were already written to disk " \
-          "at #{last[:at].utc.iso8601} by #{origin}: #{last[:paths].join(', ')}."
+      def auto_apply_mode
+        return nil unless @shell.respond_to?(:config) && @shell.config.respond_to?(:fetch)
+
+        @shell.config.fetch("buffer.auto_apply", "manual")
       end
     end
 
@@ -117,6 +115,10 @@ module Rubik
               type: "string",
               description: "Replacement or custom command string (optional, probed automatically if auto_probe: true)"
             },
+            probe_args: {
+              type: "array", items: { type: "string" },
+              description: "Explicit non-mutating functional probe arguments appended to the exact proposed command; required for unknown executables"
+            },
             auto_probe: {
               type: "boolean",
               description: "Whether to automatically probe system binaries and candidate commands (default: true)"
@@ -187,7 +189,7 @@ module Rubik
         error_diagnostic = nil
 
         begin
-          verified, error_diagnostic = verify_binary(target, lang, proposed_cmd, sub_ctx)
+          verified, error_diagnostic = verify_binary(target, lang, proposed_cmd, sub_ctx, probe_args: args["probe_args"] || args[:probe_args])
         rescue StandardError => e
           error_diagnostic = Rubik::Runtime::DiagnosticEngine.diagnose(
             cmd: proposed_cmd,
@@ -200,66 +202,114 @@ module Rubik
 
         return ToolOutput.error("Verification failed for #{target} (#{lang}):\n#{error_diagnostic&.format_for_llm}") unless verified
 
-        # 3. Live Context Promotion & Subsystem Configuration (Zero-Downtime Hot Swapping)
-        case target
-        when "lsp"
-          cfg_key = "lsp.servers.#{lang}"
-          prev_cmd = @config&.fetch(cfg_key)
-          had_client = @lsp_manager ? !@lsp_manager.client_for(lang).nil? : false
-          @config&.set(cfg_key, proposed_cmd)
-          if @lsp_manager
-            @lsp_manager.stop_client(lang)
-            start_res = @lsp_manager.start_client(lang)
-            unless start_res.is_a?(Hash) && start_res[:ok] == true
-              # Failure Reversibility (AGENTS.md §1.A): roll back the in-memory
-              # state; disk stays clean because persist happens only after a
-              # verified start (atomic promotion).
-              @lsp_manager.stop_client(lang)
-              @config&.set(cfg_key, prev_cmd)
-              @lsp_manager.start_client(lang) if had_client
-              cause = start_res.is_a?(Hash) ? start_res[:error] : "unexpected start_client response"
-              return ToolOutput.error("Failed to start LSP server for #{lang} ('#{proposed_cmd}'); " \
-                                      "previous configuration restored. Cause: #{cause}")
+        # Live changes belong to a disposable transaction. Successful project
+        # persistence is an operator decision and outlives lifecycle cleanup.
+        promotion_ctx = root_ctx.extend
+        released = false
+        @repair_scopes ||= {}
+        cfg_key = { "lsp" => "lsp.servers", "test_runner" => "test.runners",
+                    "linter" => "linter.commands" }[target]
+        cfg_key = "#{cfg_key}.#{lang}" if cfg_key
+        prev_cmd = @config&.fetch(cfg_key) if cfg_key
+        service_key = "#{{ 'test_runner' => 'runner' }.fetch(target, target)}:#{lang}"
+        previous_services = root_ctx.services
+        phase = "Promotion"
+        begin
+          promotion_ctx.on_dispose do
+            next if released
+
+            @repair_scopes.delete([root_ctx, service_key]) if @repair_scopes[[root_ctx, service_key]].equal?(promotion_ctx)
+            unless root_ctx.disposed?
+              if previous_services.key?(service_key)
+                restored = target == "lsp" ? @lsp_manager&.clients&.[](lang) : nil
+                root_ctx.provide(service_key, restored || previous_services[service_key])
+              else
+                root_ctx.unprovide(service_key)
+              end
             end
-            active_client = @lsp_manager.client_for(lang)
-            root_ctx.provide("lsp:#{lang}", active_client || proposed_cmd)
-          else
-            root_ctx.provide("lsp:#{lang}", proposed_cmd)
           end
-          # Persist to project config only after the live promotion succeeded.
-          persist_res = @config&.set(cfg_key, proposed_cmd, persist: :project)
-        when "test_runner"
-          persist_res = @config&.set("test.runners.#{lang}", proposed_cmd, persist: :project)
-          if @adapter_registry
-            adapter = @adapter_registry.get(lang)
-            if adapter
-              adapter.config ||= @config
-              adapter.custom_test_cmd = proposed_cmd
-            else
-              require_relative "../../adapter/generic" unless defined?(Rubik::Adapter::GenericAdapter)
-              new_adapter = Rubik::Adapter::GenericAdapter.new(lang, test_cmd: proposed_cmd, guard: @guard)
-              new_adapter.config = @config
-              @adapter_registry.register(lang, new_adapter, ctx: root_ctx)
+          if cfg_key && @config
+            promotion_ctx.on_dispose do
+              next if released
+
+              prev_cmd.nil? ? @config.delete(cfg_key) : @config.set(cfg_key, prev_cmd)
             end
+            @config.set(cfg_key, proposed_cmd)
           end
-          root_ctx.provide("runner:#{lang}", proposed_cmd)
-        when "linter"
-          persist_res = @config&.set("linter.commands.#{lang}", proposed_cmd, persist: :project)
-          if @adapter_registry
-            adapter = @adapter_registry.get(lang)
-            if adapter
-              adapter.config ||= @config
-              adapter.custom_format_cmd = proposed_cmd
-            else
-              require_relative "../../adapter/generic" unless defined?(Rubik::Adapter::GenericAdapter)
-              new_adapter = Rubik::Adapter::GenericAdapter.new(lang, format_cmd: proposed_cmd, guard: @guard)
-              new_adapter.config = @config
-              @adapter_registry.register(lang, new_adapter, ctx: root_ctx)
+
+          case target
+          when "lsp"
+            raise "LSP manager and config are required for live activation" unless @lsp_manager && @config
+
+            had_client = !@lsp_manager.clients[lang].nil?
+            # The manager owns its client table. Restore the old configured
+            # client on rollback; probe clients never enter that table.
+            promotion_ctx.on_dispose do
+              next if released
+
+              @lsp_manager.stop_client(lang)
+              prev_cmd.nil? ? @config.delete(cfg_key) : @config.set(cfg_key, prev_cmd)
+              if had_client && !root_ctx.disposed?
+                restored = @lsp_manager.start_client(lang)
+                raise "Previous LSP client could not be restarted: #{restored}" unless restored[:ok]
+              end
+            end
+            @lsp_manager.stop_client(lang)
+            start_res = @lsp_manager.start_client(lang)
+            raise "Failed to start LSP server: #{start_res}" unless start_res.is_a?(Hash) && start_res[:ok]
+
+            service = @lsp_manager.clients[lang]
+            raise "LSP manager reported success without an active client" unless service
+          when "test_runner", "linter"
+            if @adapter_registry
+              adapter = @adapter_registry.get(lang)
+              if adapter
+                field = target == "test_runner" ? :custom_test_cmd : :custom_format_cmd
+                old_value = adapter.public_send(field)
+                old_config = adapter.config
+                promotion_ctx.on_dispose do
+                  next if released
+
+                  adapter.public_send("#{field}=", old_value)
+                  adapter.config = old_config
+                end
+                adapter.config ||= @config
+                adapter.public_send("#{field}=", proposed_cmd)
+              else
+                require_relative "../../adapter/generic" unless defined?(Rubik::Adapter::GenericAdapter)
+                options = target == "test_runner" ? { test_cmd: proposed_cmd } : { format_cmd: proposed_cmd }
+                adapter = Rubik::Adapter::GenericAdapter.new(lang, **options, guard: @guard)
+                adapter.config = @config
+                promotion_ctx.on_dispose do
+                  @adapter_registry.unregister(lang) if !released && @adapter_registry.get(lang).equal?(adapter)
+                end
+                @adapter_registry.register(lang, adapter)
+              end
             end
+            service = proposed_cmd
+          when "command"
+            service = proposed_cmd
           end
-          root_ctx.provide("linter:#{lang}", proposed_cmd)
-        when "command"
-          root_ctx.provide("command:#{lang}", proposed_cmd)
+
+          root_ctx.provide(service_key, service)
+          phase = "Persistence"
+          persist_res = @config.set(cfg_key, proposed_cmd, persist: :project) if cfg_key && @config
+          raise persist_res[:error].to_s if persist_res.is_a?(Hash) && !persist_res[:ok]
+        rescue StandardError => e
+          promotion_ctx.dispose
+          rollback_errors = promotion_ctx.last_dispose_errors
+          detail = rollback_errors.empty? ? "previous session state restored" : "rollback incomplete: #{rollback_errors}"
+          return ToolOutput.error("#{phase} failed for #{target} (#{lang}): #{e.message}; #{detail}")
+        end
+
+        # Keep one lifetime inverse per repaired key, preserving the original
+        # baseline across repeated repairs without retaining every transaction.
+        scope_key = [root_ctx, service_key]
+        if @repair_scopes.key?(scope_key)
+          released = true
+          promotion_ctx.dispose
+        else
+          @repair_scopes[scope_key] = promotion_ctx
         end
 
         if @config.nil? && ["lsp", "test_runner", "linter"].include?(target)
@@ -267,71 +317,14 @@ module Rubik
                  "so the command is active for this session only and was not saved."
         end
 
-        if persist_res.is_a?(Hash) && !persist_res[:ok]
-          return "⚠️ Promoted '#{proposed_cmd}' for #{target} (#{lang}) — active in this session, " \
-                 "but saving to the project config failed: #{persist_res[:error]}"
-        end
-
         "✨ Successfully verified and promoted runtime service for #{target} (#{lang}): '#{proposed_cmd}'. " \
-          "Service is now active and hot-swapped in the live context with zero downtime."
+          "Service is now active in the live context."
       end
 
       private
 
-      def verify_binary(target, lang, proposed_cmd, sub_ctx)
-        case target
-        when "lsp"
-          client = Rubik::LSP::Client.new(lang, root_dir: @root_dir, server_cmd: proposed_cmd)
-          if client.available?
-            sub_ctx.provide("lsp_probe:#{lang}", client)
-            [true, nil]
-          else
-            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
-              cmd: proposed_cmd,
-              exit_code: 127,
-              stderr: "Pre-flight check failed: LSP binary '#{client.binary_name}' not available on system"
-            )]
-          end
-        when "test_runner"
-          if Rubik::Runtime::Discovery.binary_available?(proposed_cmd)
-            sub_ctx.provide("runner_probe:#{lang}", proposed_cmd)
-            [true, nil]
-          else
-            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
-              cmd: proposed_cmd,
-              exit_code: 127,
-              stderr: "Pre-flight check failed: Test runner executable not found in PATH"
-            )]
-          end
-        when "linter"
-          if Rubik::Runtime::Discovery.binary_available?(proposed_cmd)
-            sub_ctx.provide("linter_probe:#{lang}", proposed_cmd)
-            [true, nil]
-          else
-            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
-              cmd: proposed_cmd,
-              exit_code: 127,
-              stderr: "Pre-flight check failed: Linter/formatter executable not found in PATH"
-            )]
-          end
-        when "command"
-          if Rubik::Runtime::Discovery.binary_available?(proposed_cmd)
-            sub_ctx.provide("command_probe:#{lang}", proposed_cmd)
-            [true, nil]
-          else
-            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
-              cmd: proposed_cmd,
-              exit_code: 127,
-              stderr: "Pre-flight check failed: Command executable not found in PATH"
-            )]
-          end
-        else
-          [false, Rubik::Runtime::DiagnosticEngine.diagnose(
-            cmd: proposed_cmd,
-            exit_code: 1,
-            stderr: "Unknown target component type: #{target}"
-          )]
-        end
+      def verify_binary(target, lang, proposed_cmd, sub_ctx, probe_args: nil)
+        Rubik::Runtime::RepairProbe.new(root_dir: @root_dir).verify(target, lang, proposed_cmd, sub_ctx, probe_args: probe_args)
       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" }
           },