@oisin-ee/oisinpi 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @oisin-ee/oisinpi
 
+## 0.11.0
+
+### Patch Changes
+
+- Updated dependencies [[`49b00f1`](https://github.com/oisin-ee/oisinpi/commit/49b00f117d4d64a51cdb2b502ac505a99ffe83dc), [`0e37d82`](https://github.com/oisin-ee/oisinpi/commit/0e37d8259d4a7cb4cffbeccfce2a36caa0274b6e)]:
+  - @oisin-ee/pi-guardrails@0.11.0
+  - @oisin-ee/pi-todo@0.11.0
+  - @oisin-ee/pi-prewalk@0.11.0
+  - @oisin-ee/pi-tiers@0.11.0
+
 ## 0.10.2
 
 ### Patch Changes

package/node_modules/@oisin-ee/pi-guardrails/README.md

@@ -13,6 +13,44 @@ Agent guardrails for [pi](https://pi.dev), Claude Code, and Codex. One set of po
 In pi, it also fills a missing shell timeout (120 s) and blocks one above 10 minutes, naming each tool's unit.
 Shell text is parsed with `shfmt`, which must be on `PATH`. A command that cannot be parsed is blocked.
 
+## Read-only planning models
+
+A planning model (`tier/plan-claude` or `tier/plan-gpt`) may only read. The guardrails read the model of
+each tool call from the session context, so the rule follows a model switch.
+
+A planning model may call:
+
+- the read tools: `read`, `ls`, `find`, `grep`, `hypa_read`, `hypa_ls`, `hypa_find`, `hypa_grep`,
+  `web_search`, `web_fetch`, `lsp_diagnostics`, `ctx_search`, `ctx_stats`, the `hindsight` read tools, and
+  the `codebase_memory` read tools;
+- the workflow controls: `todo`, `ask`, `interview`, `tool_search`, and `codemode`;
+- the Dogsled tools `read`, `status`, `inbox`, `send`, and `done`, and a `spawn` of a bound unit by its id;
+- a shell read: `pwd`, `ls`, `rg`, `grep`, `find` without `-exec`, `-delete`, or `-fprint`, and `git status`,
+  `git diff`, `git log`, `git show`, and `git rev-parse` with read-only options.
+
+Every trusted name is exact. A tool whose name only resembles a trusted one, such as `dangerous_read` or
+`mcp__untrusted__read`, is blocked. The same holds for a command: only `pwd`, `ls`, `rg`, `grep`, `find`,
+and `git` are reads, so `./ls` and `/repo/tools/git status` are blocked.
+
+The shell check uses the `shfmt` syntax tree, so a redirect, an assignment, a substitution, a glob, a
+dollar-quoted word, or a background call is blocked even when the command itself reads. `git diff`,
+`git log -p`, and `git show` must carry `--no-ext-diff --no-textconv`, because a diff driver or a
+textconv filter can run a program. A word after `--` is a path, so it cannot carry those flags.
+
+Each command has its own option grammar. An option that needs a value must have one, an option that
+accepts only some values accepts only those, and a `find` option that changes the filesystem is blocked.
+
+A `hypa_shell` call with `raw: true` runs without a shell, so the runner splits the command on
+whitespace. The policy classifies those words, so a flag hidden in a quoted argument cannot slip through.
+
+Every command of a `ctx_batch_execute` call is checked on its own. A malformed entry is blocked.
+
+A nested call that the policy cannot inspect, such as a malformed codemode envelope or a call deeper
+than eight levels, is blocked for a planning model.
+
+Every other tool, including `write`, `edit`, and any command that changes the repository or the system,
+is blocked for a planning model. Other models keep the full policy set.
+
 ## pi
 
 ```bash

package/node_modules/@oisin-ee/pi-guardrails/dist/shell-parser.js

@@ -95,7 +95,7 @@ pipelineStages = (stmt, source) => {
         }
     };
     visit(tree);
-    return { calls, guards };
+    return { tree, calls, guards };
 }, parsedOf = (command) => {
     if (cache.command !== command || cache.parsed === undefined) {
         cache.parsed = parse(command);
@@ -117,4 +117,67 @@ shellCalls = (command) => parsedOf(command).calls.map((words) => [...words]),
  * @returns {(string[][] | null)[]} One guard per call.
  */
 shellCallGuards = (command) => parsedOf(command).guards.map((stages) => stages?.map((words) => [...words]) ?? null);
-export { shellCallGuards, shellCalls };
+/**
+ * Whether a literal contains a glob character that the shell would expand. An
+ * escaped character is literal, so it does not expand.
+ * @param {string} value The raw literal text.
+ * @returns {boolean} True for an active glob character.
+ */
+function hasActiveGlob(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index] ?? "";
+        if (!"*?[]{}".includes(character)) {
+            continue;
+        }
+        let backslashes = 0;
+        for (let before = index - 1; before >= 0 && value[before] === "\\"; before -= 1) {
+            backslashes += 1;
+        }
+        if (backslashes % 2 === 0) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Returns literal calls only when the complete AST has read-only shell syntax.
+ * @param {string} command Shell text.
+ * @returns {string[][] | null} Literal argv, or null for unsupported syntax.
+ */
+function literalShellCalls(command) {
+    const parsed = parsedOf(command), allowed = new Set([
+        "File",
+        "Stmt",
+        "CallExpr",
+        "Word",
+        "Lit",
+        "SglQuoted",
+        "DblQuoted",
+        "BinaryCmd",
+    ]), safe = (node, quoted = false) => {
+        if (Array.isArray(node)) {
+            return node.every((item) => safe(item, quoted));
+        }
+        if (!isNode(node)) {
+            return true;
+        }
+        if (node.Type !== undefined && !allowed.has(node.Type)) {
+            return false;
+        }
+        if (node.Dollar === true ||
+            node.Background === true ||
+            (node.Redirs ?? []).length > 0 ||
+            (node.Assigns ?? []).length > 0 ||
+            (node.Type === "CallExpr" && (node.Args ?? []).length === 0) ||
+            (node.Type === "BinaryCmd" && !["&&", "||", "|"].includes(node.Op ?? "")) ||
+            (node.Type === "Lit" && !quoted && hasActiveGlob(node.Value ?? "")) ||
+            (node.Type === "Lit" && !quoted && (node.Value ?? "").startsWith("~"))) {
+            return false;
+        }
+        return Object.values(node).every((value) => safe(value, quoted || node.Type === "DblQuoted"));
+    };
+    return safe(parsed.tree) && parsed.calls.length > 0
+        ? parsed.calls.map((words) => [...words])
+        : null;
+}
+export { literalShellCalls, shellCallGuards, shellCalls };

package/node_modules/@oisin-ee/pi-guardrails/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-guardrails",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Agent guardrails for pi, Claude Code, and Codex: Git safety, no waiting, no typing into other agents, GitOps-only clusters.",
   "keywords": [
     "claude-code",

package/node_modules/@oisin-ee/pi-guardrails/src/pi/index.ts

@@ -9,6 +9,7 @@ import {
   commandsFromToolInput,
 } from "./tool-inputs.ts";
 import { codeWaitViolation, enforceTimeout } from "./tool-timeouts.ts";
+import { isPlanningModel, planningToolReason } from "./planning-policy.ts";
 import { classifyEdits, editInputsFromPayload } from "../policies/edit.ts";
 import { SHELL_CLASSIFIERS } from "../policies/shell.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -23,6 +24,12 @@ interface ToolCall {
   readonly input: Record<string, unknown>;
 }
 
+/** The model of the session, as the context reports it. */
+interface CallModel {
+  readonly provider?: string;
+  readonly id?: string;
+}
+
 // A codemode script's nested calls nest at most this deep before the gate stops looking.
 const MAX_NESTING = 8,
   /**
@@ -49,31 +56,81 @@ const MAX_NESTING = 8,
     ),
   editViolation = (call: ToolCall, cwd: string): string | null =>
     classifyEdits(editInputsFromPayload({ tool_input: call.input, tool_name: call.toolName }), cwd),
-  nestedCalls = (input: Readonly<Record<string, unknown>>): ToolCall[] => {
+  /**
+   * The nested calls of a codemode input. A malformed envelope is a failure
+   * for a planning model, so it is reported rather than skipped.
+   * @param {Readonly<Record<string, unknown>>} input The tool input.
+   * @returns {{ calls: ToolCall[]; malformed: boolean }} The calls and the
+   *   state of the envelope.
+   */
+  nestedCalls = (
+    input: Readonly<Record<string, unknown>>,
+  ): { calls: ToolCall[]; malformed: boolean } => {
     const uses = input["tool_uses"];
+    if (uses === undefined) {
+      return { calls: [], malformed: false };
+    }
     if (!Array.isArray(uses)) {
-      return [];
+      return { calls: [], malformed: true };
     }
-    return uses.filter(isRecord).map((use) => ({
-      input: isRecord(use["parameters"]) ? use["parameters"] : {},
-      toolName: typeof use["recipient_name"] === "string" ? use["recipient_name"] : "",
-    }));
+    const calls: ToolCall[] = [];
+    let malformed = false;
+    for (const use of uses) {
+      if (!isRecord(use)) {
+        malformed = true;
+        continue;
+      }
+      const toolName = use["recipient_name"];
+      const parameters = use["parameters"];
+      if (typeof toolName !== "string") {
+        malformed = true;
+      }
+      if (parameters !== undefined && !isRecord(parameters)) {
+        malformed = true;
+      }
+      calls.push({
+        input: isRecord(parameters) ? parameters : {},
+        toolName: typeof toolName === "string" ? toolName : "",
+      });
+    }
+    return { calls, malformed };
   },
-  toolViolation = (event: ToolCall, cwd: string, depth = 0): string | null => {
+  toolViolation = (
+    event: ToolCall,
+    cwd: string,
+    model: CallModel | undefined,
+    depth = 0,
+  ): string | null => {
+    const planning = isPlanningModel(model);
     if (depth > MAX_NESTING) {
-      return null;
+      // A planning model fails closed: a call it cannot inspect is a call it
+      // cannot allow. Other models keep the old behaviour.
+      return planning
+        ? `planning-readonly: blocked a nested call deeper than ${MAX_NESTING} levels. A planning ` +
+            "model may only run calls it can inspect."
+        : null;
     }
     const call = { input: event.input, toolName: canonicalToolName(event.toolName) },
       own =
         enforceTimeout(call.toolName, call.input) ??
         codeWaitViolation(call.toolName, call.input) ??
+        // The planning policy authorizes the raw event name, so a tool that
+        // only ends with a trusted name is not that tool.
+        (planning ? planningToolReason(event.toolName, event.input) : null) ??
         (SHELL_TOOL_NAMES.has(call.toolName) ? shellViolation(call, cwd) : null) ??
         (EDIT_TOOL_NAMES.has(call.toolName) ? editViolation(call, cwd) : null);
     if (own !== null) {
       return own;
     }
-    for (const nested of nestedCalls(call.input)) {
-      const message = toolViolation(nested, cwd, depth + 1);
+    const nested = nestedCalls(call.input);
+    if (nested.malformed && planning) {
+      return (
+        "planning-readonly: blocked a nested call with a malformed envelope. A planning model " +
+        "may only run calls it can inspect."
+      );
+    }
+    for (const child of nested.calls) {
+      const message = toolViolation(child, cwd, model, depth + 1);
       if (message !== null) {
         return message;
       }
@@ -89,7 +146,7 @@ const MAX_NESTING = 8,
 export default function piGuardrails(pi: GuardrailsAPI): void {
   pi.on("tool_call", (event, ctx) => {
     try {
-      const message = toolViolation(event, ctx.cwd);
+      const message = toolViolation(event, ctx.cwd, ctx.model);
       return message === null ? undefined : { block: true, reason: message };
     } catch (error) {
       return { block: true, reason: error instanceof Error ? error.message : String(error) };