@hicaru/pi-rlm 0.1.2 → 0.1.5

package/README.md

@@ -24,7 +24,7 @@ Then run `/reload` or restart Pi. Verify with `pi list` that the package appears
 
 <div align="center">
 
-<a href="https://arxiv.org/abs/2512.24601"><img src="../../assets/hero.png" alt="pi-rlm"></a>
+<a href="https://arxiv.org/abs/2512.24601"><img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" alt="pi-rlm"></a>
 
 <sub>Modeled on the method in the RLM paper, reimplemented natively for Pi.</sub>
 
@@ -112,6 +112,7 @@ These functions are injected into the model's Python namespace inside the REPL:
 | `context` | `list[dict]` | Repository packed as `[{"path","content","tokens"}, ...]` — the full codebase |
 | `llm_query` | `(prompt, model=None) -> str` | One-shot sub-LLM call (worker model) |
 | `llm_query_batched` | `(prompts, model=None) -> list[str]` | Concurrent sub-LLM calls (pool-bounded) |
+| `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | Split large text into cap-sized chunks and fan out via sub-LLMs |
 | `rlm_query` | `(prompt, model=None) -> str` | Recursive child RLM with its own sandbox (depth-capped) |
 | `rlm_query_batched` | `(prompts, model=None) -> list[str]` | Concurrent recursive child RLMs |
 | `todo` | `(action, **kwargs) -> str` | Task list: `create`/`update`/`list`/`get`/`delete`/`clear` |

package/README.ru.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="../../assets/hero.png" alt="pi-rlm">
+<img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" alt="pi-rlm">
 
 </div>
 
@@ -106,6 +106,7 @@ rm -rf ~/.pi/agent/extensions/rlm
 | `context` | `list[dict]` | Репозиторий, упакованный как `[{"path","content","tokens"}, ...]` — вся кодовая база |
 | `llm_query` | `(prompt, model=None) -> str` | Одноразовый вызов sub-LLM (worker-модель) |
 | `llm_query_batched` | `(prompts, model=None) -> list[str]` | Параллельные вызовы sub-LLM (с ограничением пула) |
+| `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | Дробит большой текст на части по лимиту и обрабатывает через sub-LLM |
 | `rlm_query` | `(prompt, model=None) -> str` | Рекурсивный дочерний RLM со своей песочницей (с ограничением глубины) |
 | `rlm_query_batched` | `(prompts, model=None) -> list[str]` | Параллельные рекурсивные дочерние RLM |
 | `todo` | `(action, **kwargs) -> str` | Список задач: `create`/`update`/`list`/`get`/`delete`/`clear` |

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="../../assets/hero.png" alt="pi-rlm">
+<img src="https://github.com/openzebra/rlm.pi/blob/master/assets/hero.png?raw=true" alt="pi-rlm">
 
 </div>
 
@@ -113,6 +113,7 @@ rm -rf ~/.pi/agent/extensions/rlm
 | `context` | `list[dict]` | 打包为 `[{"path","content","tokens"}, ...]` 的仓库 —— 完整的代码库 |
 | `llm_query` | `(prompt, model=None) -> str` | 单次子 LLM 调用 (worker 模型) |
 | `llm_query_batched` | `(prompts, model=None) -> list[str]` | 并发子 LLM 调用 (池上限) |
+| `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | 将大文本拆分为不超过上限的块并通过子 LLM 处理 |
 | `rlm_query` | `(prompt, model=None) -> str` | 具有自有沙箱的递归子 RLM (设有深度限制) |
 | `rlm_query_batched` | `(prompts, model=None) -> list[str]` | 并发递归子 RLM |
 | `todo` | `(action, **kwargs) -> str` | 任务列表：`create`/`update`/`list`/`get`/`delete`/`clear` |

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@hicaru/pi-rlm",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "type": "module",
   "description": "Save 99% tokens, Recursive Language Model (RLM) for the Pi",
   "license": "MIT",
   "author": "hicaru",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hicaru/rlm.pi.git"
+    "url": "git+https://github.com/openzebra/rlm.pi.git"
   },
-  "homepage": "https://github.com/hicaru/rlm.pi",
+  "homepage": "https://github.com/openzebra/rlm.pi",
   "bugs": {
-    "url": "https://github.com/hicaru/rlm.pi/issues"
+    "url": "https://github.com/openzebra/rlm.pi/issues"
   },
   "files": [
     "src/",

package/src/bridge/llm-query.ts

@@ -11,6 +11,7 @@ import type { Api, Model, Usage } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import type { RlmEmitter } from "../tool/rlm-events.ts";
 import { modelRef, resolveModelId } from "../config/settings.ts";
+import { checkResourceLimits, type RemainingResources } from "../core/resource-limits.ts";
 import type { Sampling } from "../core/types.ts";
 import { type ChatMsg, modelComplete } from "./model.ts";
 import { previewText } from "../text/preview.ts";
@@ -26,6 +27,8 @@ export interface LlmBridgeOptions {
   readonly sampling?: Sampling;
   readonly signal?: AbortSignal;
   readonly onUsage?: (usage: Usage, model: Model<Api>) => void;
+  /** Parent run's remaining budget/timeout; checked before every sub-call. */
+  readonly remainingBudget?: () => RemainingResources;
   /** Live RlmDetails reporting via onUpdate. */
   readonly emitter?: RlmEmitter;
   readonly parentId?: string;
@@ -49,6 +52,11 @@ export function createLlmBridge(opts: LlmBridgeOptions): LlmBridge {
 
   // Run one completion; report cost/tokens via `track` (a per-call or per-batch accumulator).
   async function complete1(prompt: string, model: string | null, track: (u: Usage) => void): Promise<string> {
+    const rem = opts.remainingBudget?.();
+    if (rem !== undefined) {
+      const limitError = checkResourceLimits(rem);
+      if (limitError !== undefined) return limitError;
+    }
     if (prompt.length > maxPromptChars) {
       return formatError(`sub-LLM prompt exceeded the size limit (${prompt.length.toLocaleString()} chars > ${maxPromptChars.toLocaleString()}). Shorten or chunk the prompt before calling llm_query.`);
     }

package/src/config/defaults.ts

@@ -20,6 +20,7 @@ export const DEFAULT_CONFIG: Readonly<RlmConfig> = Object.freeze({
   maxPromptChars: 400_000,
   maxErrors: 5,
   orchestrator: true,
+  pipeline: false,
   compaction: true,
   compactionThresholdPct: 0.65,
   python: "python3",

package/src/config/settings.ts

@@ -73,6 +73,8 @@ function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (maxErrors !== undefined) out.maxErrors = maxErrors;
   const orchestrator = validateBoolean(r.orchestrator);
   if (orchestrator !== undefined) out.orchestrator = orchestrator;
+  const pipeline = validateBoolean(r.pipeline);
+  if (pipeline !== undefined) out.pipeline = pipeline;
   const compaction = validateBoolean(r.compaction);
   if (compaction !== undefined) out.compaction = compaction;
   const compactionThresholdPct = validateNumber(r.compactionThresholdPct, 0);

package/src/context/repomix-context.ts

@@ -98,6 +98,7 @@ export async function packRepository(
         output: {
           filePath: `${tmpdir()}/repomix-out-${Date.now()}.txt`,
           style: "plain",
+          filePathStyle: "cwd-relative",
           parsableStyle: false,
           headerText: undefined,
           instructionFilePath: undefined,
@@ -219,7 +220,7 @@ const MAX_LLM_LISTING_FILES = 200;
 /**
  * Produces a compact human-readable text block for the parent LLM's context window.
  * Shows file paths and token estimates — NOT full file contents (those are too large
- * for the context window). The LLM uses its file-reading tools to inspect specific files.
+ * for the context window). The LLM inspects files via repl() over the pre-loaded context variable.
  */
 export function formatForLLM(bundle: ContextBundle): string {
   const files = bundle.files.slice(0, MAX_LLM_LISTING_FILES);
@@ -237,7 +238,8 @@ export function formatForLLM(bundle: ContextBundle): string {
     listing,
     truncated,
     "",
-    "To read a file, use the file-reading tools with the exact path.",
+    "All file contents are pre-loaded in the REPL `context` variable — file-reading tools are disabled.",
+    "Use repl({code}) and delegate semantic reading to llm_query / llm_query_batched / llm_query_chunked.",
   ].join("\n");
 }
 

package/src/core/answer.ts

@@ -37,10 +37,11 @@ export function turnHadError(results: readonly ReplResult[]): boolean {
  * hist ← hist ∥ code ∥ Metadata(stdout)). */
 const SMALL_STDOUT_LIMIT = 800;
 const STDOUT_PREVIEW_LIMIT = 200;
+const STDOUT_TAIL_LIMIT = 200;
 const STDERR_LIMIT = 8_000;
 
 /** The REPL output fed back to the model as the next user message. */
-export function formatReplOutputs(results: readonly ReplResult[]): string {
+export function formatReplOutputs(results: readonly ReplResult[], skippedBlocks = 0): string {
   if (results.length === 0) {
     return "No ```repl``` block found in your response. Write one to interact with the REPL.";
   }
@@ -54,15 +55,18 @@ export function formatReplOutputs(results: readonly ReplResult[]): string {
     parts.push(`${head}${text}${formatStderr(r)}`);
   }
   const body = parts.join("\n\n");
+  const skipNote = skippedBlocks > 0
+    ? `\n\n[${skippedBlocks} later \`\`\`repl\`\`\` block(s) skipped because an earlier block raised — fix and re-run them]`
+    : "";
   // Orientation hint only when the model lost output to elision — otherwise it sees everything.
-  if (!hadElision) return body;
+  if (!hadElision) return `${body}${skipNote}`;
   // The REPL namespace is persistent across blocks in a turn, so the last block's varNames reflect
   // every variable created in any earlier block too.
   const varNames = results.at(-1)?.varNames ?? [];
   const hint = varNames.length > 0
     ? `REPL vars: ${varNames.join(", ")}`
     : `No REPL vars yet — assign results to variables before printing large outputs.`;
-  return `${body}\n\n${hint}`;
+  return `${body}${skipNote}\n\n${hint}`;
 }
 
 /** Stdout ≤ SMALL_STDOUT_LIMIT flows through verbatim; larger output keeps a short head + a note
@@ -71,8 +75,15 @@ function formatStdout(r: ReplResult): { text: string; elided: boolean } {
   const out = r.stdout.trim();
   if (!out) return { text: "(no stdout)", elided: false };
   if (out.length <= SMALL_STDOUT_LIMIT) return { text: out, elided: false };
-  const note = `[+${out.length - STDOUT_PREVIEW_LIMIT} chars elided — use slices to inspect: print(result[:500])]`;
-  return { text: `${out.slice(0, STDOUT_PREVIEW_LIMIT)}\n${note}`, elided: true };
+  const cut = out.length - STDOUT_PREVIEW_LIMIT - STDOUT_TAIL_LIMIT;
+  return {
+    text: [
+      out.slice(0, STDOUT_PREVIEW_LIMIT),
+      `[… ${cut} chars elided — full output stays in REPL vars; inspect slices: print(result[:500])]`,
+      out.slice(-STDOUT_TAIL_LIMIT),
+    ].join("\n"),
+    elided: true,
+  };
 }
 
 function formatStderr(r: ReplResult): string {

package/src/core/engine.ts

@@ -98,6 +98,10 @@ export function createEngine(deps: EngineDeps): RunRlm {
       maxErrors: deps.limits?.maxErrors,
       maxTokens: deps.limits?.maxTokens,
     }, input.resume?.usageSeed.durationMs ?? 0);
+    const remainingBudget = (): { readonly budgetUsd?: number; readonly timeoutMs?: number } => ({
+      budgetUsd: limits.remainingBudgetUsd(),
+      timeoutMs: limits.remainingTimeoutMs(),
+    });
 
     const llm = createLlmBridge({
       workerModel: deps.workerModel,
@@ -114,6 +118,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
       emitter,
       parentId: selfReportId,
       depth: input.depth,
+      remainingBudget,
     });
     const rlm = createRlmHandlers({
       run,
@@ -122,10 +127,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
       maxDepth: deps.config.maxDepth,
       maxConcurrent: deps.config.maxConcurrentSubcalls,
       parentNodeId: selfReportId,
-      remainingBudget: () => ({
-        budgetUsd: limits.remainingBudgetUsd(),
-        timeoutMs: limits.remainingTimeoutMs(),
-      }),
+      remainingBudget,
       onChildUsage: (costUsd, inputTokens, outputTokens) => {
         limits.addRaw(costUsd, inputTokens, outputTokens);
       },
@@ -150,7 +152,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
           rootPrompt: input.rootPrompt,
           context: { type: contextTypeLabel(input.context), chars: contextLength(input.context), json },
           models: { model: model.id, worker: deps.workerModel.id },
-          meta: { maxIterations: deps.config.maxIterations, maxDepth: deps.config.maxDepth, orchestrator: deps.config.orchestrator, pipeline: true },
+          meta: { maxIterations: deps.config.maxIterations, maxDepth: deps.config.maxDepth, orchestrator: deps.config.orchestrator, pipeline: deps.config.pipeline },
         };
         persistOn = await appendRow(deps.runState.cwd, deps.runState.dir, runId, header);
       }
@@ -166,7 +168,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
     };
 
     try {
-      const phaseHandlers = input.depth === 0
+      const phaseHandlers = input.depth === 0 && deps.config.pipeline
         ? {
             advancePhase: async (phase: string, summary: string | undefined) => {
               const outcome = validatePhaseTransition(phaseState?.current, phase);
@@ -205,6 +207,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
         python: deps.config.python,
         signal: deps.signal,
         initTimeoutMs: deps.config.sandboxInitTimeoutMs,
+        maxPromptChars: deps.config.maxPromptChars,
         handlers: { ...llm, ...rlm, ...phaseHandlers, ...interactiveHandlers },
       });
 
@@ -219,6 +222,8 @@ export function createEngine(deps: EngineDeps): RunRlm {
         recursion: input.depth + 1 < deps.config.maxDepth,
         askUserQuestion: deps.config.askUserQuestion && input.depth === 0,
         todo: deps.config.todo,
+        pipeline: deps.config.pipeline && input.depth === 0,
+        maxPromptChars: deps.config.maxPromptChars,
       });
       let history: ChatMsg[] = input.resume ? input.resume.history : [{ role: "system", content: system }];
       let pendingReplOutputs: string | undefined = input.resume?.pendingReplOutputs;
@@ -247,11 +252,6 @@ export function createEngine(deps: EngineDeps): RunRlm {
         if (selfReportId) emitter.emitSubcallUpdated({ id: selfReportId, detail: `turn ${i + 1}/${deps.config.maxIterations}` });
         else emitter.emitTurn(i + 1, deps.config.maxIterations);
 
-        if (pendingReplOutputs) {
-          appendUserMessage(history, pendingReplOutputs);
-          pendingReplOutputs = undefined;
-        }
-
         if (deps.config.compaction) {
           const compactionDeps = {
             // Summarisation is done by the cheap worker model; the threshold stays on the
@@ -279,7 +279,12 @@ export function createEngine(deps: EngineDeps): RunRlm {
           }
         }
 
-        const gateMsg = phaseGatePrompt(phaseState, completedTurns);
+        if (pendingReplOutputs) {
+          appendUserMessage(history, pendingReplOutputs);
+          pendingReplOutputs = undefined;
+        }
+
+        const gateMsg = deps.config.pipeline ? phaseGatePrompt(phaseState, completedTurns) : undefined;
         const gateUserMsg = gateMsg ? `[${new Date().toISOString()}] ${gateMsg}` : undefined;
         appendUserMessage(history, buildTurnPrompt(i, deps.config.maxIterations, gateUserMsg));
 
@@ -320,7 +325,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
 
         limits.observe(turnHadError(turn.results));
         history.push({ role: "assistant", content: turn.response });
-        const turnReplOutputs = formatReplOutputs(turn.results);
+        const turnReplOutputs = formatReplOutputs(turn.results, turn.skippedBlocks);
         pendingReplOutputs = turnReplOutputs;
 
         if (persistOn && runId && deps.runState) {
@@ -343,7 +348,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
         }
       }
       if (pendingReplOutputs) appendUserMessage(history, pendingReplOutputs);
-      const finalized = result(await finalize(history, deps, limits), deps.config.maxIterations, limits, editsAcc);
+      const finalized = result(await finalize(history, model, deps, limits), deps.config.maxIterations, limits, editsAcc);
       await recordTerminal("finalized", finalized);
       lastAnswer = finalized.answer;
       return finalized;
@@ -389,11 +394,11 @@ function result(answer: string, iterations: number, limits: LimitGuard, edits: P
 }
 
 /** Out of turns: ask the model for its best final answer (plain text). */
-async function finalize(history: ChatMsg[], deps: EngineDeps, limits: LimitGuard): Promise<string> {
+async function finalize(history: ChatMsg[], model: Model<Api>, deps: EngineDeps, limits: LimitGuard): Promise<string> {
   const finalHistory = [...history];
   appendUserMessage(finalHistory, FINALIZE_PROMPT);
   const { text, usage } = await modelComplete(finalHistory, {
-    model: deps.model,
+    model,
     registry: deps.registry,
     reasoning: deps.config.smartReasoning,
     signal: deps.signal,

package/src/core/iteration.ts

@@ -17,6 +17,8 @@ export interface Turn {
   readonly results: readonly ReplResult[];
   readonly usage: Usage;
   readonly blocks: readonly string[];
+  /** Blocks not executed because an earlier block raised. */
+  readonly skippedBlocks: number;
 }
 
 export interface TurnDeps {
@@ -38,8 +40,12 @@ export async function runTurn(history: readonly ChatMsg[], sandbox: PythonSandbo
 
   const blocks = findReplBlocks(text);
   const results = new Array<ReplResult>(blocks.length);
+  let executed = 0;
   for (let i = 0; i < blocks.length; i++) {
     results[i] = await sandbox.exec(blocks[i]);
+    executed = i + 1;
+    if (results[i].raised) break;
   }
-  return { response: text, results, usage, blocks };
+  results.length = executed;
+  return { response: text, results, usage, blocks, skippedBlocks: blocks.length - executed };
 }

package/src/core/pipeline.ts

@@ -80,7 +80,7 @@ export function phaseGatePrompt(
 ): string | undefined {
   const turns = turnsInPhase(state, completedTurns);
   const phase = currentPhase(state);
-  if (turns >= PHASE_GATE_TURNS) {
+  if (turns >= PHASE_GATE_TURNS && turns % PHASE_GATE_TURNS === 0) {
     const next = nextPhase(phase);
     const hint = next
       ? ` Consider calling advance_phase("${next}") if your ${phase} work is complete.`

package/src/core/types.ts

@@ -48,6 +48,8 @@ export interface RlmConfig {
   maxErrors?: number;
   /** Append the orchestrator addendum to the system prompt. */
   orchestrator: boolean;
+  /** Enable the phase pipeline (advance_phase + stall nags) at depth 0. */
+  pipeline: boolean;
   /** Summarize the trajectory when it grows past the threshold (keeps the root window small). */
   compaction: boolean;
   /** Compact when estimated history tokens reach this fraction of the model's context window. */

package/src/index.ts

@@ -13,10 +13,12 @@ import { postRlmGuide } from "./ui/intro.ts";
 import { setRlmModeStatus } from "./ui/status.ts";
 import { SandboxManager } from "./sandbox/sandbox-manager.ts";
 import { packRepository, formatForLLM, serializeForSandbox } from "./context/repomix-context.ts";
-import { buildNativeSystemPrompt } from "./prompts/system.ts";
+import { buildNativeSystemPrompt, NATIVE_TURN_REMINDER } from "./prompts/system.ts";
+import { bashCommandFromInput, isFileReadingCommand, capToolResultText, BASH_BLOCK_REASON } from "./mode/native-guards.ts";
 import { errorMessage } from "./util/errors.ts";
 
 const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep"]));
+const CAPPED_RESULT_TOOLS = Object.freeze(new Set(["bash", "find", "ls"]));
 
 export default function rlmExtension(pi: ExtensionAPI): void {
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
@@ -27,6 +29,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     requestTimeoutMs: config.requestTimeoutMs,
     python: config.python,
     sandboxInitTimeoutMs: config.sandboxInitTimeoutMs,
+    maxPromptChars: config.maxPromptChars,
   });
   let packedContextText: string | undefined;
   let contextPackPromise: Promise<string | undefined> | undefined;
@@ -123,11 +126,16 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   let contextInjected = false;
   pi.on("context", async (event, ctx) => {
     const filtered = event.messages.filter(
-      (message) => !(message.role === "custom" && message.customType === "rlm-intro"),
+      (message) =>
+        !(message.role === "custom" && message.customType === "rlm-intro")
+        && !(message.role === "user" && typeof message.content === "string" && message.content === NATIVE_TURN_REMINDER),
     );
+    if (!controller.enabled) return { messages: filtered };
 
-    // Inject repository context as a compact listing (once per session, only when RLM is enabled)
-    if (controller.enabled && !contextInjected) {
+    type PiMessage = (typeof filtered)[number];
+
+    // Inject repository context as a compact listing (once per session)
+    if (!contextInjected) {
       const cwd = ctx.cwd ?? process.cwd();
       const contextText = await ensureRepositoryContext(cwd);
       if (contextText !== undefined) {
@@ -138,16 +146,21 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           "Chunk context via Python, delegate to llm_query. If credits exhausted → report and stop.",
           "",
         ].join("\n");
-        const contextMsg = {
+        filtered.unshift({
           role: "user" as const,
           content: instruction + contextText,
           timestamp: 0,
-        } as (typeof filtered)[number];
-
-        return { messages: [contextMsg, ...filtered] };
+        } as PiMessage);
       }
     }
 
+    // Per-turn last-position reminder (not persisted — context hook rebuilds every request)
+    filtered.push({
+      role: "user" as const,
+      content: NATIVE_TURN_REMINDER,
+      timestamp: 0,
+    } as PiMessage);
+
     return { messages: filtered };
   });
 
@@ -156,10 +169,10 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     return { action: "continue" };
   });
 
-  // ── Tool restriction: block analysis tools when RLM is ON ──
+  // ── Native mode restrictions: keep bulk file content out of root-model context ──
   // `edit`/`write` stay unblocked so the agent modifies files through Pi's native
-  // tool flow (visible to all plugins, +/- diff preview). Only read/grep are
-  // blocked — the repository is pre-loaded in the REPL `context` variable.
+  // tool flow (visible to all plugins, +/- diff preview). File reading/searching
+  // belongs in the REPL, and bash output is capped as a backstop.
   pi.on("tool_call", async (event) => {
     if (!controller.enabled) return;
     if (BLOCKED_NATIVE_TOOLS.has(event.toolName)) {
@@ -168,6 +181,23 @@ export default function rlmExtension(pi: ExtensionAPI): void {
         reason: "RLM mode active. Use repl({code}) to read files and search the repository — all files are pre-loaded in the REPL `context` variable. Use `edit`/`write` for file changes. If sub-LLM credits are exhausted, report to the user.",
       };
     }
+    const bashCommand = event.toolName === "bash" ? bashCommandFromInput(event.input) : undefined;
+    if (bashCommand !== undefined && isFileReadingCommand(bashCommand)) {
+      return { block: true, reason: BASH_BLOCK_REASON };
+    }
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (!controller.enabled || !CAPPED_RESULT_TOOLS.has(event.toolName)) return;
+    let changed = false;
+    const content = event.content.map((c) => {
+      if (c.type !== "text") return c;
+      const capped = capToolResultText(c.text);
+      if (capped === undefined) return c;
+      changed = true;
+      return { ...c, type: "text" as const, text: capped };
+    });
+    return changed ? { content } : undefined;
   });
 
   // ── Session shutdown: cleanup ──

package/src/mode/native-guards.ts

@@ -0,0 +1,92 @@
+/**
+ * native-guards — keeps bulk file content out of the root model's context in native RLM mode.
+ * Layer 1: block file-reading bash commands (steering — the redirect message re-educates).
+ * Layer 2: cap tool_result text AND repl() stdout (guarantee — bulk text physically cannot
+ *          reach the root model).
+ * Layer 3: nudge the model when a repl() call printed bulk text without delegating to a sub-LLM.
+ * This is token protection, not a security boundary: a determined model can still emit small reads.
+ */
+import { truncateOutput } from "../text/parsing.ts";
+
+/** Bash commands whose purpose is printing file content / searching — the REPL owns those jobs. */
+const READER_COMMANDS: ReadonlySet<string> = Object.freeze(new Set([
+  "cat", "sed", "head", "tail", "awk", "grep", "rg", "less", "more",
+  "cut", "nl", "tac", "strings", "xxd", "od", "column",
+]));
+
+/** Head token of the first pipe segment of each statement (split on ;, &&, ||, newline). */
+function statementHeads(command: string): string[] {
+  return command
+    .split(/(?:\|\||&&|;|\n)/)
+    .map((statement) => {
+      const firstSegment = statement.split("|", 1)[0] ?? "";
+      const tokens = firstSegment.trim().split(/\s+/);
+      // Skip env-var prefixes (FOO=bar cmd) and leading wrappers that don't change intent.
+      const head = tokens.find((t) => !t.includes("=") && t !== "sudo" && t !== "command" && t !== "env");
+      return head === undefined || head.length === 0 ? undefined : head.replace(/^.*\//, "");
+    })
+    .filter((h): h is string => h !== undefined);
+}
+
+/** Extract bash input.command from an unknown Pi tool input shape. */
+export function bashCommandFromInput(input: unknown): string | undefined {
+  if (typeof input !== "object" || input === null) return undefined;
+  const command: unknown = (input as Record<string, unknown>)["command"];
+  return typeof command === "string" ? command : undefined;
+}
+
+/** True when a statement starts with a file-reading command. */
+export function isFileReadingCommand(command: string): boolean {
+  return statementHeads(command).some((h) => READER_COMMANDS.has(h));
+}
+
+export const BASH_BLOCK_REASON =
+  "RLM mode: reading files via bash is blocked — that dumps file content into the root model's " +
+  "context. All files are pre-loaded in the REPL `context` variable: use repl({code}) with Python " +
+  "string/regex search, and delegate bulk analysis to llm_query / llm_query_batched / " +
+  "llm_query_chunked. bash is for RUNNING things (tests, builds, git).";
+
+/** Max chars of tool output forwarded to the root model (≈1K tokens). */
+export const TOOL_RESULT_CAP = 4_000;
+
+const CAP_NOTE =
+  `\n[RLM: tool output capped at ${TOOL_RESULT_CAP.toLocaleString()} chars to protect the root ` +
+  "model's context — route bulk text through repl() + llm_query_chunked / llm_query_batched.]";
+
+const REPL_CAP_NOTE =
+  `\n[RLM: repl() stdout capped at ${TOOL_RESULT_CAP.toLocaleString()} chars — printing bulk text ` +
+  "is useless. Keep results in REPL variables and delegate semantic reading to llm_query / " +
+  "llm_query_batched / llm_query_chunked.]";
+
+/** Shared truncation core. Returns undefined when under the cap (leave the text untouched). */
+function capText(text: string, note: string): string | undefined {
+  if (text.length <= TOOL_RESULT_CAP) return undefined;
+  return truncateOutput(text, TOOL_RESULT_CAP) + note;
+}
+
+/** Cap a generic tool result's text (bash / find / ls). */
+export function capToolResultText(text: string): string | undefined {
+  return capText(text, CAP_NOTE);
+}
+
+/** Cap the model-visible portion of a repl() result (stdout / answerContent). */
+export function capReplResultText(text: string): string | undefined {
+  return capText(text, REPL_CAP_NOTE);
+}
+
+/** Stdout size above which a repl() call with zero sub-LLM calls earns a delegation nudge. */
+export const NUDGE_STDOUT_CHARS = 2_000;
+
+/**
+ * One-line corrective nudge when a repl() call printed bulk text without delegating.
+ * Returns undefined when behavior was fine (small output, or a delegation happened).
+ * Takes primitives (no RlmSubcall dependency) so the tool layer owns the detection.
+ */
+export function replDelegationNudge(stdoutChars: number, delegated: boolean): string | undefined {
+  if (delegated || stdoutChars <= NUDGE_STDOUT_CHARS) return undefined;
+  return (
+    `\n[RLM: this repl() printed ${stdoutChars.toLocaleString()} chars with 0 sub-LLM calls — ` +
+    "delegate semantic reading via llm_query / llm_query_batched / llm_query_chunked instead of " +
+    "reading output yourself.]"
+  );
+}