rubik 0.1.0

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../coeffects"
+require_relative "../../uris"
+require_relative "../../storage"
+
+module Rubik
+  module Tools
+    # rubik://storage sanal FS-DB'nin yazma düzlemi (okuma düzlemi read_file
+    # URI rotalarıdır — research archetype'ı storage aracına gerek olmadan
+    # okur). maestro ve coder subagent'ları hedef/plan/bellek/wiki/transcript/
+    # inceleme/not varlıklarını buradan yazar; worktree'ye iş dosyası
+    # saçtırmadan merkezi depo tutar.
+    class StorageTool < BaseTool
+      # Registry#schemas, REQUIRES memnuniyetsizliğinde aracı gizler (storage
+      # kapalı/bağlanmamışken reklam edilmez); plain (ctx'siz) registry'ler
+      # her şeyi reklam etmeye devam eder.
+      REQUIRES = [Rubik::Coeffects::STORAGE_STORE].freeze
+
+      attr_accessor :store, :runtime_context
+
+      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>'.",
+        risk: :write, archetypes: [:coder], write_grant: true,
+        maestro_blocked: false, # storage plane stays direct at root (TOOLS.md maestro policy)
+        params_schema: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              enum: ["put", "get", "list", "search", "set_ref", "delete"],
+              description: "Operation (default: 'list')."
+            },
+            type: {
+              type: "string",
+              enum: Rubik::Storage::Store::TYPES,
+              description: "Entity type: goal, plan, memory, wiki, transcript, review, or note."
+            },
+            title: { type: "string", description: "Entity title (required for put)." },
+            body: { type: "string", description: "Entity body (markdown text)." },
+            tags: {
+              type: "array", items: { type: "string" },
+              description: "Tags (array or comma-separated string)."
+            },
+            links: {
+              type: "object", additionalProperties: { type: "string" },
+              description: "Cross-references, e.g. {\"goal\": \"goal.1.<hash16>\"}."
+            },
+            status: { type: "string", description: "Lifecycle status (default 'active')." },
+            id: { type: "string", description: "Entity id to update/get/delete: full 'plan.3.<hash16>', 'plan.3', row '3', hash prefix, or ref alias." },
+            ref: { type: "string", description: "Alias name bound to the entity (upsert semantics)." },
+            query: { type: "string", description: "Search query; every space-separated term must appear (case-insensitive over title/body/tags)." },
+            format: { type: "string", enum: ["markdown", "json"], description: "Output format (default markdown)." }
+          }
+        }
+      )
+      def initialize(store = nil, runtime_context: nil, config: nil, root_dir: Dir.pwd)
+        super(DECLARATION)
+        @store = store
+        @runtime_context = runtime_context
+        @config = config
+        @root_dir = root_dir
+      end
+
+      def execute(args = {})
+        store = resolve_store
+        unless store
+          return ToolOutput.error("Storage is not available: disabled by config (storage.enabled=false) or no store wired. " \
+                                  "Read-only rubik://storage URIs may still resolve if a store exists.")
+        end
+
+        action = (args["action"] || args[:action] || "list").to_s
+        json = (args["format"] || args[:format]).to_s == "json"
+
+        case action
+        when "put" then handle_put(store, args, json)
+        when "get" then handle_get(store, args, json)
+        when "list" then handle_list(store, args, json)
+        when "search" then handle_search(store, args, json)
+        when "set_ref" then handle_set_ref(store, args)
+        when "delete" then handle_delete(store, args)
+        else ToolOutput.error("Unknown storage action '#{action}' (valid: put, get, list, search, set_ref, delete).")
+        end
+      rescue ArgumentError => e
+        ToolOutput.error("storage #{action}: #{e.message}")
+      rescue StandardError => e
+        ToolOutput.error("storage error: #{e.class}: #{e.message}")
+      end
+
+      private
+
+      # Üçlü zincir (Tools::Services ev hükümleri): ctor enjeksiyonu →
+      # STORAGE_STORE coeffect'i (parent chain — subagent'lar buradan çözer)
+      # → config'e dayalı tembel fresh default (storage kapalıysa nil).
+      def resolve_store
+        resolved = Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::STORAGE_STORE, @store)
+        return resolved if resolved
+
+        @resolve_store ||= Rubik::Storage::Service.build(config: @config, root_dir: @root_dir)
+      end
+
+      def handle_put(store, args, json)
+        record = store.put(
+          type: arg(args, "type"), title: arg(args, "title").to_s,
+          body: arg(args, "body", ""), tags: normalize_tags(args),
+          links: arg(args, "links", {}) || {}, status: arg(args, "status", "active"),
+          id: arg(args, "id"), ref: arg(args, "ref")
+        )
+        return JSON.pretty_generate(record) if json
+
+        uri = store.uri_for(record["type"], record["id"])
+        <<~MD
+          Stored: #{record['id']} (version #{record['version']})
+          URI: #{uri}
+          Read back: read_file(path: '#{uri}')
+        MD
+      end
+
+      def handle_get(store, args, json)
+        type = arg(args, "type").to_s
+        id = arg(args, "id").to_s
+        record = store.get(type: type, id: id)
+        unless record
+          return ToolOutput.error("Entity not found: #{type}/#{id} in project '#{store.project}'. " \
+                                  "Use action 'list' to see existing ids.")
+        end
+
+        json ? JSON.pretty_generate(record) : Rubik::Storage::Render.entity(record, project: store.project)
+      end
+
+      def handle_list(store, args, json)
+        type = arg(args, "type")
+        summaries = store.list(type: type)
+        return JSON.pretty_generate(summaries.map(&:to_h)) if json
+
+        type_label = type || "all types"
+        uri_hint = "read_file #{Rubik::Uris.storage_listing(project: store.project, type: type_label)}/<id>"
+        Rubik::Storage::Render.listing(project: store.project, type: type_label, summaries: summaries.map(&:to_h),
+                                       uri_hint: uri_hint)
+      end
+
+      def handle_search(store, args, json)
+        query = arg(args, "query").to_s
+        return ToolOutput.error "storage search: 'query' is required." if query.strip.empty?
+
+        hits = store.search(query: query, type: arg(args, "type"))
+        return "No storage entities match '#{query}'." if hits.empty?
+
+        return JSON.pretty_generate(hits) if json
+
+        hits.map { |r| "#{r['id']} — #{r['title']} (#{r['status']})" }.join("\n")
+      end
+
+      def handle_set_ref(store, args)
+        result = store.set_ref(arg(args, "ref").to_s, arg(args, "id").to_s)
+        "Ref set: #{result['ref']} → #{result['id']}\nURI: #{result['uri']}"
+      end
+
+      def handle_delete(store, args)
+        type = arg(args, "type").to_s
+        home_id = home_row_id(store, type)
+        deleted = store.delete(type: type, id: arg(args, "id").to_s)
+        return ToolOutput.error("Entity not found: #{arg(args, 'type')}/#{arg(args, 'id')}") unless deleted
+
+        rebuild_home_quietly(store, type) unless home_id && deleted["id"] == home_id
+        "Deleted: #{deleted['id']} (row #{deleted['row']} is never reused)."
+      end
+
+      # Manuel wiki silmesi kronikçinin flush ritmini beklemez — wiki.home
+      # bayat girdiyle kalırdı (issue #100 P2 alan bulgusu). Silme sonrası
+      # best-effort yeniden hesap: bir hata silme sonucunu ASLA maskelemez.
+      # wiki.home'un KENDİSİNİN silmesi meşrudur — rebuild onu diriltmez
+      # (review: "silindi" diyordu, entity bir sonraki get'te geri gelirdi).
+      def home_row_id(store, type)
+        return unless type == "wiki"
+
+        store.get(type: "wiki", id: Rubik::Storage::Vakanuvis::Vocabulary::HOME_REF)&.[]("id")
+      end
+
+      def rebuild_home_quietly(store, type)
+        return unless type == "wiki"
+
+        Rubik::Storage::Vakanuvis::WikiSkeleton.rebuild_home(store)
+      rescue StandardError => e
+        Rubik::Storage::Vakanuvis.log_via(
+          nil, :warn,
+          "wiki row deleted but home rebuild failed (#{e.class}: #{e.message}) — the chronicler's next " \
+          "flush retries it when the chronicler is enabled; otherwise rewrite wiki.home manually"
+        )
+      end
+
+      def arg(args, key, default = nil)
+        args[key] || args[key.to_sym] || default
+      end
+
+      def normalize_tags(args)
+        # Anahtar-varlığıyla okunur: tags: false sessizce [] düşmesin —
+        # üst-seviye boolean/sayı RET edilir (review H1: eskiden to_s
+        # üzerinden "true"/"42" etiket olarak saklanıyordu).
+        raw = if args.key?("tags") || args.key?(:tags)
+                args["tags"] || args[:tags]
+              else
+                []
+              end
+        unless raw.is_a?(Array) || raw.is_a?(String)
+          raise ArgumentError,
+                "tags must be an array of strings or a comma-separated string — " \
+                "got #{raw.class} (#{raw.inspect})."
+        end
+
+        # Dize olarak gelen etiketler virgülle ayrılır (LLM klavye alışkanlığı).
+        # Dizi öğeleri arasındaki boolean/sayı da ret edilir (issue #100 P1) —
+        # execute'ın ArgumentError köprüsü modele temiz araç hatası döner.
+        list = raw.is_a?(Array) ? raw : raw.to_s.split(",").map(&:strip)
+        list.each do |tag|
+          next if tag.is_a?(String)
+
+          raise ArgumentError,
+                "tags must be strings — got #{tag.class} (#{tag.inspect}). " \
+                "Pass an array of strings like [\"infra\"] or a comma-separated string."
+        end
+        list
+      end
+    end
+  end
+end

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

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../base"
+require_relative "../output"
+require_relative "subagent_lifecycle"
+require_relative "../../coeffects"
+require_relative "../../orchestrator/subagent/budget"
+require_relative "../../orchestrator/subagent/notices"
+require_relative "../../orchestrator/subagent/narration"
+require_relative "../../orchestrator/subagent/conversation_id"
+
+module Rubik
+  module Tools
+    # Helper extracting SubagentSupervisor instance from constructor or runtime context.
+    module SubagentToolHelpers
+      def resolve_supervisor(supervisor, runtime_context)
+        return supervisor if supervisor
+        return nil unless runtime_context.respond_to?(:get)
+
+        Rubik::Coeffects.get(runtime_context, Rubik::Coeffects::SUBAGENT_SUPERVISOR)
+      end
+    end
+
+    # Tool for asynchronously spawning one or more isolated subagents (Plan 94).
+    class InvokeSubagentTool < BaseTool
+      include SubagentToolHelpers
+
+      # Schema truth: document the EFFECTIVE spawn default — the bound
+      # supervisor's config-derived value, the Budget invariant otherwise.
+      # The literal lives once, here; the static DECLARATION carries the
+      # invariant and construction swaps in the supervisor value only when
+      # it differs (construction-time snapshot from the kwarg only —
+      # deterministic; a runtime-context peek would depend on registration
+      # order).
+      def self.params_schema_for(steps_default)
+        {
+          type: "object",
+          properties: {
+            subagents: {
+              type: "array", description: "Array of subagents to launch concurrently",
+              items: {
+                type: "object",
+                properties: {
+                  type_name: { type: "string", description: "Archetype: 'research' (default), 'coder', 'self', or custom" },
+                  role: { type: "string", description: "2-5 word job title" },
+                  prompt: { type: "string", description: "Actionable task description" },
+                  system_prompt: { type: "string", description: "Optional custom system prompt" },
+                  workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Isolation mode" },
+                  model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier" },
+                  max_steps: { type: "integer", description: "Step budget for subagent execution (default: #{steps_default})" },
+                  depends_on: { type: "array", description: "Dispatch constraints: ['subagent-1'] = FS (launch after it completes); " \
+                                                            "{'id': 'subagent-1', 'type': 'SS'} = launch when it starts. Queued specs hold no slot until released." }
+                },
+                required: ["role", "prompt"]
+              }
+            },
+            role: { type: "string", description: "Role for single subagent invocation" },
+            prompt: { type: "string", description: "Prompt for single subagent invocation" },
+            type_name: { type: "string", description: "Archetype: 'research', 'coder', or 'self'" },
+            max_steps: { type: "integer", description: "Step budget for single subagent invocation (default: #{steps_default})" }
+          }
+        }
+      end
+
+      DECLARATION = Declaration.new(
+        name: "invoke_subagent", aliases: ["spawn_subagent", "start_subagent"],
+        description: "Invokes one or more subagents asynchronously in disposable sub-contexts.",
+        risk: :execute, subagent_spawn: true, maestro_blocked: false, # the delegation verb itself — the gate's whole point
+        params_schema: params_schema_for(Rubik::Orchestrator::Subagent::Budget::DEFAULT_MAX_STEPS)
+      )
+      def initialize(supervisor: nil, runtime_context: nil)
+        sup_default = supervisor.respond_to?(:default_max_steps) ? supervisor.default_max_steps : nil
+        if sup_default && sup_default != Rubik::Orchestrator::Subagent::Budget::DEFAULT_MAX_STEPS
+          super(DECLARATION.with(params_schema: self.class.params_schema_for(sup_default)))
+        else
+          super(DECLARATION)
+        end
+        @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
+
+        specs = extract_subagent_specs(args)
+        return ToolOutput.error("No valid subagents specified to invoke.") if specs.empty?
+
+        begin
+          results = sup.spawn_batch(specs)
+        rescue StandardError => e
+          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 { |_o, i| "  • [#{i.id}] '#{i.role}' (#{i.type_name}) - #{i.state.to_s.upcase}" }
+        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
+        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")
+      end
+
+      private
+
+      def extract_subagent_specs(args)
+        list = args["subagents"] || args[:subagents]
+        return list.map { |item| normalize_spec(symbolize_keys(item)) } if list.is_a?(Array) && !list.empty?
+
+        role = args["role"] || args[:role]
+        prompt = args["prompt"] || args[:prompt]
+        return [] unless role && prompt
+
+        [normalize_spec(
+          type_name: args["type_name"] || args[:type_name], role: role, prompt: prompt,
+          system_prompt: args["system_prompt"] || args[:system_prompt], workspace: args["workspace"] || args[:workspace] || "inherit",
+          model: args["model"] || args[:model] || "inherit", max_steps: args["max_steps"] || args[:max_steps],
+          depends_on: args["depends_on"] || args[:depends_on]
+        )]
+      end
+
+      def normalize_spec(spec)
+        spec[:type_name] = spec[:type_name].to_s.strip
+        spec[:type_name] = code_modification_prompt?(spec[:role], spec[:prompt]) ? "coder" : "research" if spec[:type_name].empty?
+        spec[:max_steps] = spec[:max_steps].to_i if spec[:max_steps] && !spec[:max_steps].to_s.empty?
+        spec
+      end
+
+      def code_modification_prompt?(role, prompt)
+        "#{role} #{prompt}".match?(/\b(fix|patch|implement|refactor|write|create|modify|edit|debug)\b/i)
+      end
+
+      def symbolize_keys(hash)
+        hash.is_a?(Hash) ? hash.transform_keys(&:to_sym) : {}
+      end
+    end
+
+    # Tool for listing, inspecting, or canceling running subagents (Plan 94).
+    class ManageSubagentsTool < BaseTool
+      include SubagentToolHelpers
+      include SubagentLifecycle
+
+      DECLARATION = Declaration.new(
+        name: "manage_subagents", aliases: ["subagents_status", "subagent_list"],
+        description: "Manage existing subagents (actions: #{Rubik::Orchestrator::Subagent::Narration.quoted_canonical_list}). " \
+                     "Subagents run in background; avoid 'wait' unless strictly blocking.",
+        risk: :read,
+        params_schema: {
+          type: "object",
+          properties: {
+            action: { type: "string", description: "Action to perform",
+                      enum: Rubik::Orchestrator::Subagent::Narration::SCHEMA_ACTIONS },
+            timeout: { type: "integer", description: "Max seconds to wait for actions 'wait' or 'status' if running " \
+                                                     "(default: #{Rubik::Orchestrator::Subagent::Notices::DEFAULT_WAIT_TIMEOUT} for wait)" },
+            conversation_ids: { type: "array", items: { type: "string" }, description: "IDs of subagents to manage/wait" },
+            conversation_id: { type: "string", description: "Single subagent ID" },
+            prompt: { type: "string", description: "New task text for action 'redeploy'" },
+            steps: { type: "integer", description: "Additional steps (extend_budget) or redeploy budget" }
+          },
+          required: ["action"]
+        }
+      )
+      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
+
+        action = (args["action"] || args[:action] || "list").to_s.downcase.strip
+        # Dispatch keys on the canonical form projected from Narration::ACTION_SPECS,
+        # so schema enum, help text, and these arms can never drift apart.
+        case Rubik::Orchestrator::Subagent::Narration.canonical_action(action)
+        when "list"
+          list_action(sup)
+        when "status"
+          id = resolve_id(args)
+          return ToolOutput.error("Missing required parameter 'conversation_id' for action 'status'.") if id.empty?
+
+          inst = sup.get(id)
+          return ToolOutput.error("Subagent '#{id}' not found.") unless inst
+
+          timeout = (args["timeout"] || args[:timeout]).to_i
+          if timeout.positive? && inst.running?
+            sup.wait_for([id], timeout: timeout)
+            inst = sup.get(id) || inst
+          end
+
+          data = inst.to_h
+          guidance = Rubik::Orchestrator::Subagent::Narration.guidance(inst.state, id: inst.id, max_steps: inst.max_steps)
+          if guidance
+            data[:guidance] = guidance
+          elsif inst.running?
+            data[:guidance] = Rubik::Orchestrator::Subagent::Narration.guidance(
+              :running, id: inst.id, max_steps: inst.max_steps, step: inst.current_step, uptime: inst.uptime
+            )
+          end
+          JSON.pretty_generate(data)
+        when "wait"
+          timeout = [(args["timeout"] || args[:timeout] || Rubik::Orchestrator::Subagent::Notices::DEFAULT_WAIT_TIMEOUT).to_i, 1].max
+          ids = resolve_ids(args) # empty = wait for ALL (wait_any_hint contract)
+          results = sup.wait_for(ids, timeout: timeout)
+          return "No active subagents to wait for.#{unknown_ids_hint(sup, ids)}" if results.empty?
+
+          lines = ["Subagents wait finished (#{results.size} tracked):"]
+          results.each do |r|
+            lines << "  • [#{r[:id]}] '#{r[:role]}' (#{r[:type]}) - #{r[:state].to_s.upcase}"
+            res = (r[:result] || r[:result_summary]).to_s.strip
+            lines << "    #{truncated_result_line(res, r)}" unless res.empty?
+            lines << "    Guidance: #{guidance}" if (guidance = Rubik::Orchestrator::Subagent::Narration.guidance(r[:state], id: r[:id], max_steps: r[:max_steps]))
+          end
+          lines.join("\n")
+        when "transcript"
+          id = resolve_id(args)
+          return ToolOutput.error("Missing required parameter 'conversation_id' for action 'transcript'.") if id.empty?
+
+          inst = sup.get(id)
+          return ToolOutput.error("Subagent '#{id}' not found.") unless inst
+          return ToolOutput.error("Subagent '#{id}' is #{inst.state} — no transcript yet.") unless inst.respond_to?(:format_transcript)
+
+          inst.format_transcript
+        when "extend_budget"
+          id = resolve_id(args)
+          return ToolOutput.error("Missing required parameter 'conversation_id' for action 'extend_budget'.") if id.empty?
+
+          steps = Rubik::Orchestrator::Subagent::Budget.normalize_grant(args["steps"] || args[:steps])
+          if sup.extend_budget(id, steps)
+            "Step budget for subagent '#{id}' successfully extended by #{steps} steps (total budget: #{sup.get(id).max_steps}, state: #{sup.get(id).state.to_s.upcase})."
+          else
+            ToolOutput.error("Subagent '#{id}' not found or cannot extend budget (current state: #{sup.get(id)&.state || 'not found'}).")
+          end
+        when "resume"
+          id = resolve_id(args)
+          if id.empty?
+            resumed = sup.resume_all
+            return resumed.empty? ? "No paused subagents to resume." : "Resumed subagent(s): #{resumed.join(', ')}."
+          end
+
+          if sup.resume(id, additional_steps: args["steps"] || args[:steps])
+            "Subagent '#{id}' successfully resumed (state: #{sup.get(id).state.to_s.upcase})."
+          else
+            ToolOutput.error("Subagent '#{id}' cannot be resumed (current state: #{sup.get(id)&.state || 'not found'}).")
+          end
+        when "redeploy"
+          redeploy_action(sup, args)
+        when "reap"
+          reap_action(sup)
+        when "kill"
+          ids = resolve_ids(args)
+          return ToolOutput.error("Missing required parameter 'conversation_ids' for action 'kill'.#{id_format_hint}") if ids.empty?
+
+          "Killed subagent(s): #{ids.filter_map { |cid| sup.kill(cid, cascade: true) ? cid : nil }.join(', ')}."
+        when "kill_all"
+          sup.kill_all && "All active subagents have been terminated."
+        else
+          ToolOutput.error("Unknown manage_subagents action: '#{action}'. Valid: #{Rubik::Orchestrator::Subagent::Narration::CANONICAL_NAMES.join(', ')}.")
+        end
+      end
+
+      ID_FORMAT_EXAMPLE = "Pass ids as a JSON array (conversation_ids: [\"subagent-5\", \"subagent-6\"]) " \
+                          "or a single id (conversation_id: 'subagent-5')."
+
+      private
+
+      def resolve_id(args)
+        resolve_ids(args).first.to_s
+      end
+
+      # Model-supplied id dialects (JSON array / array-string / comma list /
+      # quoted single id) normalize in ConversationId — the parse-side
+      # vocabulary shared with send_message.
+      def resolve_ids(args)
+        raw = args["conversation_ids"] || args[:conversation_ids] ||
+              args["conversation_id"] || args[:conversation_id] ||
+              args["id"] || args[:id]
+        Rubik::Orchestrator::Subagent::ConversationId.normalize_list(raw)
+      end
+
+      def id_format_hint
+        " #{ID_FORMAT_EXAMPLE}"
+      end
+
+      # Wait returning nothing: finished-and-reaped or nonexistent — the
+      # supervisor roster is the tiebreaker, so the model gets a correction.
+      def unknown_ids_hint(sup, ids)
+        known = (sup.respond_to?(:list) ? sup.list : []).map(&:id)
+        missing = ids - known
+        missing.empty? ? "" : " Unknown id(s): #{missing.join(', ')}.#{id_format_hint}"
+      end
+
+      # Truncation hands the model the DIRECT read path (transcript URI) —
+      # session review B10: retrieving the full report cost an extra call.
+      # Returns the line WITHOUT indentation; the caller adds the prefix.
+      def truncated_result_line(res, row)
+        return "Result: #{res}" if res.length <= 1500
+
+        uri = row[:transcript].to_s
+        more = uri.empty? ? "manage_subagents(action: 'transcript', conversation_id: '#{row[:id]}')" : "read_file(path: '#{uri}')"
+        "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/subagent_lifecycle.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../output"
+require_relative "../../orchestrator/subagent/budget"
+require_relative "../../orchestrator/subagent/notices"
+require_relative "../../orchestrator/subagent/narration"
+
+module Rubik
+  module Tools
+    # Lifecycle actions + guidance renderings for ManageSubagentsTool.
+    # Instance-method module on purpose (never a tool class): the builtin
+    # registry stays at 31 — redeploy/reap are ACTIONS of manage_subagents.
+    module SubagentLifecycle
+      # Context-preserving reuse: hand a NEW task to a finished subagent
+      # instead of re-spawning and re-explaining (maestro persona workflow).
+      def redeploy_action(sup, args)
+        id = resolve_id(args)
+        return ToolOutput.error("Missing required parameter 'conversation_id' for action 'redeploy'.") if id.empty?
+
+        prompt = (args["prompt"] || args[:prompt]).to_s.strip
+        return ToolOutput.error("Missing required parameter 'prompt' (the new task) for action 'redeploy'.") if prompt.empty?
+
+        inst = sup.redeploy(id, prompt: prompt, max_steps: args["steps"] || args[:steps])
+        "Redeployed subagent '#{id}' with a new task — context preserved (#{inst.history.size} messages), " \
+          "fresh budget: #{inst.max_steps} steps, state: #{inst.state.to_s.upcase}. It runs in the background."
+      rescue StandardError => e
+        ToolOutput.error(e.message)
+      end
+
+      # Diligent cleanup: tombstone every finished subagent NOW (in-memory
+      # history reclaimed; durable transcripts and storage index survive).
+      def reap_action(sup)
+        reaped = sup.reap_finished!(force: true)
+        return "No finished subagents to reap." if reaped.empty?
+
+        "Reaped #{reaped.size} finished subagent(s): #{reaped.join(', ')} — in-memory context reclaimed; " \
+          "transcripts remain readable via their transcript URIs and rubik://storage search."
+      end
+
+      # Blocked states that need maestro action before their chain proceeds
+      # (bug-llm-timeout-observability ④): a bare JSON list made a stalled
+      # subagent indistinguishable from a healthy one at a glance.
+      ATTENTION_STATES = [:paused_error, :waiting_budget, :budget_exhausted, :waiting_input].freeze
+
+      # List with a prominent attention block: any blocked subagent is called
+      # out ABOVE the JSON with its state, last error, and the exact recovery
+      # action, so a silent stall can't hide inside the pretty-printed rows.
+      def list_action(sup)
+        instances = sup.list
+        return "No active or tracked subagents." if instances.empty?
+
+        lines = []
+        attention = instances.select { |i| ATTENTION_STATES.include?(i.state.to_sym) }
+        if attention.any?
+          lines << "⚠ #{attention.size} subagent(s) need attention:"
+          attention.each do |i|
+            err = i.last_error.to_s
+            # Tail-preserving slice (AutoApply.capped_reason doctrine): OS and
+            # provider errors carry the actionable part at the end.
+            detail = err.empty? ? "" : " — #{err[-120, 120]}"
+            guidance = Rubik::Orchestrator::Subagent::Narration.guidance(i.state, id: i.id, max_steps: i.max_steps) ||
+                       "Run manage_subagents(action: 'status', conversation_id: '#{i.id}') for details."
+            lines << "  • [#{i.id}] '#{i.role}' — #{i.state.to_s.upcase}#{detail}: #{guidance}"
+          end
+          lines << ""
+        end
+        lines << JSON.pretty_generate(instances.map(&:to_h))
+        lines.join("\n")
+      end
+    end
+  end
+end