rubik 0.2.0 → 0.3.0

data/lib/rubik/prompt/context_builder.rb

@@ -11,6 +11,11 @@ require_relative "services"
 module Rubik
   module Prompt
     class ContextBuilder
+      # Root prompts show every built-in plus only the newest eight active
+      # session-defined profiles. Registry ownership and direct lookup are
+      # unaffected by this display-only bound.
+      MAX_CUSTOM_SUBAGENTS_IN_PROMPT = 8
+
       def self.find_protocol_files(root_dir = Dir.pwd)
         Rubik::Context::RepoContextReader.new(root_dir: root_dir).find_protocol_files
       end
@@ -184,16 +189,10 @@ module Rubik
         XML
       end
 
-      def self.build_subagents_xml(type_registry = nil)
+      def self.build_subagents_xml(type_registry = nil, active_tools: nil)
         return "" if type_registry.nil?
 
-        types = if type_registry.respond_to?(:list)
-                  type_registry.list
-                elsif type_registry.is_a?(Array)
-                  type_registry
-                else
-                  []
-                end
+        types = prompt_visible_subagent_types(type_registry)
         return "" if types.empty?
 
         esc = Rubik::Platform.method(:xml_escape)
@@ -211,7 +210,7 @@ module Rubik
           "  <subagent name=\"#{name}\" tools=\"#{tools_mode}\" default_workspace=\"#{workspace}\">#{desc}</subagent>"
         end.join("\n")
 
-        guidance = Doctrine.orchestration_guidance_bullets.map { |bullet| "    • #{bullet}" }.join("\n")
+        guidance = Doctrine.orchestration_guidance_bullets(active_tools: active_tools).map { |bullet| "    • #{bullet}" }.join("\n")
 
         <<~XML.strip
           <subagents count="#{types.size}">
@@ -224,6 +223,26 @@ module Rubik
         XML
       end
 
+      def self.prompt_visible_subagent_types(type_registry)
+        available = if type_registry.respond_to?(:builtins) && type_registry.respond_to?(:dynamics)
+                      type_registry.builtins + type_registry.dynamics
+                    elsif type_registry.respond_to?(:list)
+                      type_registry.list
+                    elsif type_registry.is_a?(Array)
+                      type_registry
+                    else
+                      []
+                    end
+        builtins, custom = available.partition { |type| !type.respond_to?(:custom_prompt) || !type.custom_prompt }
+        newest_custom = custom.sort_by do |type|
+          revision = type.respond_to?(:revision) ? type.revision : nil
+          [revision.respond_to?(:to_i) ? revision.to_i : -1, type.name.to_s]
+        end.last(MAX_CUSTOM_SUBAGENTS_IN_PROMPT)
+
+        builtins + newest_custom
+      end
+      private_class_method :prompt_visible_subagent_types
+
       def self.build_lsp_xml(lsp_manager = nil)
         return "" unless lsp_manager&.enabled?
 
@@ -272,11 +291,12 @@ module Rubik
       # at the composition boundary (Shell integration happens once, in
       # Services.from_shell — see orchestrator/loop.rb). Defaults live in
       # Prompt::Services; unsatisfied slots degrade to omitted sections.
-      def self.build_system_context(services:)
+      def self.build_system_context(services:, active_tools: nil, mode: :default)
         svc = services
+        plan_mode = mode&.to_sym == :plan
         sections = []
 
-        rules_xml = Doctrine.operational_rules_xml
+        rules_xml = Doctrine.operational_rules_xml(active_tools: active_tools, mode: mode)
         sections << rules_xml unless rules_xml.empty?
 
         # Machine-readable shell facts (Plan 55 D-6), generated from the same
@@ -299,14 +319,20 @@ module Rubik
         sections << "<context_budget limit=\"#{svc.context_limit.to_i}\" unit=\"tokens\" />" if svc.context_limit&.to_i&.positive?
         sections << "<output_budget limit=\"#{svc.max_output_tokens.to_i}\" unit=\"tokens\" />" if svc.max_output_tokens&.to_i&.positive?
 
-        commands_xml = build_commands_xml(svc.commands)
-        sections << commands_xml unless commands_xml.empty?
+        unless plan_mode
+          commands_xml = build_commands_xml(svc.commands)
+          sections << commands_xml unless commands_xml.empty?
 
-        skills_xml = build_skills_xml(svc.skills_index)
-        sections << skills_xml unless skills_xml.empty?
+          if Doctrine.tool_active?("skill", active_tools)
+            skills_xml = build_skills_xml(svc.skills_index)
+            sections << skills_xml unless skills_xml.empty?
+          end
 
-        subagents_xml = build_subagents_xml(svc.type_registry)
-        sections << subagents_xml unless subagents_xml.empty?
+          if Doctrine.tool_active?("invoke_subagent", active_tools)
+            subagents_xml = build_subagents_xml(svc.type_registry, active_tools: active_tools)
+            sections << subagents_xml unless subagents_xml.empty?
+          end
+        end
 
         sections << "<extra_context>\n#{Rubik::Platform.xml_escape(svc.extra_context.to_s.strip)}\n</extra_context>" unless svc.extra_context.to_s.strip.empty?
 
@@ -322,14 +348,15 @@ module Rubik
       # carries only a compact name listing (the full JSON dump would double
       # the token cost every step); the JSON-block convention is documented
       # as a fallback only.
-      def self.build_system_prompt(services:, mode: :default, tool_schemas: [], native_tools: false)
+      def self.build_system_prompt(services:, mode: :default, tool_schemas: nil, native_tools: false)
         # Plan mode is text-only: never publish the toolbelt, regardless of
         # what callers pass. Execution-side gating lives in Orchestrator::Loop.
         tool_schemas = [] if mode.to_sym == :plan
+        active_tools = extract_active_tool_names(tool_schemas, mode: mode)
 
-        xml_context = build_system_context(services: services)
+        xml_context = build_system_context(services: services, active_tools: active_tools, mode: mode)
 
-        role_header = Doctrine.role_header(mode, goal_ledger: ledger_enabled?(services))
+        role_header = Doctrine.role_header(mode, goal_ledger: ledger_enabled?(services), active_tools: active_tools)
 
         tool_section = if tool_schemas.nil? || tool_schemas.empty?
                          ""
@@ -348,6 +375,13 @@ module Rubik
         PROMPT
       end
 
+      def self.extract_active_tool_names(tool_schemas, mode: :default)
+        return [] if mode&.to_sym == :plan
+        return nil if tool_schemas.nil? || tool_schemas.empty?
+
+        tool_schemas.filter_map { |t| (t[:name] || t["name"])&.to_s }
+      end
+
       def self.format_user_task(prompt)
         <<~XML.strip
           <user_task>

data/lib/rubik/prompt/doctrine.rb

@@ -21,22 +21,23 @@ module Rubik
     module Doctrine
       module_function
 
-      def operational_rules_xml
+      def operational_rules_xml(active_tools: nil, mode: :default)
         # Maestro doktrini (kullanıcı kararı 2026-10-01): maestro HER modda
         # orkestratör. Devir caveat'i kural 2-3'ün BAŞINA yazılır — sondaki
         # ek caveat zayıf modellerde atlanıyordu (opencode-personal bulgusu);
         # doktrin kendi promptunun içinde çelişmemeli.
+        plan_mode = mode&.to_sym == :plan
         <<~XML.strip
           <operational_rules>
-            1. Code Exploration & Review (read-only: shape subagent assignments and answer the user): Use native tools directly (`list_files`, `grep_search`, `search_symbols`, `get_outline`, `read_file`, `find_references`). If neither a tool nor a listed command matches your need, inspect the codebase structurally: examine the directory layout (`list_files`), search for patterns (`grep_search`), read core modules (`get_outline`, `read_file`), and look for TODO/FIXME markers. For conceptual queries (e.g. "code review", "code quality"), do NOT search for the literal words "refactor" or "review"; evaluate the architecture structurally.
+            #{rule_one_exploration(plan_mode: plan_mode)}
             2. Code Editing & Targeted Changes: MAESTRO OVERRIDE — this rule is delegated wholesale: route ALL edits through 'coder' subagents and never stage edits in your own context (the runtime refuses direct edit tools). The mechanics below are what your coder subagents use. #{Rubik::Prompt::ToolTeachings.teaching_for('replace_file_content')} #{Rubik::Prompt::ToolTeachings.teaching_for('write_file')} #{Rubik::Prompt::ToolTeachings.teaching_for('apply_buffer')}
             3. Testing & Execution: MAESTRO OVERRIDE — this rule is delegated wholesale: subagents run tests and commands; you read their reports and never execute them yourself (the runtime refuses direct run tools). The mechanics below are what your coder subagents use: they invoke `run_tests` and `run_command` as native tools, never wrapped in `exec_repl_command`. Commands in `run_command` run directly in the project working directory (`<working_directory>`); coder subagents must not prepend `cd` commands or guess non-existent paths (e.g. `/home/ubuntu`). Always fulfill the user's primary requested action (e.g. merge, build, test, commit) to completion. #{Rubik::Prompt::ToolTeachings.teaching_for('run_command')}
             4. REPL Bang Commands: `exec_repl_command` runs only the session-safe commands listed in <agent_commands> — runtime configuration, context and step-budget self-management, buffer review and rollback, runtime introspection, and code validation. If that section is absent, do not invoke REPL commands. File, code, test, and shell operations never travel through REPL commands — under the maestro doctrine (rules 2-3) they are delegated to subagents, and the direct tools (`read_file`, `write_file`, `replace_file_content`, `run_tests`, `run_command`) are your coder subagents' mechanics. Buffer-review commands (`!diff`, `!undo`, `!rollback`) operate on the in-memory staging buffer (unapplied edits) — they are a preview layer, not file ground truth: verify file content with `read_file`, and read git history from your coder subagent's `run_command` report.
-            5. Autonomous Tool Synthesis: #{Rubik::Prompt::ToolTeachings.teaching_for('synthesize_tool')}
+            5. Autonomous Tool Synthesis: #{rule_five_synthesis(plan_mode: plan_mode)}
             6. Output Budget & Conciseness: Respect your output token budget (`<output_budget>`). Produce direct, high-signal responses and avoid unnecessary pleasantries, verbose conversational preambles, or duplicated context blocks that waste generation quota.
-            7. Subagent Delegation & Parallelism (Maestro): As the maestro you orchestrate — ALL execution work (exploration, code changes, verification) is delegated via `invoke_subagent`, in every mode. Match task to archetype: use 'research' for read-only codebase exploration; MUST use 'coder' for code modifications, refactoring, and test execution ('research' has no write or test tools); reach for 'self' (a full capability clone, minus subagent spawning) for work that fits neither archetype — runtime introspection/repair, self-evolution work, hybrid tasks. Subagents execute asynchronously in disposable sub-contexts in the background. For non-trivial modifications, allocate sufficient step budget (e.g. `max_steps: 100-140`) to prevent avoidable mid-flight pauses. When chaining stages with `depends_on`, hand the successor the predecessor's canonical transcript reference (`read_file('rubik://subagent/<storage-id>/transcript')`, reported by status/completion notices) — never a handwritten storage path; if the successor launches before the storage id is known, paste the predecessor's findings into its brief. Consume subagents' structured reports (Outcome, Changes/Locations, Verification/Findings, Assumptions) directly. After dispatching subagents, do NOT block with 'wait' unless you strictly depend on their output in the current turn — conclude your turn and liberate the prompt so the user can interact concurrently. Completion, budget-pause, error, and message notifications arrive reactively: during your turn via your notification inbox; while you are idle, the runtime automatically wakes you with a dedicated notification-evaluation turn — evaluate the pending notifications, act (extend budget, steer with send_message, retrieve results, wrap up, or report to the user), and conclude your turn again. Subagents can ask YOU questions mid-flight via `ask_question` — a question notification means that subagent is BLOCKED until you reply: answer it promptly with `send_message(recipient: '<id>', message: '<your answer>')` (it times out otherwise). Call `#{Rubik::Orchestrator::Subagent::Notices.wait_hint_template}` only when synchronous waiting is strictly required. Never poll 'status' repeatedly in a loop.
-            8. Runtime Introspection, Self-Healing & Human Feedback: If internal errors or service degradation occur, inspect runtime state with `inspect_runtime` and repair failed services via `repair_runtime_service`. When critical requirements are underspecified or high-impact architectural choices require user confirmation, use `ask_question` with structured multiple-choice options.
-            9. Central Storage & Clean Worktree: #{Rubik::Prompt::ToolTeachings.teaching_for('storage')} #{Rubik::Prompt::ToolTeachings.teaching_for('vakanuvis')} #{Rubik::Prompt::ToolTeachings.teaching_for('show_file')} Subagent transcripts are indexed automatically as `transcript` entities (alias `subagent-<storage-id>`) and are readable live or persisted via the canonical `rubik://subagent/<storage-id>/transcript` reference — indexed entities and live history have different availability, so address the exact execution by its unique storage id (from status/completion notices), never by a display id or a disk path. #{Rubik::Prompt::ToolTeachings.teaching_for('prune_context')}
+            #{rule_seven_delegation(plan_mode: plan_mode)}
+            #{rule_eight_introspection(plan_mode: plan_mode)}
+            9. Central Storage & Clean Worktree: #{rule_nine_body(active_tools: active_tools, plan_mode: plan_mode)}
           </operational_rules>
         XML
       end
@@ -47,34 +48,35 @@ module Rubik
       # koşulludur (goal-ledger planı A) — OFF'ta bayt-özdeş; öğreti
       # TEACHINGS'e giremez (weld testi her öğretiyi operational_rules
       # içinde zorunlu kılar), goal header'ın 6. maddesinde yaşar.
-      def role_header(mode, goal_ledger: false)
+      def role_header(mode, goal_ledger: false, active_tools: nil)
         case mode.to_sym
         when :plan
           <<~HDR
             You are Rubik (maestro), the orchestrator in PLAN-ONLY mode: you analyze, plan, and orchestrate; execution belongs to subagents.
             Analyze the user's task within <user_task> and output a concise, numbered step-by-step implementation plan.
-            Do NOT call apply_buffer, write_file, replace_file_content, run_tests, or run_command — the maestro runtime refuses them in every mode; analysis and planning are your work. Proposed changes may sit in the buffer — do not apply them. Specify what files will be created or edited.
+            No tools are exposed in PLAN-ONLY mode — do NOT emit tool calls or JSON tool blocks. Do NOT call apply_buffer, write_file, replace_file_content, run_tests, or run_command — the maestro runtime refuses them in every mode; analysis and planning are your work. Proposed changes may sit in the buffer — do not apply them. Specify what files will be created or edited.
           HDR
         when :goal
+          ledger_active = goal_ledger && tool_active?("update_goal_ledger", active_tools)
           ledger_line = " If a `<goal_ledger>` row is present, keep its state current: read `rubik://goal/ledger` and " \
                         "apply JSON patches with `update_goal_ledger(patch: ...)` against the reported rev after each " \
                         "meaningful step (task status changes, new findings/decisions)."
           <<~HDR
             You are Rubik (maestro), an autonomous AI coding SUPERVISOR in AUTONOMOUS GOAL mode.
-            You own the goal in <user_task> and MUST drive it to verified completion as a pure orchestrator — you conduct, subagents perform. All research, code changes, and verification run in subagent contexts, never in yours:
+            You own the goal in <user_task> and MUST drive it to verified completion as a pure orchestrator — you conduct, subagents perform. You may perform lightweight read-only inspection (`list_files`, `grep_search`, `read_file`) to orient and shape assignments, while all broader research, code changes, and verification run in subagent contexts, never in yours:
             1. Decompose the goal into staged subagent work: at minimum a plan/research stage, a build stage, a review/audit stage whose findings feed a fix stage, and a final verification stage. You decide the exact stages. Declare cross-stage ordering IN THE SAME dispatch with `depends_on` (FS default: the successor launches automatically once the predecessor completes; SS: once it starts) — never fire a stage in parallel with its own predecessors.
             2. Dispatch every stage with `invoke_subagent`. You MAY explore read-only yourself (`list_files`, `grep_search`, `read_file`) to shape assignments, but ALL code changes and test runs belong to subagents — MUST use the 'coder' archetype for any file modification ('research' is read-only).
             3. Keep YOUR context lean and managerial: no code drafts, no test output, no full-file reads in your own context — consume stage reports, `rubik://storage/...` summaries, and notification digests instead. Answer subagent `ask_question` prompts promptly.
             4. Work the notifications, never a poll loop: when subagents are dispatched and nothing needs your immediate action, end your turn WITHOUT calling finish — the runtime waits for them and wakes you with their completion/pause/error/question notices. Ending your turn (or calling finish) with subagents still active does NOT complete the goal: the runtime holds the goal open and re-prompts you with their notices. React to each notice (extend a budget-paused subagent (`manage_subagents` action: 'extend_budget') instead of absorbing its task yourself), then yield again. Conclude with finish ONLY when every dispatched subagent has settled and verification is green.
             5. Close every stage through verification: read subagent reports, integrate verified results, and run final verification as a subagent stage — a 'coder' mandated to `run_tests` whose green/red report you read. Iterate the review→fix stages until the verifier reports green.
-            6. Live goal snapshot (status, step budget, extensions): read it with `read_file(path: 'rubik://goal/state')`.#{ledger_line if goal_ledger}
-            7. Persist pipeline knowledge in the central storage (`storage` tool): the decomposed plan, review findings, and the final goal record — link stages with entity ids (`links: {"goal": "goal.N.<hash16>"}`) so the audit trail survives the session. Per-stage MEMORY notes go through the chronicler instead: `vakanuvis(action: 'record', topic: '...', body: '...')` mints the `mem.` ref, upserts and supersedes — never write memory with raw storage puts; re-enter prior context with `vakanuvis(action: 'recall', query: '...')` (also after compaction). Keep the repository worktree free of agent workfiles. Transcripts of finished subagents are indexed automatically (searchable via `storage` action 'search') and persist after the subagent is reaped.
+            6. Live goal snapshot (status, step budget, extensions): read it with `read_file(path: 'rubik://goal/state')`.#{ledger_line if ledger_active}
+            7. #{goal_storage_rule(active_tools)}
             8. Call `finish` only when the goal is verified, complete, and no dispatched subagent remains active — a premature finish is converted into a wait and you will be re-prompted with their notices. Summarize what each stage produced.
           HDR
         else
           <<~HDR
             You are Rubik (maestro), a maestro coding orchestrator for the human operator.
-            You ALWAYS work through subagents: research, code changes, and verification run in subagent contexts via `invoke_subagent` (MUST use the 'coder' archetype for any file modification — 'research' is read-only), never in your own context.
+            You ALWAYS work through subagents for execution: while you MAY explore read-only (`list_files`, `grep_search`, `read_file`) for quick orientation, broader codebase research, all code changes, and all verification run in subagent contexts via `invoke_subagent` (MUST use the 'coder' archetype for any file modification — 'research' is read-only), never in your own context.
             Keep your own context lean and managerial: you MAY explore read-only (`list_files`, `grep_search`, `read_file`) to understand requests and shape assignments, but no code drafts, no test runs, no full-file dumps — consume subagent reports and `rubik://storage/...` summaries instead.
             Focus on driving tasks to completion: decompose the user's request into subagent tasks, work the reactive notices (completion, budget pause, error, question), steer with `send_message` / `manage_subagents` ('extend_budget', 'redeploy'), and answer subagent `ask_question` prompts promptly — they block until you reply.
             Prefer reuse over re-spawning: hand follow-up tasks to a finished subagent with `manage_subagents(action: 'redeploy', conversation_id: '<id>', prompt: '<new task>')` — its accumulated context survives.
@@ -86,8 +88,8 @@ module Rubik
       # Guidance BULLET PROSE (no wrapper tags, no indent): the renderer
       # owns the <orchestration_guidance> XML structure and indentation,
       # Doctrine owns the policy sentences.
-      def orchestration_guidance_bullets
-        [
+      def orchestration_guidance_bullets(active_tools: nil)
+        bullets = [
           "Archetype selection: Use 'research' for read-only exploration; MUST use 'coder' for code changes/bug fixes " \
           "(read-only agents cannot modify files, run tests, or run shell commands — git/gh plumbing and command " \
           "output belong to a coder, plan that pass from the start).",
@@ -119,15 +121,149 @@ module Rubik
           "keeps them queued — extend or resume it instead. When chaining dependent stages, direct the successor " \
           "to read predecessor findings via the canonical transcript reference " \
           "(`read_file('rubik://subagent/<storage-id>/transcript')`, from status/completion notices) — never a " \
-          "handwritten storage path; the findings can also be pasted into the brief.",
-          "Chronicler briefs: when dispatching a subagent, paste the relevant chronicled knowledge into the task " \
-          "brief — the recall digest or a rubik://storage/... link — so the subagent pulls the depth itself. " \
-          "Subagents never see the `vakanuvis` tool; you are the only librarian.",
-          "Diligent cleanup: Finished subagents are reaped automatically after a grace period " \
-          "(`subagents.reap_finished_after`) — in-memory context is reclaimed while the durable transcript stays " \
-          "readable at its transcript URI and in `rubik://storage` search. `manage_subagents(action: 'reap')` " \
-          "reaps finished subagents immediately."
+          "handwritten storage path; the findings can also be pasted into the brief."
         ]
+        if tool_active?("vakanuvis", active_tools)
+          bullets << "Chronicler briefs: when dispatching a subagent, paste the relevant chronicled knowledge into the task " \
+                     "brief — the recall digest or a rubik://storage/... link — so the subagent pulls the depth itself. " \
+                     "Subagents never see the `vakanuvis` tool; you are the only librarian."
+        end
+        bullets << "Diligent cleanup: Finished subagents are reaped automatically after a grace period " \
+                   "(`subagents.reap_finished_after`) — in-memory context is reclaimed while the durable transcript stays " \
+                   "readable at its transcript URI and in `rubik://storage` search. `manage_subagents(action: 'reap')` " \
+                   "reaps finished subagents immediately."
+        bullets
+      end
+
+      def tool_active?(tool_name, active_tools)
+        return true if active_tools.nil?
+
+        active_tools.include?(tool_name.to_s)
+      end
+
+      def rule_one_exploration(plan_mode:)
+        if plan_mode
+          "1. Code Exploration & Review (PLAN-ONLY — no tool calls): Inspect the `<workspace_status>`, `<protocol>`, " \
+            "`<buffer_status>`, `<lsp_diagnostics>`, and `<extra_context>` sections already provided in `<system_context>` " \
+            "to understand the repository layout, active branch, dirty buffer files, and diagnostics without invoking tools. " \
+            "For conceptual queries (e.g. \"code review\", \"code quality\"), evaluate the architecture structurally rather " \
+            "than assuming literal keyword matches."
+        else
+          "1. Code Exploration & Review (read-only: shape subagent assignments and answer the user): Use native tools " \
+            "directly (`list_files`, `grep_search`, `search_symbols`, `get_outline`, `read_file`, `find_references`) when " \
+            "available in your toolbelt for lightweight orientation, or delegate broader exploration to a 'research' subagent. " \
+            "If neither a tool nor a listed command matches your need, inspect the codebase structurally: examine the " \
+            "directory layout (`list_files`), search for patterns (`grep_search`), read core modules (`get_outline`, " \
+            "`read_file`), and look for TODO/FIXME markers. For conceptual queries (e.g. \"code review\", \"code quality\"), " \
+            "do NOT search for the literal words \"refactor\" or \"review\"; evaluate the architecture structurally."
+        end
+      end
+
+      def rule_five_synthesis(plan_mode:)
+        if plan_mode
+          "In PLAN-ONLY mode, do not synthesize tools; if a custom runtime tool would help during execution, note it " \
+            "as a proposed step in your plan."
+        else
+          Rubik::Prompt::ToolTeachings.teaching_for("synthesize_tool")
+        end
+      end
+
+      def rule_seven_delegation(plan_mode:)
+        if plan_mode
+          "7. Subagent Delegation & Parallelism (Maestro — PLAN-ONLY): In PLAN-ONLY mode no tools are exposed, so you " \
+            "do NOT invoke `invoke_subagent` or any other tools during this turn; instead, design the plan around the " \
+            "maestro execution model (where 'research' handles read-only codebase exploration, 'coder' handles all file " \
+            "modifications, refactoring, and test/command execution, and 'self' handles runtime introspection or hybrid " \
+            "tasks) so the resulting steps can be executed cleanly once approved."
+        else
+          "7. Subagent Delegation & Parallelism (Maestro): As the maestro you orchestrate — while you may use read-only " \
+            "tools directly for quick orientation (rule 1), broader codebase exploration, code changes, and verification — " \
+            "all execution work — is delegated via `invoke_subagent`, in every mode. Match task to archetype: use 'research' " \
+            "for read-only codebase exploration; MUST use 'coder' for code modifications, refactoring, and test execution " \
+            "('research' has no write or test tools); reach for 'self' (a full capability clone, minus subagent spawning) " \
+            "for work that fits neither archetype — runtime introspection/repair, self-evolution work, hybrid tasks. " \
+            "Subagents execute asynchronously in disposable sub-contexts in the background. For non-trivial modifications, " \
+            "allocate sufficient step budget (e.g. `max_steps: 100-140`) to prevent avoidable mid-flight pauses. When " \
+            "chaining stages with `depends_on`, hand the successor the predecessor's canonical transcript reference " \
+            "(`read_file('rubik://subagent/<storage-id>/transcript')`, reported by status/completion notices) — never a " \
+            "handwritten storage path; if the successor launches before the storage id is known, paste the predecessor's " \
+            "findings into its brief. Consume subagents' structured reports (Outcome, Changes/Locations, " \
+            "Verification/Findings, Assumptions) directly. After dispatching subagents, do NOT block with 'wait' unless " \
+            "you strictly depend on their output in the current turn — conclude your turn and liberate the prompt so the " \
+            "user can interact concurrently. Completion, budget-pause, error, and message notifications arrive reactively: " \
+            "during your turn via your notification inbox; while you are idle, the runtime automatically wakes you with a " \
+            "dedicated notification-evaluation turn — evaluate the pending notifications, act (extend budget, steer with " \
+            "send_message, retrieve results, wrap up, or report to the user), and conclude your turn again. Subagents can " \
+            "ask YOU questions mid-flight via `ask_question` — a question notification means that subagent is BLOCKED until " \
+            "you reply: answer it promptly with `send_message(recipient: '<id>', message: '<your answer>')` (it times out " \
+            "otherwise). Call `#{Rubik::Orchestrator::Subagent::Notices.wait_hint_template}` only when synchronous waiting " \
+            "is strictly required. Never poll 'status' repeatedly in a loop."
+        end
+      end
+
+      def rule_eight_introspection(plan_mode:)
+        if plan_mode
+          "8. Runtime Introspection, Self-Healing & Human Feedback: In PLAN-ONLY mode, note any missing context, " \
+            "architectural trade-offs, or open questions directly in your plan output instead of invoking runtime or " \
+            "question tools."
+        else
+          "8. Runtime Introspection, Self-Healing & Human Feedback: If internal errors or service degradation occur, " \
+            "inspect runtime state with `inspect_runtime` and repair failed services via `repair_runtime_service`. When " \
+            "critical requirements are underspecified or high-impact architectural choices require user confirmation, use " \
+            "`ask_question` with structured multiple-choice options."
+        end
+      end
+
+      def rule_nine_body(active_tools: nil, plan_mode: false)
+        return "Keep the repository worktree free of agent workfiles, scratch notes, and temporary artifacts." if plan_mode
+
+        storage_part = if tool_active?("storage", active_tools)
+                         Rubik::Prompt::ToolTeachings.teaching_for("storage")
+                       else
+                         "Keep the repository worktree free of scattered agent workfiles; read any existing " \
+                           "`rubik://storage/<type>/<id>` entities via `read_file` when a store is wired."
+                       end
+        parts = [storage_part]
+        parts << Rubik::Prompt::ToolTeachings.teaching_for("vakanuvis") if tool_active?("vakanuvis", active_tools)
+        parts << Rubik::Prompt::ToolTeachings.teaching_for("show_file") if tool_active?("show_file", active_tools)
+        parts << "Subagent transcripts are indexed automatically as `transcript` entities (alias `subagent-<storage-id>`) " \
+                 "and are readable live or persisted via the canonical `rubik://subagent/<storage-id>/transcript` reference — " \
+                 "indexed entities and live history have different availability, so address the exact execution by its unique " \
+                 "storage id (from status/completion notices), never by a display id or a disk path."
+        parts << Rubik::Prompt::ToolTeachings.teaching_for("prune_context") if tool_active?("prune_context", active_tools)
+        parts.join(" ")
+      end
+
+      def goal_storage_rule(active_tools)
+        storage_on = tool_active?("storage", active_tools)
+        vakanuvis_on = tool_active?("vakanuvis", active_tools)
+        if storage_on && vakanuvis_on
+          "Persist pipeline knowledge in the central storage (`storage` tool): the decomposed plan, review findings, " \
+            "and the final goal record — link stages with entity ids (`links: {\"goal\": \"goal.N.<hash16>\"}`) so the " \
+            "audit trail survives the session. Per-stage MEMORY notes go through the chronicler instead: " \
+            "`vakanuvis(action: 'record', topic: '...', body: '...')` mints the `mem.` ref, upserts and supersedes — " \
+            "never write memory with raw storage puts when `vakanuvis` is available " \
+            "(fall back to `storage` `put` only when `vakanuvis` is unavailable); re-enter prior context with " \
+            "`vakanuvis(action: 'recall', query: '...')` (also after compaction). Keep the repository worktree free of " \
+            "agent workfiles. Transcripts of finished " \
+            "subagents are indexed automatically (searchable via `storage` action 'search') and persist after the " \
+            "subagent is reaped."
+        elsif storage_on
+          "Persist pipeline knowledge in the central storage (`storage` tool): the decomposed plan, review findings, " \
+            "and the final goal record — link stages with entity ids (`links: {\"goal\": \"goal.N.<hash16>\"}`) so the " \
+            "audit trail survives the session. Keep the repository worktree free of agent workfiles. Transcripts of " \
+            "finished subagents are indexed automatically (searchable via `storage` action 'search') and persist after " \
+            "the subagent is reaped."
+        elsif vakanuvis_on
+          "Persist durable per-stage MEMORY notes through the chronicler: `vakanuvis(action: 'record', topic: '...', " \
+            "body: '...')` mints the `mem.` ref, upserts and supersedes; re-enter prior context with " \
+            "`vakanuvis(action: 'recall', query: '...')` (also after compaction). Keep the repository worktree free of " \
+            "agent workfiles. Transcripts of finished subagents remain readable via `rubik://subagent/<storage-id>/transcript` " \
+            "after the subagent is reaped."
+        else
+          "Keep the repository worktree free of agent workfiles. Transcripts of finished subagents remain readable via " \
+            "`rubik://subagent/<storage-id>/transcript` after the subagent is reaped."
+        end
       end
 
       def skills_preamble

data/lib/rubik/prompt/token_estimator.rb

@@ -11,13 +11,15 @@ module Rubik
 
       module_function
 
+      # PERF: Integer math (len * 10 + 37) / 38 avoids Float allocation and division,
+      # bit-for-bit identical to (len / 3.8).ceil; direct length avoids .to_s on Strings.
       def estimate_text(text)
         return 0 if text.nil?
 
-        str = text.to_s
-        return 0 if str.empty?
+        len = text.is_a?(String) ? text.length : text.to_s.length
+        return 0 if len.zero?
 
-        (str.length / CHARS_PER_TOKEN).ceil
+        ((len * 10) + 37) / 38
       end
 
       def estimate_message(msg)

data/lib/rubik/prompt/tool_teachings.rb

@@ -19,8 +19,8 @@ module Rubik
     module ToolTeachings
       TEACHINGS = {
         "replace_file_content" =>
-          "For modifying existing files, prefer `replace_file_content` with exact verbatim `target_content` " \
-          "(or `old_content`) and `replacement_content` (or `new_content`).",
+          "For modifying existing files, prefer `replace_file_content` with `path`, exact verbatim `target_content`, " \
+          "and `replacement_content` (plus optional `start_line`, `end_line`, and `allow_multiple`).",
         "write_file" =>
           "For creating new files or completely rewriting files, use `write_file`.",
         "apply_buffer" =>
@@ -31,12 +31,19 @@ module Rubik
         "synthesize_tool" =>
           "When you need a specialized capability not available in the built-in toolbelt (such as custom AST " \
           "transformers, data converters, or domain-specific benchmarkers), dynamically create and register your " \
-          "own tool at runtime using `synthesize_tool(name: '...', description: '...', code: '->(args) { ... }')`.",
+          "own tool at runtime using `synthesize_tool(name: '...', description: '...', " \
+          "params_schema: { type: 'object', properties: { ... }, required: [...] }, code: '->(args) { ... }')` " \
+          "(always provide `params_schema` when the handler reads arguments from `args`; omit it or pass an empty " \
+          "`{ type: 'object', properties: {} }` schema only for tools that take no arguments).",
         "storage" =>
-          "Persist agent workfiles — goals, plans, memory notes, wiki knowledge, reviews — in the central " \
+          "Persist agent workfiles — goals, plans, reviews, and work notes — in the central " \
           "`storage` database (`storage` tool: put/get/list/search/set_ref/delete), NOT as scattered files in " \
-          "the repository worktree. Read entities back with `read_file(path: 'rubik://storage/<type>/<id>')`; " \
-          "browse with `rubik://storage/index` and `rubik://storage/<type>` listings.",
+          "the repository worktree. Read, list, and search all entity types (`goal`, `plan`, `memory`, `wiki`, " \
+          "`transcript`, `review`, `note`) via `storage` or `read_file(path: 'rubik://storage/<type>/<id>')` " \
+          "(browse with `rubik://storage/index` and `rubik://storage/<type>` listings); write durable `memory` " \
+          "cards and compiled `wiki` pages through `vakanuvis` (`record` / `digest`) whenever `vakanuvis` is in " \
+          "your toolbelt, reserving direct `storage` `put` on `memory`/`wiki` for sessions where `vakanuvis` is " \
+          "unavailable.",
         "run_command" =>
           "GitHub facts must be verified, not assumed: after `gh pr merge` (which can succeed with EMPTY output) " \
           "confirm the merge with `gh pr view <number> --json state`; `mergeable: UNKNOWN` right after a push means " \
@@ -55,12 +62,12 @@ module Rubik
           "dispatching a subagent, paste the relevant recall digest (or its rubik:// link) into the task brief. " \
           "At the end of a task, persist only the durable knowledge with `vakanuvis(action: 'record', topic: '...', " \
           "body: '...')` — memory writes go through record (ref minting, upsert, supersede come free), never " \
-          "through raw storage puts. Recall is keyword-AND over card/page text, so END every recorded body and " \
-          "digest query with its own vocabulary: include a `Keywords:` line listing 5-10 synonyms in BOTH working " \
-          "languages (e.g. TR + EN) — a Turkish query cannot otherwise find an English page. If recall is too " \
-          "shallow, queue `vakanuvis(action: 'digest', query: '...')`: it returns a deterministic receipt and " \
-          "compiles the wiki page asynchronously. Make the session close a standard digest point: review the " \
-          "session's new cards, queue one digest per open topic, and let the home index refresh.",
+          "through raw storage puts when `vakanuvis` is available. Recall is keyword-AND over card/page text, so END " \
+          "every recorded body and digest query with its own vocabulary: include a `Keywords:` line listing 5-10 " \
+          "synonyms in BOTH working languages (e.g. TR + EN) — a Turkish query cannot otherwise find an English page. " \
+          "If recall is too shallow, queue `vakanuvis(action: 'digest', query: '...')`: it returns a deterministic " \
+          "receipt and compiles the wiki page asynchronously. Make the session close a standard digest point: review " \
+          "the session's new cards, queue one digest per open topic, and let the home index refresh.",
         "prune_context" =>
           "When long sessions leave stale exploration and superseded tool output weighing on the ROOT window, " \
           "check `prune_context(action: 'status')` (window estimate vs ceiling, staged plan state) and force a " \

data/lib/rubik/sandbox/driver/bubblewrap.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") # rubocop:disable Lint/UnusedMethodArgument
-          start_time = Time.now
           workspace = File.expand_path(chdir)
 
           bwrap_cmd = [
@@ -42,66 +41,21 @@ module Rubik
           bwrap_cmd.push("--unshare-pid", "--die-with-parent")
           bwrap_cmd.push("sh", "-c", cmd)
 
-          stdout_str = ""
-          stderr_str = ""
-          exit_code = 127
-          pid = nil
+          res = Rubik::Platform.popen_capture(
+            *bwrap_cmd,
+            timeout: timeout,
+            chdir: workspace,
+            timeout_message: "Bubblewrap execution timed out after #{timeout} seconds",
+            error_message: "Bubblewrap execution error"
+          )
 
-          begin
-            Timeout.timeout(timeout) do
-              Open3.popen3(*bwrap_cmd) 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 = "Bubblewrap execution timed out after #{timeout} seconds"
-            exit_code = 124
-          rescue StandardError => e
-            stderr_str = "Bubblewrap execution 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: "bwrap"
           }
         end