@hicaru/pi-rlm 0.1.1 → 0.1.2

package/README.md

@@ -1,25 +1,40 @@
+# pi-rlm — Save 99% tokens, Recursive Language Model (RLM) for the Pi
+
 <div align="center">
 
-<img src="../../assets/hero.png" alt="pi-rlm">
+**Recursive Language Models (RLMs)**, implemented natively as a Pi extension —
+FULLY LOCAL.
 
 </div>
 
-<div align="center">
+## Install
 
-<sub>
-**English** &nbsp;·&nbsp; <a href="README.zh-CN.md">中文</a> &nbsp;·&nbsp; <a href="README.ru.md">Русский</a>
-</sub>
+```bash
+pi install npm:@hicaru/pi-rlm
+```
 
-</div>
+To remove it later:
 
----
+```bash
+pi uninstall npm:@hicaru/pi-rlm
+```
+
+Then run `/reload` or restart Pi. Verify with `pi list` that the package appears in
+`settings.packages`, and check that `/rlm`, `/rlm-config`, and `/rlm-stop` appear under **[Extensions]**.
+
+<div align="center">
+
+<a href="https://arxiv.org/abs/2512.24601"><img src="../../assets/hero.png" alt="pi-rlm"></a>
 
-# pi-rlm — Recursive Language Models for the [Pi](https://github.com/earendil-works) Coding Agent
+<sub>Modeled on the method in the RLM paper, reimplemented natively for Pi.</sub>
+
+</div>
 
 <div align="center">
 
-**Recursive Language Models (RLMs)**, implemented natively as a Pi extension —
-no extra servers, no Docker, no sockets.
+<sub>
+**English** &nbsp;·&nbsp; <a href="README.zh-CN.md">中文</a> &nbsp;·&nbsp; <a href="README.ru.md">Русский</a>
+</sub>
 
 </div>
 
@@ -46,59 +61,31 @@ sub-LLM calls, hence the name.
 - Hard sub-problems **recurse** into child RLMs via `rlm_query` (depth-capped).
 - Everything runs **in-process** — the only external process is one local `python3` worker.
 
-> This is a Pi-plugin reimplementation of the RLM method (see the [RLM paper](https://arxiv.org/abs/2512.24601)
-> and the [Python `rlm` library](https://github.com/alexzhang13/rlm-minimal)). It is **not** the Python library.
+> This is a Pi-plugin reimplementation of the RLM method (see the [RLM paper](https://arxiv.org/abs/2512.24601)).
+> It is **not** the Python library.
 
 ## How it works
 
 ```
-pi process (TypeScript)
- ├─ /rlm  ──► engine drives the SMART (root) model turn-by-turn (writes ```repl``` Python)
- │             │  each turn: parse repl blocks ──► run in sandbox ──► feed stdout back
- │             ▼
- ├─ bridge ── llm_query / llm_query_batched ──► WORKER model (serverless, in-process)
- │            rlm_query ──► recursive child RLM (own sandbox), depth-capped
- ├─ AgentTree ──► live agent/subagent tree above the editor (roles, depth, cost, tokens)
- └─ PythonSandbox ── `python3 worker.py` ──[JSONL over stdio, bidirectional]── persistent REPL
-```
-
-- **No servers, no sockets, no Docker.** The only external process is one local `python3` sandbox.
-  When sandbox code calls `llm_query`, the worker writes a request on stdout and blocks on stdin;
-  Pi services it in-process and writes the reply back. **Provider API keys never enter the sandbox.**
-- The sandbox exposes `context`, `llm_query`, `llm_query_batched`, `rlm_query`,
-  `rlm_query_batched`, `SHOW_VARS()`, `todo()`, `ask_user_question()`, and an `answer` dict.
-  The model submits its final result by setting `answer["ready"] = True`.
-
-## Install
-
-`pi-rlm` is a Pi package. Pi provides the `@earendil-works/pi-*` and `typebox` peer
-dependencies; do **not** install a separate copy of them into this package. Requires
-`python3` on `PATH` (standard library only).
-
-Recommended local install while developing:
-
-```bash
-pi install /path/to/this-repo/pi-plugin/rlm
-```
-
-Published npm package install:
-
-```bash
-npm publish                       # e.g. as @<you>/pi-rlm
-pi install npm:@<you>/pi-rlm
+          ┌─────────────────────────┐
+          │     Pi coding agent     │
+          └────────────┬────────────┘
+                       │  /rlm
+                       ▼
+          ┌─────────────────────────┐  spawns   ┌────────────────────┐
+          │  Smart model (root)     │ ────────►  │   Worker models    │
+          │  drives a Python REPL   │ ◄────────  │   (cheap, fast)    │
+          └────────────┬────────────┘  results  └────────────────────┘
+                       │ recursion (depth-capped)
+                       └────► child RLMs ────► (same loop)
+
+   All local · one python3 process · no servers
 ```
 
-> **Git installs** require the package manifest to live at the installed repository root.
-> For monorepo subdirectories like this one, prefer the local-path or npm flow above.
-
-If you previously copied the extension folder directly, remove it so it does not shadow the package:
-
-```bash
-rm -rf ~/.pi/agent/extensions/rlm
-```
-
-Then run `/reload` or restart Pi. Verify with `pi list` that the package appears in
-`settings.packages`, and check that `/rlm`, `/rlm-config`, and `/rlm-stop` appear under **[Extensions]**.
+- The **smart model** thinks and writes Python in a REPL.
+- The **worker models** do the heavy lifting (read, summarize, classify).
+- Hard sub-problems **recurse** into child RLMs.
+- Everything runs **fully local** — your API keys never leave Pi.
 
 ## Commands
 
@@ -129,6 +116,8 @@ These functions are injected into the model's Python namespace inside the REPL:
 | `rlm_query_batched` | `(prompts, model=None) -> list[str]` | Concurrent recursive child RLMs |
 | `todo` | `(action, **kwargs) -> str` | Task list: `create`/`update`/`list`/`get`/`delete`/`clear` |
 | `ask_user_question` | `(questions) -> list[dict]` | Ask the user structured questions (depth 0 only) |
+| `stage_edit` | `(path, old_text, new_text) -> str` | Stage a file edit; relayed to the host's native edit flow |
+| `advance_phase` | `(phase, summary=None) -> str` | Move the root pipeline to a new phase |
 | `SHOW_VARS` | `() -> str` | List currently defined variables & their types |
 | `answer` | `dict` | Set `answer["content"]=...; answer["ready"]=True` to finalize |
 
@@ -138,15 +127,18 @@ These functions are injected into the model's Python namespace inside the REPL:
 |---|---|---|
 | Smart model | Pi's active model | the root orchestrator |
 | Worker model | cheapest available | answers `llm_query` |
-| Max recursion depth | `4` | `rlm_query` past this falls back to `llm_query` |
-| Max iterations | `30` | turns before the engine finalizes |
-| Budget ceiling | none | stops the whole tree when USD spend exceeds this |
-| Max consecutive errors | `5` | stops after N consecutive error turns |
-| REPL block timeout | `120s` | per-`repl`-block wall-clock (SIGALRM in the worker) |
-| Max concurrent sub-calls | `4` | pool size for `*_batched` |
-| Orchestrator addendum | on | "delegate, don't solve" guidance |
-| Trajectory compaction | on (0.85) | summarize history when it nears the context window |
-| `yolo` | off | apply proposed edits immediately, skipping the review popup |
+| Max recursion depth | `4` | `rlm_query` past this degrades to plain `llm_query` |
+| Max iterations | `30` | root REPL turns before RLM asks for a final answer |
+| REPL block timeout (s) | `120` | wall-clock limit for one Python REPL block (SIGALRM) |
+| Max concurrent sub-calls | `4` | concurrency pool size for `*_batched` |
+| Budget ceiling (USD) | none | total spend cap for the whole recursive tree |
+| Wall-clock ceiling (min) | none | total runtime cap for the whole recursive tree |
+| Token ceiling | none | total input+output token cap for the whole recursive tree |
+| Max consecutive errors | `5` | stop after N consecutive failing turns (none = off) |
+| Orchestrator addendum | on | divide-and-conquer guidance in the root system prompt |
+| Trajectory compaction | on (0.65) | summarize old turns when history nears the context window |
+| Root model output cap (tok) | `16384` | max output tokens per root-model turn |
+| Sandbox init timeout | `30000` ms | how long to wait for the Python worker to start |
 | `askUserQuestion` | on | expose `ask_user_question()` to the model |
 | `todo` | on | expose `todo()` to the model |
 
@@ -155,13 +147,6 @@ These functions are injected into the model's Python namespace inside the REPL:
 > defaults (depth 4, conc 4) that's 4³ = 64 in the pathological case. Budget and error
 > caps (above) bound total spend regardless of fan-out.
 
-## Run logs
-
-- **Run logs** (`runLog`): always-on by default. Each run writes a JSONL trail to `.rlm/runs/`
-  (default), capped at `maxRuns` (50). Supports **snapshots** (`sandbox.pkl`) and **resume**
-  of interrupted runs via `/rlm-resume`. Snapshots are protected by a per-session `nonce`
-  to prevent cross-session replay.
-
 ## Security
 
 - **Key isolation**: provider keys live only in TypeScript (`AuthStorage`); the sandbox
@@ -177,56 +162,3 @@ These functions are injected into the model's Python namespace inside the REPL:
   SIGALRM timeout + parent watchdog (SIGKILL on hang); budget / token / timeout /
   consecutive-error caps.
 - **Trust**: project-local install requires Pi project trust.
-
-## Project layout
-
-```
-src/
-  sandbox/    worker.py + JSONL stdio driver (PythonSandbox) · protocol.ts · sandbox-manager.ts
-  bridge/     model.ts (one-shot completion) · llm-query.ts · rlm-query.ts (recursion)
-  core/       engine.ts (the loop) · iteration · limits · answer · compaction · pipeline · types
-  prompts/    system + per-turn prompts (ported from the Python reference)
-  text/       parsing (repl blocks) · tokens · preview · edits
-  state/      reads/writes · resume · paths · rows
-  tool/       repl-tool · rlm-events · aggregator · propose-edits · emitter-listener
-  config/     defaults · settings (rlm.json persistence + validation)
-  context/    repomix-based repository packing + caching
-  ui/         tree-widget · status · model-picker · config-panel · intro · theme
-  commands/   rlm · rlm-config
-  mode/       rlm-mode (controller) · input-router
-  patch/      apply · popup · index
-  util/       errors · concurrency
-test/         phase1–phase9 · native-smoke · native-mode · helpers
-```
-
-## Tests
-
-Runtime is **Bun** (`bun install`, `bun run …` — never npm/pnpm/yarn).
-
-```bash
-bun run test/phase1.ts                   # sandbox: exec, persistence, key isolation, timeout kill
-bun run test/phase4.ts                   # recursion depth-cap logic (no tokens)
-bun run test/phase5.ts                   # live agent tree rendering (no tokens)
-RLM_TEST_LIVE=1 bun run test/phase2.ts   # real llm_query through the sandbox
-RLM_TEST_LIVE=1 bun run test/phase3.ts   # real end-to-end /rlm over a file context
-RLM_TEST_LIVE=1 bun run test/phase4.ts   # engine solves a 20-doc needle-in-haystack
-```
-
-## Background
-
-Modeled on the Python reference [`rlm`](https://github.com/alexzhang13/rlm-minimal) and the
-method in the [RLM paper](https://arxiv.org/abs/2512.24601), reimplemented natively for Pi.
-
-If you use this in your research, please cite the original RLM work:
-
-```bibtex
-@misc{zhang2026recursivelanguagemodels,
-      title={Recursive Language Models},
-      author={Alex L. Zhang and Tim Kraska and Omar Khattab},
-      year={2026},
-      eprint={2512.24601},
-      archivePrefix={arXiv},
-      primaryClass={cs.AI},
-      url={https://arxiv.org/abs/2512.24601},
-}
-```

package/README.ru.md

@@ -19,7 +19,7 @@
 <div align="center">
 
 **Рекурсивные языковые модели (RLMs)**, реализованные нативно как расширение Pi —
-без дополнительных серверов, Docker или сокетов.
+ПОЛНОСТЬЮ ЛОКАЛЬНО.
 
 </div>
 
@@ -36,8 +36,8 @@
 - Сложные подзадачи **рекурсивно** передаются в дочерние RLM через `rlm_query` (с ограничением глубины).
 - Все работает **in-process** — единственным внешним процессом является локальный worker `python3`.
 
-> This is a Pi-plugin reimplementation of the RLM method (see the [RLM paper](https://arxiv.org/abs/2512.24601)
-> and the [Python `rlm` library](https://github.com/alexzhang13/rlm-minimal)). It is **not** the Python library.
+> This is a Pi-plugin reimplementation of the RLM method (see the [RLM paper](https://arxiv.org/abs/2512.24601)).
+> It is **not** the Python library.
 
 ## Как это работает
 
@@ -181,7 +181,7 @@ RLM_TEST_LIVE=1 bun run test/phase4.ts   # engine solves a 20-doc needle-in-hays
 
 ## Общая информация
 
-Реализовано на основе эталонного проекта [`rlm`](https://github.com/alexzhang13/rlm-minimal) на Python и метода из [статьи RLM](https://arxiv.org/abs/2512.24601), с нативной переработкой для Pi.
+Реализовано на основе метода из [статьи RLM](https://arxiv.org/abs/2512.24601), с нативной переработкой для Pi.
 
 Если вы используете этот проект в своих исследованиях, пожалуйста, сошлитесь на оригинальную работу RLM:
 

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 <div align="center">
 
 **递归语言模型 (RLMs)** 作为 Pi 扩展原生实现 ——
-无需额外服务器，无需 Docker，无需 socket。
+完全本地。
 
 </div>
 
@@ -36,8 +36,8 @@
 - 困难的子问题通过 `rlm_query` **递归**到子 RLM 中（设有深度限制）。
 - 所有内容均**在进程内**运行 —— 唯一的外部进程是一个本地的 `python3` worker。
 
-> 这是 RLM 方法的 Pi 插件重新实现（参见 [RLM 论文](https://arxiv.org/abs/2512.24601)
-> 和 [Python `rlm` 库](https://github.com/alexzhang13/rlm-minimal)）。它**不是**那个 Python 库。
+> 这是 RLM 方法的 Pi 插件重新实现（参见 [RLM 论文](https://arxiv.org/abs/2512.24601)）。
+> 它**不是**那个 Python 库。
 
 ## 工作原理
 
@@ -201,8 +201,7 @@ RLM_TEST_LIVE=1 bun run test/phase4.ts   # 引擎解决 20 个文档的“大海
 
 ## 背景
 
-基于 Python 参考实现 [`rlm`](https://github.com/alexzhang13/rlm-minimal) 和
-[RLM 论文](https://arxiv.org/abs/2512.24601) 中的方法，为 Pi 原生重新实现。
+基于 [RLM 论文](https://arxiv.org/abs/2512.24601) 中的方法，为 Pi 原生重新实现。
 
 如果您在研究中使用此项目，请引用原始 RLM 工作：
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hicaru/pi-rlm",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
-  "description": "Recursive Language Model (RLM) for the Pi coding agent — native, server-less.",
+  "description": "Save 99% tokens, Recursive Language Model (RLM) for the Pi",
   "license": "MIT",
   "author": "hicaru",
   "repository": {

package/src/index.ts

@@ -16,7 +16,7 @@ import { packRepository, formatForLLM, serializeForSandbox } from "./context/rep
 import { buildNativeSystemPrompt } from "./prompts/system.ts";
 import { errorMessage } from "./util/errors.ts";
 
-const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep", "bash"]));
+const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep"]));
 
 export default function rlmExtension(pi: ExtensionAPI): void {
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
@@ -28,6 +28,23 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     python: config.python,
     sandboxInitTimeoutMs: config.sandboxInitTimeoutMs,
   });
+  let packedContextText: string | undefined;
+  let contextPackPromise: Promise<string | undefined> | undefined;
+  const ensureRepositoryContext = async (cwd: string): Promise<string | undefined> => {
+    if (packedContextText !== undefined && sandboxManager.contextPayload !== null) return packedContextText;
+    contextPackPromise ??= packRepository(cwd)
+      .then((result) => {
+        if (!result.ok) {
+          console.warn(`[rlm] repository context pack failed: ${result.error}`);
+          return undefined;
+        }
+        sandboxManager.contextPayload = serializeForSandbox(result.value);
+        packedContextText = formatForLLM(result.value);
+        return packedContextText;
+      })
+      .finally(() => { contextPackPromise = undefined; });
+    return contextPackPromise;
+  };
 
   // Load persisted settings async — applied before session_start handler reads controller state
   const settingsReady = loadSettings()
@@ -81,6 +98,10 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           getWorkerModel: () => controller.resolveModels(ctx)?.worker,
           registry: ctx.modelRegistry,
           config: controller.config,
+          ensureContext: async () => {
+            const contextText = await ensureRepositoryContext(ctx.cwd ?? process.cwd());
+            if (contextText === undefined) throw new Error("repository context could not be loaded into RLM sandbox");
+          },
         }));
       } catch { /* re-registration on provider change — ignore if already registered */ }
     }
@@ -107,14 +128,13 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
     // Inject repository context as a compact listing (once per session, only when RLM is enabled)
     if (controller.enabled && !contextInjected) {
-      contextInjected = true;
       const cwd = ctx.cwd ?? process.cwd();
-      const result = await packRepository(cwd);
-      if (result.ok) {
-        const contextText = formatForLLM(result.value);
+      const contextText = await ensureRepositoryContext(cwd);
+      if (contextText !== undefined) {
+        contextInjected = true;
         const instruction = [
-          "ANALYZE THIS REPOSITORY using repl({code}) — read/grep/bash are DISABLED.",
-          `Total: ${result.value.totalFiles} files, ${result.value.totalChars.toLocaleString()} chars — must use repl().`,
+          "ANALYZE THIS REPOSITORY using repl({code}) — read/grep are DISABLED.",
+          "Repository contents are pre-loaded in the Python REPL `context` variable.",
           "Chunk context via Python, delegate to llm_query. If credits exhausted → report and stop.",
           "",
         ].join("\n");
@@ -124,9 +144,6 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           timestamp: 0,
         } as (typeof filtered)[number];
 
-        // Store context for sandbox loading on first repl() call
-        sandboxManager.contextPayload = serializeForSandbox(result.value);
-
         return { messages: [contextMsg, ...filtered] };
       }
     }
@@ -141,7 +158,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
   // ── Tool restriction: block analysis tools when RLM is ON ──
   // `edit`/`write` stay unblocked so the agent modifies files through Pi's native
-  // tool flow (visible to all plugins, +/- diff preview). Only read/grep/bash are
+  // tool flow (visible to all plugins, +/- diff preview). Only read/grep are
   // blocked — the repository is pre-loaded in the REPL `context` variable.
   pi.on("tool_call", async (event) => {
     if (!controller.enabled) return;
@@ -158,5 +175,8 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     controller.abort();
     await sandboxManager.dispose();
     contextInjected = false;
+    packedContextText = undefined;
+    contextPackPromise = undefined;
+    sandboxManager.contextPayload = null;
   });
 }

package/src/prompts/system.ts

@@ -230,7 +230,7 @@ export function buildNativeSystemPrompt(): string {
     "║  NATIVE RLM MODE — YOU ARE AN ORCHESTRATOR, NOT A READER      ║",
     "╚══════════════════════════════════════════════════════════════════╝",
     "",
-    "ABSOLUTE RESTRICTION: Do NOT use `read`, `grep`, or `bash` to access files.",
+    "ABSOLUTE RESTRICTION: Do NOT use `read` or `grep` to access files.",
     "All file content is pre-loaded in the REPL `context` variable. Use ONLY `repl({code})`.",
     "If sub-LLM credits are exhausted → report the error to the user and stop.",
     "",

package/src/sandbox/sandbox-manager.ts

@@ -35,8 +35,7 @@ export class SandboxManager {
    * given handlers. Subsequent calls return the existing sandbox immediately.
    * Deduplicates concurrent calls via initPromise.
    *
-   * The caller is responsible for calling loadContext() on the returned sandbox
-   * before first use.
+   * If contextPayload is set, it is loaded before the sandbox is returned.
    */
   async getOrCreate(handlers: Partial<SubLlmHandlers>): Promise<PythonSandbox> {
     if (this.disposed) throw new Error("SandboxManager disposed");
@@ -45,8 +44,8 @@ export class SandboxManager {
       // "context" event's async packRepository resolves after the first repl() call).
       // Load it into the live sandbox now if still pending.
       if (this.contextPayload !== null && !this.contextLoaded) {
+        await this.sandbox.loadContext(this.contextPayload);
         this.contextLoaded = true;
-        try { await this.sandbox.loadContext(this.contextPayload); } catch { /* best-effort */ }
       }
       return this.sandbox;
     }
@@ -61,15 +60,16 @@ export class SandboxManager {
       initTimeoutMs: this.config.sandboxInitTimeoutMs,
       handlers,
     }).then(async (s) => {
-      // Load context on first creation if available
+      // Load context on first creation if available.
       if (this.contextPayload !== null) {
+        await s.loadContext(this.contextPayload);
         this.contextLoaded = true;
-        try { await s.loadContext(this.contextPayload); } catch { /* best-effort */ }
       }
       this.sandbox = s;
       this.initPromise = null;
       return s;
     }).catch((err) => {
+      this.contextLoaded = false;
       this.initPromise = null;
       throw err;
     });
@@ -115,6 +115,7 @@ export class SandboxManager {
         // Best-effort dispose of the dead sandbox
         try { await this.sandbox.dispose(); } catch { /* already dead */ }
         this.sandbox = null;
+        this.contextLoaded = false;
       }
       throw err;
     } finally {
@@ -139,5 +140,6 @@ export class SandboxManager {
     this.disposed = true;
     await this.sandbox?.dispose();
     this.sandbox = null;
+    this.contextLoaded = false;
   }
 }

package/src/sandbox/sandbox.ts

@@ -161,6 +161,7 @@ export class PythonSandbox {
     try {
       path = await this.writeContextFile(payload, isJson);
       const res = await this.request({ type: "load_context", path, index, json: isJson });
+      if (!res.ok) throw new Error(res.error ?? "load_context failed");
       return res.index ?? 0;
     } finally {
       if (path) await unlink(path).catch(() => {});
@@ -183,6 +184,7 @@ export class PythonSandbox {
 
   async exec(code: string): Promise<ReplResult> {
     const res = await this.request({ type: "exec", code });
+    if (!res.ok) throw new Error(res.error ?? "exec failed");
     return {
       stdout: res.stdout ?? "",
       stderr: res.stderr ?? "",
@@ -212,6 +214,7 @@ export class PythonSandbox {
   async snapshot(path: string, nonce: string): Promise<boolean> {
     try {
       const res = await this.request({ type: "snapshot", path, nonce });
+      if (!res.ok) return false;
       return res.ok;
     } catch {
       return false;
@@ -222,6 +225,7 @@ export class PythonSandbox {
   async restore(path: string, nonce: string): Promise<boolean> {
     try {
       const res = await this.request({ type: "restore", path, nonce });
+      if (!res.ok) return false;
       return res.ok;
     } catch {
       return false;

package/src/tool/repl-tool.ts

@@ -24,7 +24,7 @@ import { previewText } from "../text/preview.ts";
 import { mapPool } from "../util/concurrency.ts";
 import { LimitGuard } from "../core/limits.ts";
 import { checkResourceLimits } from "../core/resource-limits.ts";
-import type { RlmConfig, Sampling } from "../core/types.ts";
+import type { InteractiveDeps, RlmConfig, Sampling } from "../core/types.ts";
 import { SandboxManager } from "../sandbox/sandbox-manager.ts";
 import type { SubLlmHandlers } from "../sandbox/sandbox.ts";
 import type { ProposedEdit, ReplResult } from "../sandbox/protocol.ts";
@@ -64,12 +64,14 @@ class NativeBridgeState {
   currentParentId: string | undefined;
   currentDepth = 0;
   currentLimits: LimitGuard | null = null;
+  currentInteractive: InteractiveDeps | null = null;
 
-  swap(inv: { emitter: RlmEmitter; parentId?: string; depth: number; limits: LimitGuard }): void {
+  swap(inv: { emitter: RlmEmitter; parentId?: string; depth: number; limits: LimitGuard; interactive: InteractiveDeps }): void {
     this.currentEmitter = inv.emitter;
     this.currentParentId = inv.parentId;
     this.currentDepth = inv.depth;
     this.currentLimits = inv.limits;
+    this.currentInteractive = inv.interactive;
   }
 
   buildLlmHandlers(deps: {
@@ -224,6 +226,8 @@ class NativeBridgeState {
           maxTokens: deps.config.maxTokens,
           maxErrors: deps.config.maxErrors,
         },
+        onTodo: state.currentInteractive?.onTodo,
+        onAskUserQuestion: state.currentInteractive?.onAskUserQuestion,
       });
 
       try {
@@ -277,6 +281,7 @@ export interface ReplToolDeps {
   readonly config: RlmConfig;
   readonly signal?: AbortSignal;
   readonly onUsage?: (usage: Usage, role: "sub") => void;
+  readonly ensureContext?: () => Promise<void>;
 }
 
 export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplToolParams, ReplDetails> {
@@ -378,6 +383,7 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
           parentId: undefined,
         });
 
+        await deps.ensureContext?.();
         await sandboxManager.getOrCreate({
           ...llmHandlers,
           ...rlmHandlers,
@@ -399,7 +405,7 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
           // Wire per-invocation mutable state only after the serialized exec slot
           // is active. Swapping earlier would let queued repl() calls overwrite
           // emitter/limits for the currently running REPL execution.
-          bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits });
+          bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits, interactive });
         });
         const elapsed = Date.now() - start;
         capturedStdout = result.stdout;