pi-better-harness 0.40.5 → 0.40.6

package/extensions/tool-call-guard/index.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { SettingsControl } from "../settings/registry.ts";
+import { readHarnessSetting, updateHarnessSetting } from "../shared-harness-settings.ts";
+import { blockReason, detectForegroundWait, type WaitMatch } from "./waits.ts";
+
+const SETTING_KEY = "toolCallGuard";
+
+interface GuardSetting { version?: unknown; enabled?: unknown }
+
+/**
+ * Block a foreground command that waits on an external system.
+ *
+ * Returns the block result from `tool_call`, which pi turns into a failed tool result carrying
+ * `reason`. Nothing is executed. `isEnabled` is read per call so the setting takes effect
+ * without reloading the extension.
+ */
+export function installToolCallGuard(
+  pi: ExtensionAPI,
+  isEnabled: () => boolean,
+  onBlock?: (match: WaitMatch, command: string) => void,
+): void {
+  pi.on("tool_call", (event) => {
+    if (!isEnabled()) return;
+    if (event.toolName !== "bash") return;
+    // `input` is the current SDK field; older typings and some hosts expose `args`.
+    const payload = event as { input?: { command?: unknown }; args?: { command?: unknown } };
+    const command = payload.input?.command ?? payload.args?.command;
+    if (typeof command !== "string") return;
+    const match = detectForegroundWait(command);
+    if (!match) return;
+    onBlock?.(match, command);
+    return { block: true, reason: blockReason(match) };
+  });
+}
+
+export default function toolCallGuardExtension(pi: ExtensionAPI): void {
+  let enabled = true;
+
+  const read = (): void => {
+    const value = readHarnessSetting<GuardSetting>(SETTING_KEY);
+    if (value !== undefined && (value?.version !== 1 || typeof value.enabled !== "boolean")) {
+      throw new Error("Invalid tool-call guard setting in global settings.json.");
+    }
+    enabled = value?.enabled !== false;
+  };
+
+  const setting: SettingsControl = {
+    id: "tool-call-guard", label: "Tool call guard", values: ["On", "Off"],
+    get: () => enabled ? "On" : "Off",
+    change(value: string, _ctx: ExtensionCommandContext) {
+      if (value !== "On" && value !== "Off") throw new Error("Invalid tool-call guard value.");
+      updateHarnessSetting(SETTING_KEY, () => ({ version: 1, enabled: value === "On" }));
+      enabled = value === "On";
+    },
+  };
+
+  const register = () => pi.events.emit("harness-settings:register", setting);
+  let stopSettings: (() => void) | undefined;
+  const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
+
+  subscribe();
+  register();
+  installToolCallGuard(pi, () => enabled);
+
+  pi.on("session_start", () => {
+    subscribe();
+    try { read(); }
+    catch {
+      // A malformed value must not take the session down; fall back to guarding.
+      enabled = true;
+    }
+    register();
+  });
+
+  pi.on("session_shutdown", () => {
+    stopSettings?.();
+    stopSettings = undefined;
+  });
+}

package/extensions/tool-call-guard/waits.ts

@@ -0,0 +1,59 @@
+/**
+ * Recognise a foreground command that waits on something outside this machine.
+ *
+ * The guard keys off command shape rather than duration: a five minute test run belongs in the
+ * foreground where its output streams, while `gh pr checks --watch` can only end when GitHub
+ * says so. Duration cannot tell those apart, and blocking the first would be wrong.
+ */
+export interface WaitMatch {
+  /** Which rule matched, quoted back to the caller so the block is explainable. */
+  rule: string;
+  /** What the command is waiting for. */
+  waitsOn: string;
+}
+
+/** A foreground pause shorter than this is ordinary command flow, not a wait. */
+export const SLEEP_THRESHOLD_SECONDS = 3;
+
+const RULES: readonly { rule: RegExp; waitsOn: string }[] = [
+  { rule: /\bgh\s+pr\s+checks\b[^\n]*--watch\b/, waitsOn: "a pull request's checks" },
+  { rule: /\bgh\s+run\s+(?:view|watch)\b[^\n]*--watch\b/, waitsOn: "a workflow run" },
+  { rule: /\bgh\s+run\s+watch\b/, waitsOn: "a workflow run" },
+  { rule: /\bgh\s+workflow\s+run\b[^\n]*--watch\b/, waitsOn: "a workflow run" },
+  // A helper script whose name starts with watch- polls an external system, whatever its flags.
+  { rule: /\bwatch[-_][\w.-]*/, waitsOn: "an external state change" },
+  // --watch and --until only mean polling on provider CLIs; `git log --until` is a plain filter.
+  { rule: /\b(?:gh|github|glab)\b[^\n]*--(?:watch|until)\b/, waitsOn: "an external state change" },
+  { rule: /(?:^|[;&|]\s*)watch\s+\S/, waitsOn: "a repeating command" },
+  { rule: /\btail\s+-[a-zA-Z]*[fF]/, waitsOn: "a growing file" },
+  { rule: /\bdocker\s+(?:logs|events)\b[^\n]*\s-f\b/, waitsOn: "a container's log stream" },
+  { rule: /\bkubectl\b[^\n]*(?:--watch\b|\s-w\b)/, waitsOn: "cluster state" },
+  // A poll loop only counts when its body actually waits on something.
+  { rule: /\b(?:until|while)\b[^\n]*\b(?:sleep|curl|gh\s|docker\s|kubectl\s|pg_isready)\b/, waitsOn: "a repeated external check" },
+];
+
+const SLEEP = /(?:^|[;&|(]\s*|\bsudo\s+)sleep\s+(\d+(?:\.\d+)?)/;
+
+export function detectForegroundWait(command: string): WaitMatch | undefined {
+  for (const { rule, waitsOn } of RULES) {
+    if (rule.test(command)) return { rule: rule.source, waitsOn };
+  }
+  const sleep = SLEEP.exec(command);
+  if (sleep) {
+    const seconds = Number(sleep[1]);
+    if (Number.isFinite(seconds) && seconds > SLEEP_THRESHOLD_SECONDS) {
+      return { rule: SLEEP.source, waitsOn: `${seconds} seconds of wall clock` };
+    }
+  }
+  return undefined;
+}
+
+/** The message the model reads instead of the command's output. */
+export function blockReason(match: WaitMatch): string {
+  return [
+    `This command waits on ${match.waitsOn}, so it belongs in a background task.`,
+    "Spawn it with bg_task_spawn, then call wait_for_operations to park until it reports; a background task survives the end of the turn, while a foreground wait does not.",
+    "Read bg_task_status and bg_task_log for the verdict.",
+    'To run this command in the foreground anyway, set Tool call guard to Off in Harness settings.',
+  ].join(" ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.40.5",
+  "version": "0.40.6",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, model routing, and Outcome & Todo.",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
       "extensions/model-router/index.ts",
       "extensions/task-context/index.ts",
       "extensions/minimal-output/index.ts",
+      "extensions/tool-call-guard/index.ts",
       "extensions/settings/index.ts"
     ],
     "image": "https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-harness.png"
@@ -51,7 +52,7 @@
   ],
   "scripts": {
     "prepack": "node ../../scripts/sync-shared-log-utils.mjs && node ../../scripts/stage-harness-dependencies.mjs",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node extensions/minimal-output/index.ts extensions/minimal-output/hook.ts extensions/settings/index.ts extensions/execution-policy.ts extensions/task-context/index.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --module NodeNext --moduleResolution NodeNext --target ES2022 --strict --skipLibCheck --types node extensions/minimal-output/index.ts extensions/minimal-output/hook.ts extensions/settings/index.ts extensions/execution-policy.ts extensions/tool-call-guard/index.ts extensions/tool-call-guard/waits.ts extensions/task-context/index.ts",
     "test": "node --import tsx --import ../../scripts/isolate-registry.mjs --test test/*.test.mjs test/*.test.ts test/task-context/*.test.ts"
   },
   "dependencies": {