@senomas/pi-git-hat 0.2.2 → 0.2.5

package/README.md

@@ -16,6 +16,7 @@ No other dependencies needed. On first startup, role prompts and a default `role
 
 - **Role-based branch switching** — `/hat` TUI to pick branches grouped by role
 - **Permission enforcement** — each role can only write to certain paths
+- **Tool enforcement** — per-role allow/block rules for commands ([docs](docs/tool-enforcement.md))
 - **System prompt injection** — role instructions injected automatically per session
 - **Ancestry checking** — `/hatt` validates branch parent chain before work
 - **Auto-seeding** — role prompts copied from bundled `roles/` to project `.pi/` on first use

package/git-hat.ts

@@ -45,13 +45,30 @@ import {
   Text,
 } from "@earendil-works/pi-tui";
 import { SearchableSelectList } from "./lib/searchable-select-list.js";
+import {
+  type RegexObj,
+  type ToolRule,
+  testRegex,
+  evaluateToolRules,
+} from "./lib/tool-enforcement.js";
 
 // -- Types ---------------------------------------------------------
 
+interface WritablePathEntry {
+  /** Directory or file path (relative to project root). Empty string = project root. */
+  path: string;
+  /** Optional file extension filter, e.g. "md" — if set, only files with this extension are writable. */
+  extension?: string;
+}
+
 interface RoleDef {
   pattern: string;
   description?: string;
   ancestorRoles?: string[];
+  tool?: ToolRule[];
+  /** Tool rules evaluated after default post-tool rules (snake_case key "post-tool" in JSON). */
+  postTool?: ToolRule[];
+  writablePaths?: WritablePathEntry[];
 }
 
 interface RolesConfig {
@@ -61,6 +78,13 @@ interface RolesConfig {
   fileDir?: string;
   caseInsensitive?: boolean;
 
+  default?: {
+    /** Tool rules evaluated before role-specific rules (snake_case key "pre-tool" in JSON). */
+    preTool?: ToolRule[];
+    /** Tool rules evaluated after role-specific rules (snake_case key "post-tool" in JSON). */
+    postTool?: ToolRule[];
+  };
+
   postSwitchLog?: boolean;
 }
 
@@ -69,6 +93,11 @@ interface MergedConfig {
   fileDir: string;
   caseInsensitive: boolean;
 
+  /** Default pre-tool rules loaded from roles.json default.pre-tool */
+  preTool?: ToolRule[];
+  /** Default post-tool rules loaded from roles.json default.post-tool */
+  postTool?: ToolRule[];
+
   postSwitchLog: boolean;
   configFile: string;
 }
@@ -254,6 +283,10 @@ function loadConfig(): MergedConfig {
         if (raw.caseInsensitive !== undefined) merged.caseInsensitive = raw.caseInsensitive;
 
         if (raw.postSwitchLog !== undefined) merged.postSwitchLog = raw.postSwitchLog;
+        if (raw.default) {
+          if (raw.default["pre-tool"] !== undefined) merged.preTool = raw.default["pre-tool"];
+          if (raw.default["post-tool"] !== undefined) merged.postTool = raw.default["post-tool"];
+        }
       } catch {
         // ignore parse errors
       }
@@ -341,11 +374,66 @@ function normalisePath(raw: string, cwd: string, cwdAbsolute: string): string {
   return path;
 }
 
+/**
+ * Strip a leading `cd <dir> && ` prefix from a bash command if <dir> resolves
+ * to a path inside the project. Supports relative paths (resolved against cwd).
+ *
+ * Examples:
+ *   "cd docs && ls -la"         → "ls -la"
+ *   "cd ../outside && ls"      → "cd ../outside && ls" (unchanged — outside project)
+ *   "ls -la"                    → "ls -la" (unchanged — no cd prefix)
+ */
+function stripCdPrefix(cmd: string, cwd: string, cwdAbsolute: string): string {
+  const match = cmd.match(/^cd\s+(\S+)\s*&&\s*/);
+  if (!match) return cmd;
+  const dir = match[1];
+  const rest = cmd.slice(match[0].length);
+  // Resolve the directory: absolute path, relative path, or ~
+  let resolved: string;
+  if (dir.startsWith("/")) {
+    resolved = dir;
+  } else if (dir.startsWith("~")) {
+    return cmd; // home dir — can't guarantee it's inside project, keep as-is
+  } else {
+    resolved = resolve(cwd, dir);
+  }
+  // Check if resolved path is inside the project
+  if (resolved.startsWith(cwdAbsolute)) {
+    return rest;
+  }
+  return cmd;
+}
+
 /** Check if a path is inside one of the given directories. */
 function isInside(path: string, dirs: string[]): boolean {
   return dirs.some((d) => path === d || path.startsWith(d + "/"));
 }
 
+/**
+ * Check if a path matches one of the given writable path entries.
+ *
+ * - If `entry.path` is empty string, only root-level files match.
+ * - If `entry.extension` is set, the path must end with that extension.
+ * - A trailing slash is appended automatically when matching directories.
+ */
+function isWritablePath(path: string, writablePaths: WritablePathEntry[]): boolean {
+  return writablePaths.some((entry) => {
+    const dir = entry.path;
+    const ext = entry.extension;
+    // Check directory match
+    const inDir =
+      dir === ""
+        ? !path.includes("/") // root level only
+        : path === dir || path.startsWith(dir + "/");
+    if (!inDir) return false;
+    // Check extension filter (if set)
+    if (ext) {
+      return path.endsWith("." + ext);
+    }
+    return true; // no extension filter = allow any file in this dir
+  });
+}
+
 /**
  * Load a role's .md file from the project's fileDir directory.
  * Case-insensitive lookup if config.caseInsensitive is true.
@@ -712,9 +800,17 @@ async function handleTodo(
     ctx.ui.notify("\uD83D\uDCED No pending todos found", "info");
     return;
   }
+
+  const remaining = result.totalPending - result.totalCovered;
+
+  if (remaining === 0) {
+    ctx.ui.notify("\u2714\uFE0F No more task in todo", "info");
+    return;
+  }
+
   ctx.ui.notify(result.summary, "info");
 
-  if (result.totalPending - result.totalCovered > 0) {
+  if (remaining > 0) {
     const detail = result.files
       .map((f) => {
         const items = f.pending
@@ -978,10 +1074,16 @@ export default function (pi: ExtensionAPI) {
           ? `${roleIcon(currentRole)} ${currentRole}${usingFile}`
           : "\u2753 No matching role (read-only mode)";
 
+        const defaultInfo = [];
+        if (config.preTool) defaultInfo.push(`pre-tool: ${config.preTool.length} rule(s)`);
+        if (config.postTool) defaultInfo.push(`post-tool: ${config.postTool.length} rule(s)`);
+        const defaultLine = defaultInfo.length > 0 ? `default: ${defaultInfo.join(", ")}\n` : "";
+
         ctx.ui.notify(
           `${roleDisplay}\n` +
             `branch: ${currentBranch ?? "not a git repo"}\n` +
             `${desc ? `desc: ${desc}\n` : ""}` +
+            `${defaultLine}` +
             `roles: ${config.configFile}`,
           "info",
         );
@@ -1141,6 +1243,188 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  // -- /hatr command: TUI branch selector for rebase ------------------
+
+  pi.registerCommand("hatr", {
+    description: "TUI branch selector — pick a role-matched branch to rebase onto",
+    handler: async (_args, ctx) => {
+      // Edge case: detached HEAD or non-git directory
+      const branch = await detectBranch();
+      if (!branch) {
+        ctx.ui.notify("Not on a branch (detached HEAD or not a git repo). Aborting.", "warning");
+        return;
+      }
+      const currentBranch = branch;
+
+      // List all local branches
+      let allBranches: string[] = [];
+      try {
+        const result = await pi.exec("git", ["branch", "--format", "%(refname:short)"]);
+        allBranches = result.stdout.trim().split("\n").filter(Boolean);
+      } catch {
+        ctx.ui.notify("Failed to list git branches.", "error");
+        return;
+      }
+
+      // Filter to role-matched branches, excluding current
+      const candidates: string[] = [];
+      for (const b of allBranches) {
+        if (b === currentBranch) continue;
+        if (detectRole(b, config)) candidates.push(b);
+      }
+
+      // Edge case: no other role-matched branches
+      if (candidates.length === 0) {
+        ctx.ui.notify("No other role-matched branches to rebase onto.", "info");
+        return;
+      }
+
+      // Get latest commit info for each candidate
+      interface CandidateInfo {
+        branch: string;
+        timestamp: number;
+        abbrev: string;
+        subject: string;
+      }
+      const infos: CandidateInfo[] = [];
+      for (const b of candidates) {
+        try {
+          const result = await pi.exec("git", [
+            "log", "--format=%ct %h %s", "-1", b,
+          ]);
+          const line = result.stdout.trim();
+          if (!line) continue;
+          const space1 = line.indexOf(" ");
+          const space2 = line.indexOf(" ", space1 + 1);
+          if (space1 === -1 || space2 === -1) continue;
+          const timestamp = parseInt(line.slice(0, space1), 10);
+          const abbrev = line.slice(space1 + 1, space2);
+          const subject = line.slice(space2 + 1);
+          infos.push({ branch: b, timestamp, abbrev, subject });
+        } catch {
+          // skip branches we can't read
+        }
+      }
+
+      if (infos.length === 0) {
+        ctx.ui.notify("Could not determine latest commits for candidates.", "error");
+        return;
+      }
+
+      // Sort by commit timestamp descending (most recent first)
+      infos.sort((a, b) => b.timestamp - a.timestamp);
+
+      // Require TUI mode
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/hatr requires TUI mode", "warning");
+        return;
+      }
+
+      // Build select items with: "branchname  <abbrev> subject"
+      const selectItems: SelectItem[] = infos.map((c) => {
+        const maxSubjectLen = 50;
+        const subject =
+          c.subject.length > maxSubjectLen
+            ? c.subject.slice(0, maxSubjectLen) + "…"
+            : c.subject;
+        return {
+          value: c.branch,
+          label: `${c.branch}  \x1b[90m${c.abbrev} ${subject}\x1b[0m`,
+        };
+      });
+
+      const result = await ctx.ui.custom<string | null>(
+        (tui, theme, _kb, done) => {
+          const container = new Container();
+
+          container.addChild(
+            new DynamicBorder((s: string) => theme.fg("accent", s)),
+          );
+
+          container.addChild(
+            new Text(theme.fg("accent", theme.bold("Rebase Branch")), 1, 0),
+          );
+
+          const selectList = new SearchableSelectList(selectItems, Math.min(selectItems.length, 20), {
+            selectedPrefix: (t) => theme.fg("accent", t),
+            selectedText: (t) => theme.fg("accent", t),
+            description: (t) => theme.fg("muted", t),
+            scrollInfo: (t) => theme.fg("dim", t),
+            noMatch: (t) => theme.fg("warning", t),
+          });
+
+          selectList.onSelect = (item) => {
+            if (item.value.startsWith("__header_")) return;
+            done(item.value);
+          };
+          selectList.onCancel = () => done(null);
+
+          container.addChild(selectList);
+
+          container.addChild(
+            new Text(
+              theme.fg("dim", "\u2191\u2193 navigate \u2022 enter select \u2022 esc cancel \u2022 type to search"),
+              1,
+              0,
+            ),
+          );
+
+          container.addChild(
+            new DynamicBorder((s: string) => theme.fg("accent", s)),
+          );
+
+          return {
+            render: (w) => container.render(w),
+            invalidate: () => container.invalidate(),
+            handleInput: (data) => {
+              selectList.handleInput(data);
+              tui.requestRender();
+            },
+          };
+        },
+        { overlay: true },
+      );
+
+      if (!result) {
+        ctx.ui.notify("Rebase cancelled.", "info");
+        return;
+      }
+
+      const selectedInfo = infos.find((c) => c.branch === result)!;
+
+      // Confirm before rebasing
+      const confirmed = await ctx.ui.confirm(
+        `Rebase ${currentBranch} onto ${result}? (${selectedInfo.abbrev} ${selectedInfo.subject})`,
+      );
+      if (!confirmed) {
+        ctx.ui.notify("Rebase cancelled.", "info");
+        return;
+      }
+
+      // Run the rebase
+      try {
+        const rebaseResult = await pi.exec("git", ["rebase", result]);
+        if (rebaseResult.code === 0) {
+          ctx.ui.notify(
+            `Rebase onto ${result} succeeded. Updated commit tree:`,
+            "info",
+          );
+          await showGitLog(ctx, 10);
+        } else {
+          ctx.ui.notify(
+            `Rebase onto ${result} failed:\n${rebaseResult.stderr}\n\nResolve conflicts manually, then run \`git rebase --continue\`.`,
+            "error",
+          );
+        }
+      } catch (e) {
+        ctx.ui.notify(
+          `Rebase onto ${result} failed: ${(e as Error).message}\n\nResolve conflicts manually, then run \`git rebase --continue\`.`,
+          "error",
+        );
+      }
+    },
+  });
+
   // -- Session lifecycle ----------------------------------------
 
   pi.on("session_start", async (event, ctx) => {
@@ -1207,10 +1491,16 @@ export default function (pi: ExtensionAPI) {
       ? `${roleIcon(currentRole)} ${currentRole}${usingFile}`
       : "\u2753 No matching role (read-only mode)";
 
+    const defaultInfo = [];
+    if (config.preTool) defaultInfo.push(`pre-tool: ${config.preTool.length} rule(s)`);
+    if (config.postTool) defaultInfo.push(`post-tool: ${config.postTool.length} rule(s)`);
+    const defaultLine = defaultInfo.length > 0 ? `default: ${defaultInfo.join(", ")}\n` : "";
+
     ctx.ui.notify(
       `${roleDisplay}\n` +
         `branch: ${currentBranch ?? "not a git repo"}\n` +
         `${desc ? `desc: ${desc}\n` : ""}` +
+        `${defaultLine}` +
         `roles: ${config.configFile}`,
       "info",
     );
@@ -1370,6 +1660,154 @@ If the user asks you to make changes, tell them to switch to an appropriate bran
       }
     }
 
+    // Config-driven tool rules: evaluate bash commands
+    if (isBash) {
+      const lowerRole = currentRole.toLowerCase();
+      const roleDef = config.roles[lowerRole] ?? config.roles[currentRole];
+      const rawCmd = ((event.input as { command?: string }).command ?? "").trim();
+      const cmd = stripCdPrefix(rawCmd, ctx.cwd, cwdAbsolute);
+
+      // -- Hardcoded safety guards (not overridable by roles.json) --
+
+      // Block pipe to any shell interpreter (arbitrary code execution vector)
+      if (/\|\s*(sh|bash|zsh|fish|dash|ksh|tcsh|csh)\b/.test(cmd)) {
+        return {
+          block: true,
+          reason:
+            "Piping to a shell interpreter is blocked for security. " +
+            "Use the `write` or `edit` tool to create or modify files.",
+        };
+      }
+
+      // Check output redirect to files via > or >> (write operation via bash)
+      const redirectMatch = cmd.match(/[\s>](>|>>)\s*([\w\/~.$].*)$/);
+      if (redirectMatch) {
+        const target = redirectMatch[2];
+        // Allow redirects to /tmp/ with confirmation (scratch space)
+        if (/^\/tmp\//.test(target)) {
+          const confirmed = await ctx.ui.confirm(
+            `Write to \`${target}\` via redirect? Confirm?`,
+          );
+          if (!confirmed) {
+            return { block: true, reason: "Redirect to /tmp cancelled." };
+          }
+        } else {
+          // All other redirect targets are blocked unconditionally
+          return {
+            block: true,
+            reason:
+              `Output redirect to \`${target}\` is blocked for security. ` +
+              `Use the \`write\` or \`edit\` tool instead. ` +
+              `Redirects to \`/tmp/...\` are allowed with confirmation.`,
+          };
+        }
+      }
+
+      // 1. Default pre-tool rules (evaluated before role-specific rules)
+      let matchedAny = false;
+      if (config.preTool) {
+        const result = evaluateToolRules(config.preTool, cmd);
+        if (result.matched) {
+          matchedAny = true;
+          if (!result.allowed) {
+            return {
+              block: true,
+              reason: result.reason ?? `Command \`${cmd}\` blocked by default pre-tool rule.`,
+            };
+          }
+          if (result.confirm) {
+            const confirmed = await ctx.ui.confirm(
+              result.reason ?? `Run bash command \`${cmd}\` (default pre-tool check)?`,
+            );
+            if (!confirmed) {
+              return { block: true, reason: "Command cancelled by user." };
+            }
+          }
+        }
+      }
+
+      // 2. Role-specific tool rules
+      if (roleDef?.tool !== undefined) {
+        const result = evaluateToolRules(roleDef.tool, cmd);
+        if (result.matched) {
+          matchedAny = true;
+          if (!result.allowed) {
+            return {
+              block: true,
+              reason: result.reason ?? `Command \`${cmd}\` blocked by tool rule for ${currentRole}.`,
+            };
+          }
+          if (result.confirm) {
+            const confirmed = await ctx.ui.confirm(
+              result.reason ?? `Run bash command \`${cmd}\` as ${currentRole}?`,
+            );
+            if (!confirmed) {
+              return { block: true, reason: "Command cancelled by user." };
+            }
+          }
+        }
+      }
+
+      // 3. Default post-tool rules (evaluated after role-specific rules pass)
+      if (config.postTool) {
+        for (const rule of config.postTool) {
+          if (!testRegex(rule.regex, cmd)) continue;
+          matchedAny = true;
+          if (rule.type === "block") {
+            return {
+              block: true,
+              reason: rule.reason ?? `Command \`${cmd}\` blocked by default post-tool rule.`,
+            };
+          }
+          if (rule.type === "confirm") {
+            const confirmed = await ctx.ui.confirm(
+              rule.reason ?? `Run bash command \`${cmd}\` (default post-tool check)?`,
+            );
+            if (!confirmed) {
+              return { block: true, reason: "Command cancelled by user." };
+            }
+          }
+          // "allow" → no-op, continue past post-tool
+        }
+      }
+
+      // 4. Role-specific post-tool rules (evaluated after default post-tool)
+      if (roleDef?.postTool) {
+        for (const rule of roleDef.postTool) {
+          if (!testRegex(rule.regex, cmd)) continue;
+          matchedAny = true;
+          if (rule.type === "block") {
+            return {
+              block: true,
+              reason: rule.reason ?? `Command \`${cmd}\` blocked by role post-tool rule for ${currentRole}.`,
+            };
+          }
+          if (rule.type === "confirm") {
+            const confirmed = await ctx.ui.confirm(
+              rule.reason ?? `Run bash command \`${cmd}\` (${currentRole} post-tool check)?`,
+            );
+            if (!confirmed) {
+              return { block: true, reason: "Command cancelled by user." };
+            }
+          }
+          // "allow" → no-op, continue
+        }
+      }
+
+      // 5. Safe default: if no rule matched in any stage, require confirmation
+      if (!matchedAny) {
+        const confirmed = await ctx.ui.confirm(
+          `Command \`${cmd}\` not covered by any tool rule. Confirm execution?`,
+        );
+        if (!confirmed) {
+          return { block: true, reason: "Command cancelled by user." };
+        }
+      }
+
+      // Tool rules passed (or no tool rules defined): allow bash
+      return;
+    }
+
     // Known roles: only intercept edit/write
     if (!isWrite) return;
 
@@ -1377,21 +1815,44 @@ If the user asks you to make changes, tell them to switch to an appropriate bran
     const path = normalisePath(rawPath, ctx.cwd, cwdAbsolute);
 
     const lowerRole = currentRole.toLowerCase();
+    const roleDef = config.roles[lowerRole] ?? config.roles[currentRole];
+
+    // Note: edit/write skip tool rules entirely — they use writablePaths instead.
+
+    // -- Config-driven writable path enforcement ---------------------
+
+    // Planner NN sequence validation (architectural guard — always applies)
+    if (lowerRole === "planner" && path.startsWith("todo/")) {
+      const nn = extractNN(path.replace("todo/", ""));
+      if (nn !== null && nn <= (await findMaxNN(ctx.cwd))) {
+        return {
+          block: true,
+          reason: `\uD83D\uDCCB Planner: NN must be > max in todo/ and report/. You used ${String(nn).padStart(2, "0")}. Use ${String((await findMaxNN(ctx.cwd)) + 1).padStart(2, "0")} or higher.`,
+        };
+      }
+    }
+
+    // Config-driven writablePaths: if defined and non-empty, use it
+    if (roleDef?.writablePaths !== undefined && roleDef.writablePaths.length > 0) {
+      if (isWritablePath(path, roleDef.writablePaths)) return;
+      const allowed = roleDef.writablePaths
+        .map((e) =>
+          e.path === ""
+            ? `*.${e.extension}`
+            : `${e.path}/${e.extension ? `*.${e.extension}` : "*"}`,
+        )
+        .join(", ");
+      return {
+        block: true,
+        reason: `\uD83D\uDD12 ${currentRole}: can only write to ${allowed}. Blocked: ${rawPath}`,
+      };
+    }
+
+    // Fallback: hardcoded per-role path restrictions
 
     // Planner: only todo/, plan/, docs/*.md
     if (lowerRole === "planner") {
-      if (isInside(path, ["todo", "plan", "docs"])) {
-        if (path.startsWith("todo/")) {
-          const nn = extractNN(path.replace("todo/", ""));
-          if (nn !== null && nn <= (await findMaxNN(ctx.cwd))) {
-            return {
-              block: true,
-              reason: `\uD83D\uDCCB Planner: NN must be > max in todo/ and report/. You used ${String(nn).padStart(2, "0")}. Use ${String((await findMaxNN(ctx.cwd)) + 1).padStart(2, "0")} or higher.`,
-            };
-          }
-        }
-        return;
-      }
+      if (isInside(path, ["todo", "plan", "docs"])) return;
       return {
         block: true,
         reason: `\uD83D\uDCCB Planner: can only write to todo/, plan/, and docs/*.md. Blocked: ${rawPath}`,

package/lib/tool-enforcement.ts

@@ -0,0 +1,91 @@
+/**
+ * Tool enforcement engine — reusable by extensions and packages.
+ *
+ * Provides types and functions for config-driven tool rule evaluation.
+ *
+ * Exports:
+ *   - RegexObj, ToolRule (types)
+ *   - testRegex()      — recursive regex matching (string / any / all)
+ *   - evaluateToolRules()  — first-match-wins rule evaluation
+ */
+
+// -- Types ---------------------------------------------------------
+
+export interface RegexObj {
+  type: "any" | "all";
+  regex: (string | RegexObj)[];
+}
+
+export interface ToolRule {
+  type: "allow" | "block" | "confirm";
+  regex: string | RegexObj;
+  reason?: string;
+}
+
+// -- Regex matching ------------------------------------------------
+
+/**
+ * Recursively test a command against a regex pattern.
+ *
+ * - **string**: direct `new RegExp(regex).test(command)`, invalid patterns skipped
+ * - **`{ type: "any", regex: [...] }`**: true if **any** sub-regex matches (OR)
+ * - **`{ type: "all", regex: [...] }`**: true if **all** sub-regexes match (AND)
+ *
+ * Sub-regexes can themselves be strings or nested `RegexObj` values.
+ */
+export function testRegex(regex: string | RegexObj, command: string): boolean {
+  if (typeof regex === "string") {
+    try {
+      return new RegExp(regex).test(command);
+    } catch {
+      return false;
+    }
+  }
+  // RegexObj
+  if (regex.type === "any") {
+    return regex.regex.some((r) => testRegex(r, command));
+  }
+  // type === "all"
+  return regex.regex.every((r) => testRegex(r, command));
+}
+
+// -- Rule evaluation -----------------------------------------------
+
+/**
+ * Evaluate a command against an ordered list of tool rules.
+ *
+ * **First matching rule wins**: if a rule matches and its type is `"allow"`,
+ * the command is permitted. If `"block"`, the command is denied with an
+ * optional reason. If `"confirm"`, the command requires user confirmation.
+ * If no rule matches, the command also requires user confirmation (safe default).
+ *
+ * @param rules - Array of `ToolRule` objects, or `undefined` (treated as "not configured")
+ * @param command - The string to test (bash command, tool name, etc.)
+ * @returns
+ *   - `{ allowed: true }` — command is permitted unconditionally
+ *   - `{ allowed: false, reason }` — command is denied
+ *   - `{ allowed: true, confirm: true, reason }` — command requires user confirmation
+ */
+export function evaluateToolRules(
+  rules: ToolRule[] | undefined,
+  command: string,
+): { allowed: boolean; confirm?: boolean; reason?: string; matched: boolean } {
+  if (!rules || rules.length === 0) {
+    // No rules defined or empty array = caller should fall back to hardcoded behaviour
+    return { allowed: true, matched: false };
+  }
+  for (const rule of rules) {
+    if (testRegex(rule.regex, command)) {
+      if (rule.type === "allow") {
+        return { allowed: true, matched: true };
+      }
+      if (rule.type === "confirm") {
+        return { allowed: true, confirm: true, reason: rule.reason, matched: true };
+      }
+      // block
+      return { allowed: false, reason: rule.reason, matched: true };
+    }
+  }
+  // No rule matched — caller should continue to next stage
+  return { allowed: true, matched: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@senomas/pi-git-hat",
-	"version": "0.2.2",
+	"version": "0.2.5",
 	"description": "Pi extension for role-based Git branch workflows — wear different hats by switching branches",
 	"type": "module",
 	"keywords": ["pi-package", "git", "workflow", "branching", "roles"],

package/roles/roles.json

@@ -1,9 +1,99 @@
 {
+  "default": {
+    "pre-tool": [
+      { "type": "allow", "regex": "^ls ", "reason": "List directory contents" },
+      { "type": "allow", "regex": "^find ", "reason": "Search for files" },
+      { "type": "allow", "regex": "^grep ", "reason": "Search text patterns" },
+      { "type": "allow", "regex": "^rg ", "reason": "Recursive text search" },
+      { "type": "allow", "regex": "^cat ", "reason": "Concatenate/read files" },
+      { "type": "allow", "regex": "^head ", "reason": "Output first lines" },
+      { "type": "allow", "regex": "^tail ", "reason": "Output last lines" },
+      { "type": "allow", "regex": "^wc ", "reason": "Word/line/byte count" },
+      { "type": "allow", "regex": "^sort ", "reason": "Sort lines" },
+      { "type": "allow", "regex": "^uniq ", "reason": "Filter repeated lines" },
+      { "type": "allow", "regex": "^jq ", "reason": "JSON query" },
+      { "type": "allow", "regex": "^dirname ", "reason": "Strip path components" },
+      { "type": "allow", "regex": "^basename ", "reason": "Strip directory from path" },
+      { "type": "allow", "regex": "^pwd$", "reason": "Print working directory" },
+      { "type": "allow", "regex": "^echo ", "reason": "Print text" },
+      { "type": "allow", "regex": "^printf ", "reason": "Formatted print" },
+      { "type": "allow", "regex": "^which ", "reason": "Locate a command" },
+      { "type": "allow", "regex": "^whoami$", "reason": "Print current user" },
+      { "type": "allow", "regex": "^uname ", "reason": "Print system info" },
+      { "type": "allow", "regex": "^hostname$", "reason": "Print host name" },
+      { "type": "allow", "regex": "^date ", "reason": "Show date/time" },
+      { "type": "allow", "regex": "^env$", "reason": "Print environment" },
+      { "type": "allow", "regex": "^true$", "reason": "No-op success" },
+      { "type": "allow", "regex": "^false$", "reason": "No-op failure" },
+      { "type": "allow", "regex": "^yes ", "reason": "Repeat output" },
+      { "type": "allow", "regex": "^time ", "reason": "Time a command" },
+      { "type": "allow", "regex": "^seq ", "reason": "Print number sequence" },
+      { "type": "allow", "regex": "^sleep ", "reason": "Pause execution" },
+      { "type": "allow", "regex": "^read ", "reason": "Read file contents" },
+      { "type": "allow", "regex": "^diff ", "reason": "Compare files" }
+    ],
+    "post-tool": [
+      { "type": "confirm", "regex": "^git push\\b", "reason": "Push to remote?" },
+      { "type": "confirm", "regex": "^git checkout\\b", "reason": "Switch branches?" },
+      { "type": "confirm", "regex": "^git switch\\b", "reason": "Switch branches?" },
+      { "type": "allow", "regex": "^git\\b", "reason": "Git commands" }
+    ]
+  },
   "roles": {
-    "planner":      { "pattern": "^plan(-|/|$)", "description": "Plan work by creating todo/plan files" },
-    "implementor":  { "pattern": "^(implementor$|feature|feat|impl$|work$)(-|/|$)", "description": "Feature/impl/work branches" },
-    "reviewer":     { "pattern": "^review(-|/|$)", "description": "Review implementations against todos" },
-    "admin":        { "pattern": "^(main|master)$", "description": "Project configuration and docs" },
-    "researcher":   { "pattern": "^research(-|/|$)", "description": "Research topics and document findings" }
+    "planner": {
+      "pattern": "^plan(-|/|$)",
+      "description": "Plan work by creating todo/plan files",
+      "tool": [
+        { "type": "allow", "regex": "^web_", "reason": "Web search" },
+        { "type": "block", "regex": ".*", "reason": "Planner: block." }
+      ],
+      "writablePaths": [
+        { "path": "todo", "extension": "md" },
+        { "path": "plan", "extension": "md" },
+        { "path": "docs", "extension": "md" }
+      ]
+    },
+    "implementor": {
+      "pattern": "^(implementor$|feature|feat|impl$|work$)(-|/|$)",
+      "description": "Feature/impl/work branches",
+      "tool": [
+      ]
+    },
+    "reviewer": {
+      "pattern": "^review(-|/|$)",
+      "description": "Review implementations against todos",
+      "tool": [
+      ],
+      "post-tool": [
+        { "type": "block", "regex": ".*", "reason": "Reviewer: block." }
+      ],
+      "writablePaths": [
+        { "path": "todo" }
+      ]
+    },
+    "admin": {
+      "pattern": "^(main|master)$",
+      "description": "Project configuration and docs",
+      "tool": [
+      ],
+      "writablePaths": [
+        { "path": ".pi" },
+        { "path": "", "extension": "md" }
+      ]
+    },
+    "researcher": {
+      "pattern": "^research(-|/|$)",
+      "description": "Research topics and document findings",
+      "tool": [
+        { "type": "allow", "regex": "^web_", "reason": "Web research" }
+      ],
+      "post-tool": [
+        { "type": "block", "regex": ".*", "reason": "Reviewer: block." }
+      ],
+      "writablePaths": [
+        { "path": "docs", "extension": "md"  },
+        { "path": "", "extension": "md" }
+      ]
+    }
   }
 }