@oisin-ee/oisinpi 0.10.2 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @oisin-ee/oisinpi
 
+## 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
+
+- 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,14 @@ 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.
 
+## Planning models
+
+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.
+
+Planning restrictions belong to Plannotator. It owns plan mode, and it blocks writes while it plans.
+
 ## 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.1",
   "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

@@ -49,15 +49,29 @@ 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.
+   * @param {Readonly<Record<string, unknown>>} input The tool input.
+   * @returns {readonly ToolCall[]} The calls of the envelope.
+   */
+  nestedCalls = (input: Readonly<Record<string, unknown>>): readonly ToolCall[] => {
     const uses = input["tool_uses"];
     if (!Array.isArray(uses)) {
       return [];
     }
-    return uses.filter(isRecord).map((use) => ({
-      input: isRecord(use["parameters"]) ? use["parameters"] : {},
-      toolName: typeof use["recipient_name"] === "string" ? use["recipient_name"] : "",
-    }));
+    const calls: ToolCall[] = [];
+    for (const use of uses) {
+      if (!isRecord(use)) {
+        continue;
+      }
+      const toolName = use["recipient_name"];
+      const parameters = use["parameters"];
+      calls.push({
+        input: isRecord(parameters) ? parameters : {},
+        toolName: typeof toolName === "string" ? toolName : "",
+      });
+    }
+    return calls;
   },
   toolViolation = (event: ToolCall, cwd: string, depth = 0): string | null => {
     if (depth > MAX_NESTING) {
@@ -72,8 +86,8 @@ const MAX_NESTING = 8,
     if (own !== null) {
       return own;
     }
-    for (const nested of nestedCalls(call.input)) {
-      const message = toolViolation(nested, cwd, depth + 1);
+    for (const child of nestedCalls(call.input)) {
+      const message = toolViolation(child, cwd, depth + 1);
       if (message !== null) {
         return message;
       }

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

@@ -32,6 +32,7 @@ interface ShNode {
 }
 
 interface Parsed {
+  readonly tree: unknown;
   readonly calls: readonly Words[];
   readonly guards: readonly Guard[];
 }
@@ -145,7 +146,7 @@ const MAX_BUFFER = 16 * 1024 * 1024,
         }
       };
     visit(tree);
-    return { calls, guards };
+    return { tree, calls, guards };
   },
   parsedOf = (command: string): Parsed => {
     if (cache.command !== command || cache.parsed === undefined) {
@@ -170,4 +171,75 @@ const MAX_BUFFER = 16 * 1024 * 1024,
   shellCallGuards = (command: string): (string[][] | null)[] =>
     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: string): boolean {
+  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: string): string[][] | null {
+  const parsed = parsedOf(command),
+    allowed = new Set([
+      "File",
+      "Stmt",
+      "CallExpr",
+      "Word",
+      "Lit",
+      "SglQuoted",
+      "DblQuoted",
+      "BinaryCmd",
+    ]),
+    safe = (node: unknown, quoted = false): boolean => {
+      if (Array.isArray(node)) {
+        return node.every((item: unknown) => 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: unknown) =>
+        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-prewalk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-prewalk",
-  "version": "0.10.2",
+  "version": "0.11.1",
   "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.10.2",
+  "version": "0.11.1",
   "description": "Sticky virtual model tiers with quota-aware recovery for pi.",
   "keywords": [
     "pi-extension",

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

@@ -64,6 +64,14 @@ Untargeted `done` and `drop` affect open work only. A parent without `task` is n
 Appending children to a closed parent reopens it as pending. An active parent stays active.
 Outcome and subtask progress remain separate. Abandoned work never counts as completed.
 
+## Activation gate
+
+Shell, code, and mutation tools need one active local unit. Structured reads, workflow control, and `todo` calls stay available without one.
+The gate checks the selected model at each call. The planner selections `tier/plan-claude` and `tier/plan-gpt` skip the activation check, so a planning session can read and inspect without a unit.
+Every other selection needs an active unit, including a tier with another name and a physical model that only looks like a planner.
+The exemption is a workflow prerequisite, not a permission. It does not grant write access, and other policies such as guardrails still apply.
+An active unit stays required for the sessions that implement code.
+
 ## State
 
 Each task change is saved as a `todo-state` entry on the session branch. A resumed session, a `/tree` move,

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

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-todo",
-  "version": "0.10.2",
+  "version": "0.11.1",
   "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/gate.ts

@@ -2,8 +2,17 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { TaskProvider } from "./provider.ts";
 import { ownsTodo } from "./lifecycle.ts";
 
-/** Exact structured reads and workflow controls, never command-text inference. */
-const controls = new Set([
+/** Planning selections that skip the activation check, exact provider and model IDs. */
+const planningSelections = new Set(["plan-claude", "plan-gpt"]),
+  /**
+   * Whether the selected model is a planning selection.
+   * @param {Readonly<object>} model Selected model, when the session has one.
+   * @returns {boolean} Whether the activation check does not apply.
+   */
+  isPlanning = (model: { readonly provider?: string; readonly id?: string } | undefined): boolean =>
+    model?.provider === "tier" && planningSelections.has(model.id ?? ""),
+  /** Exact structured reads and workflow controls, never command-text inference. */
+  controls = new Set([
     "ask",
     "codemode",
     "interview",
@@ -57,7 +66,7 @@ const controls = new Set([
         return { block: false };
       }
       provider.context(ctx);
-      if (controls.has(event.toolName)) {
+      if (controls.has(event.toolName) || isPlanning(ctx.model)) {
         return { block: false };
       }
       const active = provider.capability().active();

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

@@ -9,6 +9,8 @@ const workUnitGuidance =
   "Use returned IDs after creation. Update drafts before start; only one complete self leaf executes locally. " +
   "The lead closes any open leaf with done and a short note, or with drop. " +
   "Keep content a short headline (aim under 60 characters, imperative, no trailing detail); " +
-  "put context, approach, or acceptance detail in the optional description (one or two sentences).";
+  "put context, approach, or acceptance detail in the optional description (one or two sentences). " +
+  "A planning session selected as tier/plan-claude or tier/plan-gpt needs no active unit. " +
+  "Every other session needs one active local unit before shell, code, or mutation tools.";
 
 export { workUnitGuidance };

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

@@ -27,6 +27,12 @@ interface Startup {
   readonly cwd: string;
   readonly seedPath: string;
 }
+/** One selectable model in the runtime catalog. */
+interface Selection {
+  readonly id: string;
+  readonly kind?: "physical" | "virtual";
+  readonly provider: string;
+}
 interface RuntimeFixture {
   readonly session: Readonly<Pick<Session, "dispose" | "abort" | "messages">> & {
     readonly extensionRunner: Readonly<Pick<Session["extensionRunner"], "emitToolResult" | "emit">>;
@@ -35,27 +41,32 @@ interface RuntimeFixture {
   readonly provider: () => TaskProviderV1;
   readonly call: (name: string, args: Readonly<Record<string, string>>) => Promise<void>;
   readonly create: () => Promise<void>;
+  readonly select: (provider: string, id: string) => Promise<void>;
   readonly todo: (params: TodoParams) => Promise<unknown>;
 }
+/** Plain description of one runtime fixture. */
+interface FixtureRequest {
+  readonly collision: boolean;
+  readonly later: ExtensionFactory | undefined;
+  readonly selections: readonly Selection[];
+  readonly startup: Startup | undefined;
+}
 
 /**
  * Creates resources without user configuration or external services.
- * @param {ExtensionFactory} later Optional additional guard or test tool.
- * @param {boolean} collision Whether the other todo owner loads first.
- * @param {Startup | undefined} startup Optional worker startup configuration.
+ * @param {Readonly<FixtureRequest>} request Fixture description.
  * @returns {object} Local resource owners.
  */
 const resources = (
-    later: ExtensionFactory | undefined,
-    collision: boolean,
-    startup: Startup | undefined,
+    request: Readonly<FixtureRequest>,
   ): {
     events: ReturnType<typeof createEventBus>;
     manager: SessionManager;
     settings: SettingsManager;
     loader: DefaultResourceLoader;
   } => {
-    const events = createEventBus(),
+    const { collision, later, startup } = request,
+      events = createEventBus(),
       manager = SessionManager.inMemory(),
       settings = SettingsManager.inMemory({
         compaction: { enabled: false },
@@ -130,47 +141,55 @@ const resources = (
     );
   },
   /**
-   * Executes a scripted tool request through the actual model runtime.
-   * @param {Session} session Session execution owner.
-   * @param {Readonly<ReturnType<typeof fauxProvider>>} faux Scripted provider.
-   * @returns {RuntimeFixture["call"]} Request function.
+   * Creates the model catalog with the requested physical and virtual entries.
+   * @param {Readonly<FixtureRequest>} request Fixture description.
+   * @returns {object} Scripted provider and model catalog owner.
    */
-  caller =
-    (
-      session: Readonly<Pick<Session, "prompt">>,
-      faux: Readonly<Pick<ReturnType<typeof fauxProvider>, "setResponses">>,
-    ): RuntimeFixture["call"] =>
-    async (name, args): Promise<void> => {
-      faux.setResponses([
-        fauxAssistantMessage(fauxToolCall(name, args)),
-        fauxAssistantMessage("Done."),
-      ]);
-      await session.prompt("Exercise one tool.");
-    },
-  /**
-   * Loads the real runner and codemode with a scripted model.
-   * @param {ExtensionFactory} later Additional extension.
-   * @param {boolean} collision Loads a competing owner first.
-   * @param {Startup | undefined} startup Optional worker startup configuration.
-   * @returns {Promise<RuntimeFixture>} Isolated runtime and callers.
-   */
-  runtimeFixture = async (
-    later?: ExtensionFactory,
-    collision = false,
-    startup?: Startup,
-  ): Promise<RuntimeFixture> => {
-    const setup = resources(later, collision, startup),
-      modelRuntime = await ModelRuntime.create({
+  catalog = async (
+    request: Readonly<FixtureRequest>,
+  ): Promise<{
+    faux: ReturnType<typeof fauxProvider>;
+    modelRuntime: ModelRuntime;
+  }> => {
+    const modelRuntime = await ModelRuntime.create({
         credentials: new InMemoryCredentialStore(),
         modelsPath: null,
         modelsStore: new InMemoryModelsStore(),
         refreshOnCreate: false,
       }),
-      faux = fauxProvider({ tokensPerSecond: 0 });
+      faux = fauxProvider({
+        models: [
+          ...request.selections
+            .filter((selection) => selection.kind === "physical")
+            .map((selection) => ({ id: selection.id })),
+          { id: "faux-1" },
+        ],
+        tokensPerSecond: 0,
+      });
     modelRuntime.registerNativeProvider(faux.provider);
+    for (const selection of request.selections.filter((entry) => entry.kind !== "physical")) {
+      modelRuntime.registerVirtualModel({
+        id: selection.id,
+        name: selection.id,
+        provider: selection.provider,
+        route: () => ({ model: faux.getModel(), thinkingLevel: "off" }),
+        thinkingLevels: ["off"],
+      });
+    }
+    await modelRuntime.refresh({ allowNetwork: false });
+    return { faux, modelRuntime };
+  },
+  /**
+   * Builds the real session and its callers over prepared resources.
+   * @param {Readonly<FixtureRequest>} request Fixture description.
+   * @returns {Promise<RuntimeFixture>} Isolated runtime and callers.
+   */
+  buildFixture = async (request: Readonly<FixtureRequest>): Promise<RuntimeFixture> => {
+    const setup = resources(request),
+      { faux, modelRuntime } = await catalog(request);
     await setup.loader.reload();
     const { session } = await createAgentSession({
-      cwd: startup?.cwd ?? "/tmp",
+      cwd: request.startup?.cwd ?? "/tmp",
       model: faux.getModel(),
       modelRuntime,
       resourceLoader: setup.loader,
@@ -181,7 +200,13 @@ const resources = (
     await session.bindExtensions({});
     session.setActiveToolsByName([...session.getActiveToolNames(), "codemode"]);
     return {
-      call: caller(session, faux),
+      call: async (name, args): Promise<void> => {
+        faux.setResponses([
+          fauxAssistantMessage(fauxToolCall(name, args)),
+          fauxAssistantMessage("Done."),
+        ]);
+        await session.prompt("Exercise one tool.");
+      },
       create: async (): Promise<void> => {
         await todoCall(session, {
           items: [{ content: "Build", contract: contract(), key: "build" }],
@@ -191,10 +216,36 @@ const resources = (
       },
       manager: setup.manager,
       provider: () => acquire(setup.events),
+      select: async (provider, id): Promise<void> => {
+        const model = modelRuntime.getModel(provider, id);
+        if (model === undefined) {
+          throw new Error(`Unknown selection: ${provider}/${id}`);
+        }
+        await session.setModel(model);
+      },
       session,
       todo: async (params): Promise<unknown> => todoCall(session, params),
     };
   },
+  /**
+   * Loads the real runner and codemode with a scripted model.
+   * @param {ExtensionFactory} later Optional additional guard or test tool.
+   * @param {boolean} collision Whether the other todo owner loads first.
+   * @param {Startup | undefined} startup Optional worker startup configuration.
+   * @returns {Promise<RuntimeFixture>} Isolated runtime and callers.
+   */
+  runtimeFixture = async (
+    later?: ExtensionFactory,
+    collision = false,
+    startup?: Startup,
+  ): Promise<RuntimeFixture> => buildFixture({ collision, later, selections: [], startup }),
+  /**
+   * Loads the real runtime with selectable virtual and physical models.
+   * @param {readonly Selection[]} selections Selectable catalog entries.
+   * @returns {Promise<RuntimeFixture>} Runtime with the given selections.
+   */
+  selectableFixture = async (selections: readonly Selection[]): Promise<RuntimeFixture> =>
+    buildFixture({ collision: false, later: undefined, selections, startup: undefined }),
   /**
    * Produces a deterministic tool result.
    * @returns {object} Successful content.
@@ -205,5 +256,5 @@ const resources = (
   }),
   emptyParameters = Type.Object({});
 
-export { emptyParameters, emptyResult, runtimeFixture };
-export type { RuntimeFixture };
+export { emptyParameters, emptyResult, runtimeFixture, selectableFixture };
+export type { RuntimeFixture, Selection };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/oisinpi",
-  "version": "0.10.2",
+  "version": "0.11.1",
   "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.10.2",
-    "@oisin-ee/pi-prewalk": "0.10.2",
-    "@oisin-ee/pi-tiers": "0.10.2",
-    "@oisin-ee/pi-todo": "0.10.2"
+    "@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"
   },
   "bundleDependencies": [
     "@oisin-ee/pi-guardrails",