@illusoryai/pi-orchestration-guard 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @illusoryai/pi-guard
+
+Orchestrator mode enforcement — restricts bash commands to read-only operations in orchestrator mode.
+
+## Contents
+
+| Type | Name | Description |
+|------|------|-------------|
+| Extension | `orchestrator-guard.ts` | Blocks write commands (mkdir, cp, rm, etc.) in orchestrator mode |
+
+## Install
+
+```bash
+pi install npm:@illusoryai/pi-guard
+```
+
+Optional — only for projects requiring strict orchestrator/implement mode separation.
+Private package — requires npm auth configured in `~/.npmrc`.

package/extensions/orchestrator-guard.ts

@@ -0,0 +1,319 @@
+/**
+	* Orchestrator Guard Extension
+	*
+	* Enforces the orchestrator/worker role boundary. In orchestrator mode (default),
+	* blocks direct code implementation — the model must delegate via subagents.
+	*
+	* Modes:
+	*   - Orchestrator (default): read-only + subagent delegation. edit/write blocked.
+	*   - Implement: full tool access for direct implementation.
+	*
+	* Commands:
+	*   /implement [reason]  — switch to implement mode
+	*   /orchestrate         — switch back to orchestrator mode
+	*
+	* Also enforces always-on forbidden commands (e.g., git push origin main).
+	*/
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+// --- Forbidden patterns (blocked in ALL modes) ---
+
+import { existsSync } from "node:fs";
+import { execSync as execSyncNode } from "node:child_process";
+
+function isGraphiteRepo(): boolean {
+	try {
+		const root = execSyncNode("git rev-parse --show-toplevel", { encoding: "utf-8", timeout: 3000 }).trim();
+		return existsSync(`${root}/.graphite_id`);
+	} catch {
+		return false;
+	}
+}
+
+const ALWAYS_FORBIDDEN: { pattern: RegExp; reason: string; check?: () => boolean }[] = [
+	{
+		pattern: /\bgit\s+push\s+(?:--[^\s]+\s+)*origin\s+main\b/,
+		reason: "Direct push to main is forbidden. Use Graphite PRs (gt submit).",
+		check: isGraphiteRepo,
+	},
+	{
+		pattern: /\bgit\s+push\s+(?:--[^\s]+\s+)*origin\s+master\b/,
+		reason: "Direct push to master is forbidden. Use Graphite PRs (gt submit).",
+		check: isGraphiteRepo,
+	},
+];
+
+// --- Orchestrator mode: bash commands that are allowed (read-only / diagnostic) ---
+
+const SAFE_BASH_PATTERNS: RegExp[] = [
+	// Git read-only
+	/^\s*git\s+(status|log|diff|show|branch|remote|stash\s+list|worktree\s+list|rev-parse|ls-files|blame)/,
+	/^\s*git\s+worktree\s+(list|prune)/,
+	// Graphite read-only
+	/^\s*gt\s+(log|status|ls|branch|trunk|info)/,
+	// File exploration
+	/^\s*ls\b/,
+	/^\s*cat\b/,
+	/^\s*head\b/,
+	/^\s*tail\b/,
+	/^\s*wc\b/,
+	/^\s*find\b/,
+	/^\s*grep\b/,
+	/^\s*rg\b/,
+	/^\s*fd\b/,
+	/^\s*tree\b/,
+	/^\s*file\b/,
+	/^\s*stat\b/,
+	/^\s*du\b/,
+	/^\s*df\b/,
+	/^\s*pwd\b/,
+	/^\s*which\b/,
+	/^\s*echo\b/,
+	/^\s*printenv\b/,
+	/^\s*env\b/,
+	// Path utilities
+	/^\s*realpath\b/,
+	/^\s*dirname\b/,
+	/^\s*basename\b/,
+	// Diff (read-only comparison)
+	/^\s*diff\b/,
+	// Process / system info
+	/^\s*ps\b/,
+	/^\s*whoami\b/,
+	/^\s*hostname\b/,
+	/^\s*uname\b/,
+	/^\s*date\b/,
+	// Cargo read-only
+	/^\s*cargo\s+(check|clippy|fmt\s+--check|test\s+--no-run|metadata|tree)/,
+	// TypeScript type-check only
+	/^\s*tsc\s+--noEmit\b/,
+	// npm read-only
+	/^\s*npm\s+(ls|list)\b/,
+	// Journalctl / systemctl status (read-only)
+	/^\s*journalctl\b/,
+	/^\s*systemctl\s+status\b/,
+	// cd (no side effects)
+	/^\s*cd\b/,
+];
+
+/**
+	* Check if a bash command is safe (read-only) for orchestrator mode.
+	*
+	* Note: Uses regex splitting on shell operators (&&, ||, ;, |). Does not handle
+	* operators inside quoted strings (e.g., `grep "foo|bar"`). Acceptable for the
+	* common case; false positives are blocked and can be delegated via subagents.
+	*/
+function findUnsafeBashSegment(command: string): string | undefined {
+	const segments = command.split(/\s*(?:&&|\|\||[;|])\s*/).map((s) => s.trim());
+	for (const segment of segments) {
+		if (!segment) continue;
+		if (!SAFE_BASH_PATTERNS.some((p) => p.test(segment))) {
+			return segment;
+		}
+	}
+	return undefined;
+}
+
+function getLastEntry<T>(entries: { type: string; customType?: string; data?: unknown }[], customType: string): T | undefined {
+	const entry = entries
+		.filter((e) => e.type === "custom" && e.customType === customType)
+		.pop();
+	return entry?.data as T | undefined;
+}
+
+export default function orchestratorGuard(pi: ExtensionAPI) {
+	let orchestratorMode = true;
+	let implementReason = "";
+
+	// --- State persistence ---
+
+	function persistState(): void {
+		pi.appendEntry("orchestrator-guard", {
+			orchestratorMode,
+			implementReason,
+		});
+	}
+
+	// --- UI helpers ---
+
+	function updateStatus(ctx: ExtensionContext): void {
+		if (orchestratorMode) {
+			ctx.ui.setStatus(
+				"orch-guard",
+				ctx.ui.theme.fg("warning", "⏸ orchestrator") + ctx.ui.theme.fg("dim", " (edit/write blocked)"),
+			);
+		} else {
+			ctx.ui.setStatus(
+				"orch-guard",
+				ctx.ui.theme.fg("success", "⚡ implement") +
+					(implementReason ? ctx.ui.theme.fg("dim", ` — ${implementReason}`) : ""),
+			);
+		}
+	}
+
+	// --- Commands ---
+
+	pi.registerCommand("implement", {
+		description: "Switch to implement mode (full tool access)",
+		handler: async (args, ctx) => {
+			if (!orchestratorMode) {
+				ctx.ui.notify("Already in implement mode.", "info");
+				return;
+			}
+			implementReason = args?.trim() || "";
+			orchestratorMode = false;
+			updateStatus(ctx);
+			persistState();
+			ctx.ui.notify(
+				`Switched to implement mode.${implementReason ? ` Reason: ${implementReason}` : ""}\nUse /orchestrate to return.`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("orchestrate", {
+		description: "Switch to orchestrator mode (read-only, delegate via subagents)",
+		handler: async (_args, ctx) => {
+			if (orchestratorMode) {
+				ctx.ui.notify("Already in orchestrator mode.", "info");
+				return;
+			}
+			orchestratorMode = true;
+			implementReason = "";
+			updateStatus(ctx);
+			persistState();
+			ctx.ui.notify("Switched to orchestrator mode. edit/write blocked. Use subagents to delegate.", "info");
+		},
+	});
+
+	// --- Tool call interception ---
+
+	pi.on("tool_call", async (event, ctx) => {
+		// 1. Always-on forbidden commands (regardless of mode)
+		if (event.toolName === "bash") {
+			const command = event.input.command as string;
+			for (const rule of ALWAYS_FORBIDDEN) {
+				if (rule.pattern.test(command) && (!rule.check || rule.check())) {
+					if (ctx.hasUI) ctx.ui.notify(`Blocked: ${rule.reason}`, "warning");
+					return { block: true, reason: rule.reason };
+				}
+			}
+		}
+
+		// 2. If in implement mode, allow everything else
+		if (!orchestratorMode) return undefined;
+
+		// 3. Orchestrator mode: block edit and write
+		if (event.toolName === "edit") {
+			return {
+				block: true,
+				reason: [
+					"BLOCKED: You are in orchestrator mode. Direct file editing is not allowed.",
+					"",
+					"To make code changes, delegate via subagent:",
+					'  subagent({ agent: "td-worker", task: "Edit file X to do Y" })',
+					"",
+					"Or ask the human to switch modes:",
+					'  "Should I implement this directly? Use /implement to allow."',
+				].join("\n"),
+			};
+		}
+
+		if (event.toolName === "write") {
+			return {
+				block: true,
+				reason: [
+					"BLOCKED: You are in orchestrator mode. Direct file writing is not allowed.",
+					"",
+					"To create/modify files, delegate via subagent:",
+					'  subagent({ agent: "td-worker", task: "Create file X with Y" })',
+					"",
+					"Or ask the human to switch modes:",
+					'  "Should I implement this directly? Use /implement to allow."',
+				].join("\n"),
+			};
+		}
+
+		// 4. Orchestrator mode: filter bash commands
+		if (event.toolName === "bash") {
+			const command = event.input.command as string;
+			const unsafeSegment = findUnsafeBashSegment(command);
+			if (unsafeSegment) {
+				return {
+					block: true,
+					reason: [
+						`BLOCKED: Bash command not allowed in orchestrator mode.`,
+						`Command: ${command}`,
+						`Unrecognized segment: ${unsafeSegment}`,
+						"",
+						"Allowed: git read-only, ls, cat, grep, find, diff, cargo check/clippy, tsc --noEmit.",
+						"",
+						"To run this command, either:",
+						'  1. Delegate: subagent({ agent: "td-worker", task: "Run X" })',
+						'  2. Switch mode: "/implement to allow direct commands"',
+					].join("\n"),
+				};
+			}
+		}
+
+		return undefined;
+	});
+
+	// --- System prompt injection ---
+
+	pi.on("before_agent_start", async (event) => {
+		if (!orchestratorMode) return undefined;
+
+		return {
+			systemPrompt:
+				(event.systemPrompt || "") +
+				`
+
+## ⏸ Orchestrator Mode Active
+
+You are in ORCHESTRATOR mode. You coordinate and delegate — you do NOT implement directly.
+The edit and write tools are blocked. Modifying bash commands are blocked.
+
+### What you CAN do
+- Read files and run diagnostic commands (git status, ls, grep, cargo check)
+- Use the **subagent** tool to delegate tasks to worker agents
+- Use **/run <agent> <task>** to quickly delegate a task
+- Use **/chain** to run multi-step agent pipelines
+- Use obsidian, linkup_web_search, linkup_web_fetch (fetch URLs), and other coordination tools
+- When a URL is provided, use **linkup_web_fetch** first to fetch its content directly — don't search for it
+- Analyze, plan, and present findings to the human
+
+### What you CANNOT do (will be blocked)
+- edit or write tools
+- Bash commands that modify files or run builds
+- Any direct code implementation
+
+### How to delegate
+Subagents:
+  /run td-worker <task description>
+  /chain scout -> td-worker
+  subagent({ agent: "td-worker", task: "..." })
+
+### If the task is trivial
+Tell the human: "This is a small fix I could do directly. Use /implement to allow."
+Do NOT attempt to work around the blocks.
+`,
+		};
+	});
+
+	// --- Session restore ---
+
+	pi.on("session_start", async (_event, ctx) => {
+		// Restore persisted state
+		const entries = ctx.sessionManager.getEntries();
+		const state = getLastEntry<{ orchestratorMode: boolean; implementReason?: string }>(entries, "orchestrator-guard");
+
+		if (state) {
+			orchestratorMode = state.orchestratorMode ?? true;
+			implementReason = state.implementReason ?? "";
+		}
+
+		updateStatus(ctx);
+	});
+}

package/install.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * @illusoryai/pi-guard postinstall
+ * Auto-installs peer dependencies and registers them in pi settings.
+ * Add entries to PEERS array when this package gains peer deps.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const PEERS = [];
+
+if (PEERS.length === 0) process.exit(0);
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const globalModules = join(__dirname, "..", "..");
+
+for (const peer of PEERS) {
+  const peerPath = join(globalModules, peer);
+  if (!existsSync(peerPath)) {
+    console.log(`[pi-guard] Installing peer: ${peer}`);
+    try {
+      execSync(`npm install -g ${peer}`, { stdio: "pipe" });
+      console.log(`[pi-guard] Installed ${peer}`);
+    } catch {
+      console.warn(
+        `[pi-guard] Could not auto-install ${peer}. Run: pi install npm:${peer}`
+      );
+    }
+  }
+}
+
+const home = process.env.SUDO_USER
+  ? join("/home", process.env.SUDO_USER)
+  : homedir();
+const settingsPath = join(home, ".pi", "agent", "settings.json");
+
+if (existsSync(settingsPath)) {
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    const packages = settings.packages || [];
+    let changed = false;
+
+    for (const peer of PEERS) {
+      const entry = `npm:${peer}`;
+      if (!packages.includes(entry)) {
+        packages.push(entry);
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      settings.packages = packages;
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+      console.log("[pi-guard] Updated pi settings with peer deps");
+    }
+  } catch {
+    // Don't fail install on settings update error
+  }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@illusoryai/pi-orchestration-guard",
+  "version": "0.1.0",
+  "description": "Orchestrator mode enforcement for pi — blocks direct implementation, enforces subagent delegation",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package"
+  ],
+  "scripts": {
+    "postinstall": "node install.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "extensions/orchestrator-guard.ts"
+    ],
+    "skills": []
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}