@oisin-ee/oisinpi 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @oisin-ee/oisinpi
 
+## 0.12.0
+
+### Patch Changes
+
+- Updated dependencies [[`7fcdc45`](https://github.com/oisin-ee/oisinpi/commit/7fcdc45f08c065faf38c3841c0b2d2133ad9322f)]:
+  - @oisin-ee/pi-todo@0.12.0
+  - @oisin-ee/pi-guardrails@0.12.0
+  - @oisin-ee/pi-prewalk@0.12.0
+  - @oisin-ee/pi-tiers@0.12.0
+
+## 0.11.1
+
+### Patch Changes
+
+- Updated dependencies [[`f1837f2`](https://github.com/oisin-ee/oisinpi/commit/f1837f28bc25fb00feebf7c47509db9bbd3b897c)]:
+  - @oisin-ee/pi-guardrails@0.11.1
+  - @oisin-ee/pi-prewalk@0.11.1
+  - @oisin-ee/pi-tiers@0.11.1
+  - @oisin-ee/pi-todo@0.11.1
+
 ## 0.11.0
 
 ### Patch Changes

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

@@ -13,43 +13,13 @@ 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
+## 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.
+The guardrails do not restrict a model by its identity. The planning selections `tier/plan-claude` and
+`tier/plan-gpt` keep the full policy set: a planning model may run Git commands, write and edit files,
+and use the workflow tools.
 
-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.
+Planning restrictions belong to Dogsled plan mode, which blocks writes outside markdown files while planning.
 
 ## pi
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-guardrails",
-  "version": "0.11.0",
+  "version": "0.12.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,7 +9,6 @@ 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";
@@ -24,12 +23,6 @@ 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,
   /**
@@ -57,80 +50,44 @@ const MAX_NESTING = 8,
   editViolation = (call: ToolCall, cwd: string): string | null =>
     classifyEdits(editInputsFromPayload({ tool_input: call.input, tool_name: call.toolName }), cwd),
   /**
-   * The nested calls of a codemode input. A malformed envelope is a failure
-   * for a planning model, so it is reported rather than skipped.
+   * The nested calls of a codemode input.
    * @param {Readonly<Record<string, unknown>>} input The tool input.
-   * @returns {{ calls: ToolCall[]; malformed: boolean }} The calls and the
-   *   state of the envelope.
+   * @returns {readonly ToolCall[]} The calls of the envelope.
    */
-  nestedCalls = (
-    input: Readonly<Record<string, unknown>>,
-  ): { calls: ToolCall[]; malformed: boolean } => {
+  nestedCalls = (input: Readonly<Record<string, unknown>>): readonly ToolCall[] => {
     const uses = input["tool_uses"];
-    if (uses === undefined) {
-      return { calls: [], malformed: false };
-    }
     if (!Array.isArray(uses)) {
-      return { calls: [], malformed: true };
+      return [];
     }
     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 };
+    return calls;
   },
-  toolViolation = (
-    event: ToolCall,
-    cwd: string,
-    model: CallModel | undefined,
-    depth = 0,
-  ): string | null => {
-    const planning = isPlanningModel(model);
+  toolViolation = (event: ToolCall, cwd: string, depth = 0): string | null => {
     if (depth > MAX_NESTING) {
-      // 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;
+      return 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;
     }
-    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);
+    for (const child of nestedCalls(call.input)) {
+      const message = toolViolation(child, cwd, depth + 1);
       if (message !== null) {
         return message;
       }
@@ -146,7 +103,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, ctx.model);
+      const message = toolViolation(event, ctx.cwd);
       return message === null ? undefined : { block: true, reason: message };
     } catch (error) {
       return { block: true, reason: error instanceof Error ? error.message : String(error) };

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

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-prewalk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A one-shot planner-to-executor handoff for pi, with branch-backed Rust rules.",
   "keywords": [
     "pi-extension",

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

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-tiers",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Sticky virtual model tiers with quota-aware recovery for pi.",
   "keywords": [
     "pi-extension",

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

@@ -105,24 +105,14 @@ Version 3 adds `display.sections` to the snapshot: four typed status groups (`in
 Pi-todo does not answer version 2 requests.
 Incompatible versions leave the standalone widget available. Rendering failures restore it without changing saved tasks.
 
-## Plannotator plans
+## Dogsled plans
 
-With Plannotator external execution, pi-todo continues approved plans in the same session.
-Add this setting to `~/.pi/agent/plannotator.json`:
-
-```json
-{
-  "executionMode": "external"
-}
-```
+Dogsled plan mode (`/plan` and `submit_plan`) emits `dogsled:plan-approved` when the user approves a plan.
+Pi-todo continues the approved plan in the same session. No setting is needed.
 
 After approval, the agent reads the current todo list and adds the remaining approved work before implementation.
 It preserves unrelated tasks and completed progress. Free-form plans do not need a special checklist format.
 The todo tool owns progress, persistence, reminders, and the shared work display.
-Plannotator returns to idle and does not maintain a second checklist or require `[DONE:n]` markers.
-
-This integration uses the supported `plannotator:plan-approved` event, verified with Plannotator `0.28.19`.
-It does not import Plannotator internals or change its code.
 Malformed events, a different working directory, or another owner of the `todo` tool stop the handoff with an error.
 
 ## Reminder

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

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-todo",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A todo tool for pi with a Rust core: one active task, state on the session branch.",
   "keywords": [
     "pi-extension",

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

@@ -1,6 +1,6 @@
 import { ownsTodo, settle } from "./lifecycle.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { PlannotatorHandoff } from "./plannotator.ts";
+import { PlanApprovedHandoff } from "./plan-approved.ts";
 import { TaskProvider } from "./provider.ts";
 import { TodoPresentation } from "./presentation.ts";
 import { TodoWork } from "./work.ts";
@@ -30,7 +30,7 @@ type TodoAPI = WorkHost &
  * @param {TodoAPI} pi The extension API methods used here.
  */
 export default function piTodo(pi: TodoAPI): void {
-  const handoff = new PlannotatorHandoff(pi),
+  const handoff = new PlanApprovedHandoff(pi),
     presentation = new TodoPresentation(),
     work = new TodoWork(pi, presentation),
     provider = new TaskProvider(pi),

package/node_modules/@oisin-ee/pi-todo/src/{plannotator.ts → plan-approved.ts}

@@ -4,7 +4,7 @@ import type { WorkHost } from "./work.ts";
 import { ownsTodo } from "./lifecycle.ts";
 import { workUnitGuidance } from "./guidance.ts";
 
-/** The supported Plannotator external-execution event. */
+/** The supported Dogsled plan approval event. */
 interface ApprovedPlan {
   readonly cwd: string;
   readonly planFilePath: string;
@@ -39,8 +39,8 @@ const isApprovedPlan = (value: unknown): value is ApprovedPlan =>
    */
   continuation = (plan: ApprovedPlan): string =>
     [
-      "The user approved this plan in Plannotator. Continue execution in this session.",
-      "Use the todo tool as the only task tracker. Do not maintain Plannotator [DONE:n] markers.",
+      "The user approved this plan in Dogsled plan mode. Continue execution in this session.",
+      "Use the todo tool as the only task tracker.",
       "First call todo with op=view to inspect the current branch list.",
       "Before implementation, represent remaining outcomes with optional bounded subtasks in that list. Use parent plus exact task for child operations.",
       workUnitGuidance,
@@ -58,7 +58,7 @@ const isApprovedPlan = (value: unknown): value is ApprovedPlan =>
     ].join("\n");
 
 /** Owns the approval subscription, never the todo list or execution progress. */
-class PlannotatorHandoff {
+class PlanApprovedHandoff {
   readonly #host: PlanHost;
   #unsubscribe: (() => void) | undefined;
 
@@ -76,26 +76,23 @@ class PlannotatorHandoff {
    */
   public start(ctx: PlanContext): void {
     this.stop();
-    this.#unsubscribe = this.#host.events.on(
-      "plannotator:plan-approved",
-      (value: unknown): void => {
-        if (!isApprovedPlan(value)) {
-          ctx.ui.notify("pi-todo: Invalid Plannotator approval. No execution started.", "error");
-        } else if (value.cwd !== ctx.cwd) {
-          ctx.ui.notify(
-            "pi-todo: The approved plan belongs to another working directory. No execution started.",
-            "error",
-          );
-        } else if (ownsTodo(this.#host)) {
-          this.#host.sendMessage(
-            { content: continuation(value), customType: "todo-plan-approved", display: true },
-            { deliverAs: "followUp", triggerTurn: true },
-          );
-        } else {
-          ctx.ui.notify("pi-todo: Another extension owns todo. No execution started.", "error");
-        }
-      },
-    );
+    this.#unsubscribe = this.#host.events.on("dogsled:plan-approved", (value: unknown): void => {
+      if (!isApprovedPlan(value)) {
+        ctx.ui.notify("pi-todo: Invalid Dogsled plan approval. No execution started.", "error");
+      } else if (value.cwd !== ctx.cwd) {
+        ctx.ui.notify(
+          "pi-todo: The approved plan belongs to another working directory. No execution started.",
+          "error",
+        );
+      } else if (ownsTodo(this.#host)) {
+        this.#host.sendMessage(
+          { content: continuation(value), customType: "todo-plan-approved", display: true },
+          { deliverAs: "followUp", triggerTurn: true },
+        );
+      } else {
+        ctx.ui.notify("pi-todo: Another extension owns todo. No execution started.", "error");
+      }
+    });
   }
 
   /** Removes the previous session's listener before replacement or shutdown. */
@@ -105,5 +102,5 @@ class PlannotatorHandoff {
   }
 }
 
-export { PlannotatorHandoff };
+export { PlanApprovedHandoff };
 export type { PlanContext, PlanHost };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/oisinpi",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Oisin's pi packages in one install: prewalk, todo, tiers, and guardrails.",
   "keywords": [
     "guardrails",
@@ -17,10 +17,10 @@
   },
   "type": "module",
   "dependencies": {
-    "@oisin-ee/pi-guardrails": "0.11.0",
-    "@oisin-ee/pi-prewalk": "0.11.0",
-    "@oisin-ee/pi-tiers": "0.11.0",
-    "@oisin-ee/pi-todo": "0.11.0"
+    "@oisin-ee/pi-guardrails": "0.12.0",
+    "@oisin-ee/pi-prewalk": "0.12.0",
+    "@oisin-ee/pi-tiers": "0.12.0",
+    "@oisin-ee/pi-todo": "0.12.0"
   },
   "bundleDependencies": [
     "@oisin-ee/pi-guardrails",

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

@@ -1,763 +0,0 @@
-/*
- * The read-only policy for planning models. A planning model may read the
- * repository and the tools that report on it; it may not change anything.
- *
- * The model identity comes from the context of the call, read fresh for each
- * tool call: the session can switch models between calls.
- *
- * Every trusted name here is exact. A tool whose name only ends with a trusted
- * name, such as `dangerous_read` or `mcp__untrusted__read`, is a different
- * tool, so the policy blocks it. The same rule holds for the executable of a
- * read command: only `pwd`, `ls`, `rg`, `grep`, `find`, and `git` are reads,
- * not every path whose basename is one of them.
- */
-import { isRecord } from "../common.ts";
-import type { Command } from "../common.ts";
-import { literalShellCalls } from "../shell-parser.ts";
-
-/** The provider of the planning models. */
-const PLANNING_PROVIDER = "tier",
-  /** The model ids that plan. */
-  PLANNING_MODEL_IDS: ReadonlySet<string> = new Set(["plan-claude", "plan-gpt"]);
-
-/** The model of a tool call, as the context reports it. */
-interface ModelIdentity {
-  readonly provider?: string;
-  readonly id?: string;
-}
-
-/**
- * Whether the model of a tool call is a planning model.
- * @param {ModelIdentity | undefined} model The current model.
- * @returns {boolean} True for a planning model.
- */
-function isPlanningModel(model: ModelIdentity | undefined): boolean {
-  return (
-    model?.provider === PLANNING_PROVIDER &&
-    model.id !== undefined &&
-    PLANNING_MODEL_IDS.has(model.id)
-  );
-}
-
-/** The tools that only report on the repository, by exact name. */
-const READ_TOOLS: ReadonlySet<string> = new Set([
-    "read",
-    "ls",
-    "find",
-    "grep",
-    "hypa_read",
-    "hypa_ls",
-    "hypa_find",
-    "hypa_grep",
-    "web_search",
-    "web_fetch",
-    "lsp_diagnostics",
-    "ctx_search",
-    "ctx_stats",
-    "mcp__context_mode__ctx_search",
-    "mcp__context_mode__ctx_stats",
-    "hindsight_search_knowledge_pages",
-    "hindsight_list_knowledge_pages",
-    "hindsight_read_knowledge_page",
-    "hindsight_reflect",
-    "hindsight_sync_status",
-    "hindsight_diagnose",
-    "mcp__codebase_memory__search_graph",
-    "mcp__codebase_memory__get_code_snippet",
-    "mcp__codebase_memory__trace_path",
-    "mcp__codebase_memory__detect_changes",
-  ]),
-  /** The workflow controls a planning model keeps. */
-  WORKFLOW_TOOLS: ReadonlySet<string> = new Set([
-    "todo",
-    "ask",
-    "interview",
-    "tool_search",
-    "codemode",
-  ]),
-  /** The Dogsled tools a planning model may use, by full name. */
-  DOGSLED_TOOLS: ReadonlySet<string> = new Set([
-    "mcp__dogsled__read",
-    "mcp__dogsled__status",
-    "mcp__dogsled__inbox",
-    "mcp__dogsled__send",
-    "mcp__dogsled__done",
-  ]),
-  /** The shell tools a planning model may use, by exact name. */
-  SHELL_TOOLS: ReadonlySet<string> = new Set([
-    "bash",
-    "shell",
-    "hypa_shell",
-    "ctx_execute",
-    "ctx_batch_execute",
-    "ctx_execute_file",
-    "mcp__context_mode__ctx_execute",
-    "mcp__context_mode__ctx_batch_execute",
-    "mcp__context_mode__ctx_execute_file",
-    "mcp__gateway__keen_bash",
-  ]),
-  /** The shell tools that take a list of commands. */
-  BATCH_SHELL_TOOLS: ReadonlySet<string> = new Set([
-    "ctx_batch_execute",
-    "mcp__context_mode__ctx_batch_execute",
-  ]),
-  /** The shell tools that take a script in a language. */
-  CODE_SHELL_TOOLS: ReadonlySet<string> = new Set([
-    "ctx_execute",
-    "ctx_execute_file",
-    "mcp__context_mode__ctx_execute",
-    "mcp__context_mode__ctx_execute_file",
-  ]);
-
-const READ_MESSAGE =
-  "planning-readonly: a planning model may only read. Allowed 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 and codebase_memory read tools, todo, ask, interview, tool_search, " +
-  "codemode, and the Dogsled read/status/inbox/send/done tools. A planning model may not write, " +
-  "edit, or run commands that change anything.";
-
-/**
- * The message for a tool a planning model may not call.
- * @param {string} toolName The tool name.
- * @returns {string} The block message.
- */
-function toolMessage(toolName: string): string {
-  return `${READ_MESSAGE} Blocked tool: ${toolName}.`;
-}
-
-/**
- * Whether a tool call is a bound Dogsled spawn, which a planning model may use
- * to start a bound unit.
- * @param {Readonly<Record<string, unknown>>} input The tool input.
- * @returns {boolean} True for a spawn with a unit id.
- */
-function isBoundSpawn(input: Readonly<Record<string, unknown>>): boolean {
-  const unit = input["unit"];
-  if (!isRecord(unit)) {
-    return false;
-  }
-  const id = unit["id"];
-  return typeof id === "string" && id.length > 0;
-}
-
-/**
- * The value of a text field.
- * @param {unknown} value The field value.
- * @returns {string | undefined} The text, when the value is a string.
- */
-function textOf(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}
-
-/**
- * The command text of a shell tool input.
- * @param {Readonly<Record<string, unknown>>} input The tool input.
- * @returns {string | null} The command, or null when the input carries none.
- */
-function commandTextOf(input: Readonly<Record<string, unknown>>): string | null {
-  return textOf(input["command"]) ?? textOf(input["cmd"]) ?? textOf(input["commandText"]) ?? null;
-}
-
-/**
- * The argument list of a raw command. The runner splits a raw command on
- * whitespace and does not parse quotes, so the argv holds the words between
- * the spaces.
- * @param {string} text The raw command.
- * @returns {string[]} The words of the argument list.
- */
-function rawWords(text: string): string[] {
-  return text.split(/\s+/u).filter((word) => word.length > 0);
-}
-
-/** The options of a command, and the values its options accept. */
-interface OptionTables {
-  /** The options that take no value. */
-  readonly flags: ReadonlySet<string>;
-  /** The options that take a value. */
-  readonly valueFlags: ReadonlySet<string>;
-  /** The values each option accepts, when it accepts only some. */
-  readonly enumValues: Readonly<Record<string, ReadonlySet<string>>>;
-}
-
-/** The options of each read command that stay read-only. */
-const READ_COMMAND_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
-    pwd: new Set(["-L", "-P"]),
-    ls: new Set([
-      "-1",
-      "-a",
-      "-A",
-      "-d",
-      "-F",
-      "-h",
-      "-l",
-      "-r",
-      "-R",
-      "-S",
-      "-t",
-      "--all",
-      "--almost-all",
-      "--human-readable",
-      "--long",
-    ]),
-    rg: new Set([
-      "-c",
-      "-C",
-      "-e",
-      "-F",
-      "-g",
-      "-i",
-      "-l",
-      "-n",
-      "-r",
-      "-s",
-      "-v",
-      "-w",
-      "--count",
-      "--files-with-matches",
-      "--fixed-strings",
-      "--ignore-case",
-      "--line-number",
-      "--no-heading",
-      "--no-ignore-case",
-      "--word-regexp",
-    ]),
-    grep: new Set([
-      "-A",
-      "-B",
-      "-C",
-      "-c",
-      "-e",
-      "-E",
-      "-F",
-      "-i",
-      "-l",
-      "-n",
-      "-o",
-      "-r",
-      "-s",
-      "-v",
-      "-w",
-      "--count",
-      "--files-with-matches",
-      "--ignore-case",
-      "--line-number",
-      "--recursive",
-      "--word-regexp",
-    ]),
-    find: new Set([
-      "-E",
-      "-H",
-      "-L",
-      "-name",
-      "-iname",
-      "-iregex",
-      "-maxdepth",
-      "-mindepth",
-      "-newer",
-      "-not",
-      "-path",
-      "-print",
-      "-printf",
-      "-regex",
-      "-type",
-    ]),
-  },
-  /** The options that take a value. */
-  READ_COMMAND_VALUE_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
-    ls: new Set(["--color", "--time-style"]),
-    rg: new Set(["-C", "-e", "-g", "--color", "--context", "--glob", "--max-count"]),
-    grep: new Set(["-A", "-B", "-C", "-e", "--color", "--context"]),
-    find: new Set([
-      "-name",
-      "-iname",
-      "-iregex",
-      "-maxdepth",
-      "-mindepth",
-      "-newer",
-      "-path",
-      "-regex",
-      "-type",
-    ]),
-  },
-  /** The values each read option accepts, when it accepts only some. */
-  READ_COMMAND_ENUM_VALUES: Readonly<
-    Record<string, Readonly<Record<string, ReadonlySet<string>>>>
-  > = {
-    ls: {
-      "--color": new Set(["always", "auto", "never"]),
-      "--time-style": new Set(["long-iso"]),
-    },
-    rg: { "--color": new Set(["never"]) },
-    grep: { "--color": new Set(["never"]) },
-  },
-  /** The find options that change the filesystem. */
-  FIND_MUTATIONS: ReadonlySet<string> = new Set([
-    "-delete",
-    "-exec",
-    "-execdir",
-    "-fls",
-    "-fprint",
-    "-fprintf",
-    "-ok",
-    "-okdir",
-  ]),
-  /** The executables a planning model may run. */
-  READ_COMMANDS: ReadonlySet<string> = new Set(["pwd", "ls", "rg", "grep", "find", "git"]),
-  /** The git subcommands a planning model may run. */
-  GIT_READ_SUBCOMMANDS: ReadonlySet<string> = new Set([
-    "diff",
-    "log",
-    "rev-parse",
-    "show",
-    "status",
-  ]),
-  /** The git global options a planning model may use. */
-  GIT_GLOBAL_FLAGS: ReadonlySet<string> = new Set(["--no-pager", "--literal-pathspecs"]),
-  /** The git global options that take a value. */
-  GIT_GLOBAL_VALUE_FLAGS: ReadonlySet<string> = new Set(["-C", "--git-dir", "--work-tree"]),
-  /** The git options of each read subcommand. */
-  GIT_SUBCOMMAND_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
-    status: new Set([
-      "--branch",
-      "--ignored",
-      "--long",
-      "--porcelain",
-      "--short",
-      "-b",
-      "-l",
-      "-s",
-      "-uno",
-      "-unormal",
-      "-uall",
-    ]),
-    diff: new Set([
-      "--cached",
-      "--name-only",
-      "--name-status",
-      "--no-ext-diff",
-      "--no-textconv",
-      "--stat",
-      "--staged",
-      "-M",
-    ]),
-    log: new Set([
-      "--abbrev-commit",
-      "--decorate",
-      "--graph",
-      "--no-color",
-      "--no-ext-diff",
-      "--no-textconv",
-      "--oneline",
-      "--name-only",
-      "--name-status",
-      "--patch",
-      "--stat",
-      "-p",
-    ]),
-    show: new Set([
-      "--abbrev-commit",
-      "--no-color",
-      "--no-ext-diff",
-      "--no-textconv",
-      "--oneline",
-      "--stat",
-    ]),
-    "rev-parse": new Set([
-      "--abbrev-ref",
-      "--git-dir",
-      "--is-inside-work-tree",
-      "--quiet",
-      "--short",
-      "--show-prefix",
-      "--show-toplevel",
-      "--symbolic-full-name",
-    ]),
-  },
-  /** The git options that take a value. */
-  GIT_SUBCOMMAND_VALUE_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
-    status: new Set(["--untracked-files"]),
-    diff: new Set(["--color"]),
-    log: new Set(["-n", "--max-count", "--color"]),
-    show: new Set(["--color"]),
-    "rev-parse": new Set(["--verify"]),
-  },
-  /** The values each git option accepts, when it accepts only some. */
-  GIT_SUBCOMMAND_ENUM_VALUES: Readonly<
-    Record<string, Readonly<Record<string, ReadonlySet<string>>>>
-  > = {
-    status: { "--untracked-files": new Set(["all", "normal", "no"]) },
-    diff: { "--color": new Set(["never"]) },
-    log: { "--color": new Set(["never"]) },
-    show: { "--color": new Set(["never"]) },
-  };
-
-const EXT_DIFF_MESSAGE =
-  "planning-readonly: blocked a git command that can run an external diff driver or a textconv " +
-  "filter. Add --no-ext-diff --no-textconv and run it again.";
-
-/**
- * Whether a word is an option of a command, so it cannot be the value of the
- * option before it.
- * @param {string} word The word.
- * @param {OptionTables} tables The options of the command.
- * @returns {boolean} True for an option word.
- */
-function isOptionWord(word: string, tables: OptionTables): boolean {
-  if (!word.startsWith("-") || word === "-") {
-    return false;
-  }
-  if (tables.flags.has(word) || tables.valueFlags.has(word)) {
-    return true;
-  }
-  if (word.startsWith("--") && word.includes("=")) {
-    const name = word.slice(0, word.indexOf("="));
-    return tables.flags.has(name) || tables.valueFlags.has(name);
-  }
-  if (word.startsWith("--")) {
-    return false;
-  }
-  for (const letter of word.slice(1)) {
-    if (!tables.flags.has(`-${letter}`) && !tables.valueFlags.has(`-${letter}`)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * The block message for an option a planning model may not use.
- * @param {string} detail The option and its value, for the message.
- * @returns {string} The block message.
- */
-function blockedOption(detail: string): string {
-  return `planning-readonly: blocked ${detail}. A planning model may use only read-only options.`;
-}
-
-/**
- * The reason an option word is not allowed, or null when it is.
- * @param {readonly string[]} words The words of the call.
- * @param {number} index The index of the option.
- * @param {OptionTables} tables The options of the command.
- * @param {string} label The name of the command, for the message.
- * @returns {string | null} The block message.
- */
-function optionReason(
-  words: readonly string[],
-  index: number,
-  tables: OptionTables,
-  label: string,
-): string | null {
-  const word = words[index] ?? "",
-    { flags, valueFlags, enumValues } = tables,
-    blocked = blockedOption,
-    needsValue = (): string =>
-      `planning-readonly: blocked the option ${word} of ${label}. The option needs a value.`;
-  if (word === "--" || !word.startsWith("-") || word === "-") {
-    return null;
-  }
-  const equals = word.indexOf("="),
-    name = word.startsWith("--") && equals !== -1 ? word.slice(0, equals) : word,
-    inline = word.startsWith("--") && equals !== -1 ? word.slice(equals + 1) : undefined;
-  if (valueFlags.has(name)) {
-    const allowed = enumValues[name];
-    if (inline !== undefined) {
-      return allowed !== undefined && !allowed.has(inline)
-        ? blocked(`the option ${word} of ${label}`)
-        : null;
-    }
-    const value = words[index + 1];
-    if (value === undefined || value === "--" || isOptionWord(value, tables)) {
-      return needsValue();
-    }
-    return allowed !== undefined && !allowed.has(value)
-      ? blocked(`the option ${word} of ${label} with the value ${value}`)
-      : null;
-  }
-  if (flags.has(name)) {
-    return null;
-  }
-  if (word.startsWith("--")) {
-    return blocked(`the option ${word} of ${label}`);
-  }
-  // A short cluster such as `-la` matches when every letter is a known option.
-  const letters: string[] = [];
-  for (const letter of word.slice(1)) {
-    letters.push(`-${letter}`);
-  }
-  if (letters.length < 2) {
-    return blocked(`the option ${word} of ${label}`);
-  }
-  for (const [position, letter] of letters.entries()) {
-    if (flags.has(letter)) {
-      continue;
-    }
-    // A letter that takes a value must be the last of the cluster, because it
-    // takes the word that follows the cluster.
-    if (valueFlags.has(letter) && position === letters.length - 1) {
-      const value = words[index + 1];
-      if (value === undefined || value === "--" || isOptionWord(value, tables)) {
-        return needsValue();
-      }
-      continue;
-    }
-    return blocked(`the option ${word} of ${label}`);
-  }
-  return null;
-}
-
-/**
- * The number of words an option occupies, so the value of an option is not
- * read as an option itself.
- * @param {readonly string[]} words The words of the call.
- * @param {number} index The index of the option.
- * @param {OptionTables} tables The options of the command.
- * @returns {number} The number of words.
- */
-function optionWidth(words: readonly string[], index: number, tables: OptionTables): number {
-  const word = words[index] ?? "",
-    name = word.startsWith("--") && word.includes("=") ? word.slice(0, word.indexOf("=")) : word;
-  if (word.includes("=")) {
-    return 1;
-  }
-  if (tables.valueFlags.has(name)) {
-    const value = words[index + 1];
-    return value === undefined || value === "--" || isOptionWord(value, tables) ? 1 : 2;
-  }
-  // A short cluster that ends in a letter that takes a value takes the word
-  // that follows the cluster.
-  if (word.startsWith("-") && !word.startsWith("--") && word.length > 1) {
-    const last = `-${word.slice(-1)}`;
-    if (tables.valueFlags.has(last)) {
-      const value = words[index + 1];
-      return value === undefined || value === "--" || isOptionWord(value, tables) ? 1 : 2;
-    }
-  }
-  return 1;
-}
-
-/**
- * The reason a git command is not a read, or null when it is one.
- * @param {readonly string[]} words The words of the call, without `git`.
- * @returns {string | null} The block message.
- */
-function gitReason(words: readonly string[]): string | null {
-  const rest = [...words];
-  while (rest.length > 0) {
-    const word = rest[0] ?? "";
-    if (GIT_GLOBAL_VALUE_FLAGS.has(word)) {
-      const value = rest[1];
-      if (value === undefined) {
-        return `planning-readonly: blocked the git option ${word}. The option needs a value.`;
-      }
-      rest.splice(0, 2);
-      continue;
-    }
-    if (GIT_GLOBAL_FLAGS.has(word)) {
-      rest.shift();
-      continue;
-    }
-    break;
-  }
-  const subcommand = rest.shift();
-  if (subcommand === undefined || !GIT_READ_SUBCOMMANDS.has(subcommand)) {
-    return (
-      "planning-readonly: a planning model may only run git status, git diff, git log, git show, " +
-      "and git rev-parse."
-    );
-  }
-  const tables: OptionTables = {
-    flags: GIT_SUBCOMMAND_FLAGS[subcommand] ?? new Set<string>(),
-    valueFlags: GIT_SUBCOMMAND_VALUE_FLAGS[subcommand] ?? new Set<string>(),
-    enumValues: GIT_SUBCOMMAND_ENUM_VALUES[subcommand] ?? {},
-  };
-  let noExtDiff = false,
-    noTextconv = false;
-  for (let index = 0; index < rest.length; index += 1) {
-    const word = rest[index] ?? "";
-    // After `--` every word is a path, not an option, so it cannot ask for a
-    // safe diff driver.
-    if (word === "--") {
-      break;
-    }
-    if (subcommand === "log" && /^-\d+$/u.test(word)) {
-      continue;
-    }
-    const reason = optionReason(rest, index, tables, `git ${subcommand}`);
-    if (reason !== null) {
-      return reason;
-    }
-    if (word === "--no-ext-diff") {
-      noExtDiff = true;
-    }
-    if (word === "--no-textconv") {
-      noTextconv = true;
-    }
-    index += optionWidth(rest, index, tables) - 1;
-  }
-  const patches = subcommand === "diff" || subcommand === "show",
-    logsPatch = subcommand === "log" && rest.some((word) => word === "-p" || word === "--patch");
-  if ((patches || logsPatch) && !(noExtDiff && noTextconv)) {
-    return EXT_DIFF_MESSAGE;
-  }
-  return null;
-}
-
-/**
- * The reason a read command is not read-only, or null when it is one.
- * @param {readonly string[]} words The words of the call.
- * @returns {string | null} The block message.
- */
-function readCommandReason(words: readonly string[]): string | null {
-  const base = words[0] ?? "";
-  if (!READ_COMMANDS.has(base)) {
-    return (
-      `planning-readonly: blocked the command ${base}. A planning model may only run pwd, ls, ` +
-      "rg, grep, find, and read-only git commands."
-    );
-  }
-  if (base === "git") {
-    return gitReason(words.slice(1));
-  }
-  const tables: OptionTables = {
-    flags: READ_COMMAND_FLAGS[base] ?? new Set<string>(),
-    valueFlags: READ_COMMAND_VALUE_FLAGS[base] ?? new Set<string>(),
-    enumValues: READ_COMMAND_ENUM_VALUES[base] ?? {},
-  };
-  for (let index = 1; index < words.length; index += 1) {
-    const word = words[index] ?? "";
-    if (base === "find" && FIND_MUTATIONS.has(word)) {
-      return (
-        `planning-readonly: blocked the find option ${word}. A planning model may only list ` +
-        "files."
-      );
-    }
-    const reason = optionReason(words, index, tables, base);
-    if (reason !== null) {
-      return reason;
-    }
-    index += optionWidth(words, index, tables) - 1;
-  }
-  return null;
-}
-
-/**
- * The reason a shell command is not read-only, or null when it is one.
- * @param {Command} command The shell text or an argument list.
- * @returns {string | null} The block message.
- */
-function planningShellReason(command: Command): string | null {
-  if (typeof command !== "string") {
-    if (command.length === 0) {
-      return "planning-readonly: blocked an empty shell command.";
-    }
-    return readCommandReason([...command]);
-  }
-  const calls = literalShellCalls(command);
-  if (calls === null) {
-    return (
-      "planning-readonly: blocked a shell command that uses a redirect, an assignment, a " +
-      "substitution, a glob, or other dynamic syntax. A planning model may only run plain " +
-      "read-only commands."
-    );
-  }
-  if (calls.length === 0) {
-    return "planning-readonly: blocked an empty shell command.";
-  }
-  for (const words of calls) {
-    if (words.length === 0) {
-      return "planning-readonly: blocked an empty shell command.";
-    }
-    const reason = readCommandReason(words);
-    if (reason !== null) {
-      return reason;
-    }
-  }
-  return null;
-}
-
-/**
- * The reason a shell tool call is not read-only, or null when it is one.
- * @param {string} toolName The tool name.
- * @param {Readonly<Record<string, unknown>>} input The tool input.
- * @returns {string | null} The block message.
- */
-function planningShellToolReason(
-  toolName: string,
-  input: Readonly<Record<string, unknown>>,
-): string | null {
-  if (BATCH_SHELL_TOOLS.has(toolName)) {
-    const commands = input["commands"];
-    if (!Array.isArray(commands)) {
-      return `planning-readonly: blocked ${toolName}. The commands must be a list.`;
-    }
-    for (const entry of commands) {
-      if (!isRecord(entry)) {
-        return `planning-readonly: blocked ${toolName}. A command of the batch is malformed.`;
-      }
-      const text = textOf(entry["command"]);
-      if (text === undefined) {
-        return `planning-readonly: blocked ${toolName}. A command of the batch has no command.`;
-      }
-      const reason = planningShellReason(text);
-      if (reason !== null) {
-        return reason;
-      }
-    }
-    return null;
-  }
-  if (CODE_SHELL_TOOLS.has(toolName)) {
-    if (input["language"] !== "shell") {
-      return `planning-readonly: blocked ${toolName}. A planning model may only run shell code.`;
-    }
-    const code = textOf(input["code"]);
-    if (code === undefined) {
-      return `planning-readonly: blocked ${toolName}. The code is missing.`;
-    }
-    return planningShellReason(code);
-  }
-  const text = commandTextOf(input);
-  if (text === null) {
-    return `planning-readonly: blocked ${toolName}. The command is missing.`;
-  }
-  // A raw command runs without a shell, so the runner splits it on whitespace
-  // and the words are the argument list.
-  if (toolName === "hypa_shell" && input["raw"] === true) {
-    return planningShellReason(rawWords(text));
-  }
-  return planningShellReason(text);
-}
-
-/**
- * The block message for a tool call a planning model may not make, or null
- * when the call is a read the policy allows.
- * @param {string} toolName The tool name.
- * @param {Readonly<Record<string, unknown>>} input The tool input.
- * @returns {string | null} The block message.
- */
-function planningToolReason(
-  toolName: string,
-  input: Readonly<Record<string, unknown>>,
-): string | null {
-  if (WORKFLOW_TOOLS.has(toolName)) {
-    return null;
-  }
-  if (DOGSLED_TOOLS.has(toolName)) {
-    return null;
-  }
-  if (toolName === "mcp__dogsled__spawn") {
-    return isBoundSpawn(input)
-      ? null
-      : "planning-readonly: blocked a Dogsled spawn without a bound unit. A planning model may " +
-          "only spawn a bound unit by its id.";
-  }
-  if (READ_TOOLS.has(toolName)) {
-    return null;
-  }
-  if (SHELL_TOOLS.has(toolName)) {
-    return planningShellToolReason(toolName, input);
-  }
-  return toolMessage(toolName);
-}
-
-export { isPlanningModel, planningShellReason, planningToolReason, readCommandReason };
-export type { ModelIdentity };