@orchestrator-claude/definitions 3.34.0 → 3.35.0

package/hooks/agent-git-guard.ts

@@ -0,0 +1,166 @@
+/**
+ * agent-git-guard.ts — PreToolUse[Bash] hook (TD-169 enforcement)
+ *
+ * BLOCKS `git push`, `git merge`, and `gh pr merge` when the command is run by a
+ * SUB-AGENT, while ALLOWING the main orchestrator (main conversation) to run them.
+ *
+ * Mechanism: Claude Code injects `agent_id` into PreToolUse stdin ONLY when the
+ * hook fires inside a sub-agent call (see hook-reference: "Present only when the
+ * hook fires inside a subagent call"). workflow-guard.ts uses the same signal for
+ * Write/Edit (the sub-agent branch of decideWorkflowGuardAction). This hook extends
+ * it to the git escape-to-remote path.
+ *
+ * Why this exists: S288 governance breach — an `implementer` sub-agent autonomously
+ * committed + pushed + `gh pr merge`'d an unauthorized FK-drop to main. Prose
+ * commit-policy in dispatch prompts is unenforced (agents hold Bash + gh). This hook
+ * is the enforcement layer (cf. workflow-guard model; S288-handoff §TD-169).
+ *
+ * Scope: push / merge ONLY — NOT commit. A local commit by a sub-agent is recoverable
+ * and is sometimes legitimate (orchestrator Commit Policy option b). Push/merge to a
+ * remote is the unrecoverable breach vector, so that is what we deny.
+ *
+ * RFC-040 TD-204 §⑤-A (S366) — Classe-A asset-safety classification:
+ * this gate is classified Classe-A (same family as workflow-guard.ts's
+ * `.orchestrator`-registration and workflow-active checks — asset-safety
+ * gates that must remain intact everywhere, never silently no-op). UNLIKE
+ * workflow-guard.ts, this gate's decision (evaluateGitGuard) is a pure
+ * function of (command, agentId, agentType) ONLY — it never inspects any
+ * file_path or cwd. A sub-agent attempting `git push`/`git merge`/`gh pr
+ * merge` is denied identically no matter which project's working tree the
+ * Bash command runs against. This makes it **globally cwd-safe already**:
+ * no TD-204 ⑤-A remediation (project-root resolution / `.unmanaged`
+ * sentinel / unregistered-path branching) is needed here — there is no
+ * path-dependent branch to make cwd-scoped-safe in the first place. See
+ * tests/unit/hooks/agent-git-guard-path-invariance.test.ts for the
+ * property-style proof.
+ *
+ * Decision:
+ *   - agent_id absent (main orchestrator)        → silent pass-through (allow)
+ *   - agent_id present + push/merge/gh-pr-merge  → DENY
+ *   - agent_id present + commit/read-only/other  → silent pass-through (allow)
+ *   - SKIP_AGENT_GIT_GUARD=true                  → allow (escape hatch, logged)
+ *   - parse error / empty stdin                  → fail-open (allow)
+ */
+
+import { log, readStdin, getField, outputPreToolUse } from './lib/api-client.js';
+
+const HOOK = 'AGENT-GIT-GUARD';
+
+// ─────────────────────────────────────────────────────────────
+// Dependency injection interface (enables testing without IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  output: (opts: { decision: 'allow' | 'deny'; reason?: string; context?: string }) => void;
+  log: (prefix: string, msg: string) => void;
+  getEnv: (key: string) => string | undefined;
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  output: outputPreToolUse,
+  log,
+  getEnv: (key) => process.env[key],
+};
+
+// ─────────────────────────────────────────────────────────────
+// Pure helpers (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+// `(\s|$)` after the verb avoids matching plumbing like `git merge-base`.
+const PUSH = /\bgit\s+push(\s|$)/;
+const MERGE = /\bgit\s+merge(\s|$)/;
+const GH_PR_MERGE = /\bgh\s+pr\s+merge(\s|$)/;
+
+/**
+ * True when the bash command performs a push or merge (the escape-to-remote
+ * operations owned exclusively by the main orchestrator). Excludes `git merge-base`
+ * (read-only plumbing), `git commit`, and read-only git/gh commands.
+ */
+export function commandIsPushOrMerge(command: string): boolean {
+  return PUSH.test(command) || MERGE.test(command) || GH_PR_MERGE.test(command);
+}
+
+export interface GuardResult {
+  decision: 'allow' | 'deny';
+  reason?: string;
+}
+
+/**
+ * Pure decision: deny only when a sub-agent (agentId present) attempts a
+ * push/merge. Empty agentId == main orchestrator == always allowed.
+ *
+ * Path-independent by construction (RFC-040 TD-204 §⑤-A, Classe-A): the
+ * signature takes no file_path/cwd input, so the decision is provably the
+ * same for every project's working tree — globally cwd-safe without any
+ * project-root resolution.
+ */
+export function evaluateGitGuard(
+  command: string,
+  agentId: string,
+  agentType?: string
+): GuardResult {
+  if (!agentId) return { decision: 'allow' }; // main orchestrator owns git
+  if (!commandIsPushOrMerge(command)) return { decision: 'allow' }; // commit/read-only fine
+
+  const who = agentType && agentType.length > 0 ? `Sub-agent '${agentType}'` : 'Sub-agent';
+  return {
+    decision: 'deny',
+    reason:
+      `[AGENT-GIT-GUARD] ${who} is not permitted to run git push / git merge / gh pr merge. ` +
+      `Per RFC-022 + TD-169, push and merge are owned EXCLUSIVELY by the main orchestrator ` +
+      `(the main conversation). Make your changes locally and return them in your report — ` +
+      `the orchestrator reviews, then pushes/merges. (Prevents the S288 unauthorized merge-to-main breach.)`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Core logic (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const { readStdin, output, log, getEnv } = deps;
+
+  const stdin = await readStdin();
+
+  const command =
+    (getField(stdin, 'tool_input.command') as string | undefined) ||
+    (getField(stdin, 'command') as string | undefined) ||
+    '';
+
+  const agentId = getField(stdin, 'agent_id');
+  const agentType = getField(stdin, 'agent_type');
+
+  // Escape hatch (parity with workflow-guard SKIP_*). Process-env only — a
+  // sub-agent's transient shell env does not persist into the hook process.
+  if (getEnv('SKIP_AGENT_GIT_GUARD') === 'true') {
+    log(HOOK, `BYPASS (SKIP_AGENT_GIT_GUARD): ${command.slice(0, 60)}`);
+    return; // silent pass-through
+  }
+
+  const result = evaluateGitGuard(command, agentId, agentType);
+
+  if (result.decision === 'deny') {
+    log(HOOK, `DENY (agent=${agentType || 'unknown'}): ${command.slice(0, 80)}`);
+    output({ decision: 'deny', reason: result.reason });
+    return;
+  }
+
+  // Allow path is a silent pass-through so we never clobber the context that the
+  // sibling Bash hook (verification-before-completion) injects.
+  log(
+    HOOK,
+    `ALLOW (agent=${agentId ? agentType || 'sub-agent' : 'main'}): ${command.slice(0, 60)}`
+  );
+}
+
+// ─────────────────────────────────────────────────────────────
+// Entry point (production use)
+// ─────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
+main().catch(() => process.exit(0));

package/hooks/hooks.json

@@ -4,59 +4,74 @@
       {
         "matcher": "startup|resume",
         "hooks": [
-          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs", "timeout": 10000 },
-          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/sprint-registry.mjs", "timeout": 5000 }
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"", "timeout": 10000 },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/sprint-registry.mjs\"", "timeout": 5000 }
         ]
       }
     ],
     "UserPromptSubmit": [
       {
         "matcher": "",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt.mjs", "timeout": 10000 }]
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt.mjs\"", "timeout": 10000 }]
       }
     ],
     "PreToolUse": [
       {
-        "matcher": "mcp__orchestrator-tools__advancePhase",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/gate-guardian.mjs", "timeout": 15000 }]
+        "matcher": "mcp__(plugin_orchestrator_)?orchestrator-tools__advancePhase",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gate-guardian.mjs\"", "timeout": 15000 }]
       },
       {
         "matcher": "Write|Edit",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/workflow-guard.mjs", "timeout": 10000 }]
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/workflow-guard.mjs\"", "timeout": 10000 }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/verification-before-completion.mjs\"", "timeout": 5000 },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/agent-git-guard.mjs\"", "timeout": 5000 }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-agent-dispatch.mjs\"", "timeout": 5000 }]
+      },
+      {
+        "matcher": "mcp__plugin_playwright_playwright__browser_take_screenshot|mcp__plugin_playwright_playwright__browser_pdf_save",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/playwright-output-guard.mjs\"", "timeout": 5000 }]
       }
     ],
     "SubagentStart": [
       {
-        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.mjs", "timeout": 10000 }]
+        "matcher": "(orchestrator:)?(implementer|specifier|planner|task-generator|reviewer|researcher)",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.mjs\"", "timeout": 10000 }]
       }
     ],
     "SubagentStop": [
       {
-        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop.mjs", "timeout": 30000 }]
+        "matcher": "(orchestrator:)?(implementer|specifier|planner|task-generator|reviewer|researcher)",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop.mjs\"", "timeout": 30000 }]
       }
     ],
     "Stop": [
       {
         "matcher": "",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/dangling-guard.mjs", "timeout": 15000 }]
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/dangling-guard.mjs\"", "timeout": 15000 }]
       }
     ],
     "PostToolUse": [
       {
         "matcher": "",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/mailbox-listener.mjs", "timeout": 5000 }]
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/mailbox-listener.mjs\"", "timeout": 5000 }]
       },
       {
-        "matcher": "mcp__orchestrator-tools__advancePhase",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-implement.mjs", "timeout": 15000 }]
+        "matcher": "mcp__(plugin_orchestrator_)?orchestrator-tools__advancePhase",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-implement.mjs\"", "timeout": 15000 }]
       }
     ],
     "PostCompact": [
       {
         "matcher": "",
-        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-compact.mjs", "timeout": 5000 }]
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-compact.mjs\"", "timeout": 5000 }]
       }
     ]
   }

package/hooks/playwright-output-guard.mjs

@@ -0,0 +1,136 @@
+import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
+
+// hooks/playwright-output-guard.ts
+import { dirname as dirname3, isAbsolute, normalize, resolve } from "node:path";
+
+// hooks/lib/api-client.ts
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../project-root-resolver/dist/index.js
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+function resolveProjectRoot(cwd, sentinel = ".orchestrator") {
+  let currentDir = cwd;
+  for (; ; ) {
+    if (existsSync(join(currentDir, sentinel))) {
+      return currentDir;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+// hooks/lib/api-client.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var PROJECT_ROOT = join2(__dirname, "..", "..", "..");
+var STATE_DIR = join2(PROJECT_ROOT, ".orchestrator", ".state");
+var JWT_CACHE = join2(STATE_DIR, "jwt-token");
+var DEBUG_LOG = join2(STATE_DIR, "hook-debug.log");
+mkdirSync(STATE_DIR, { recursive: true });
+var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
+var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";
+var PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+function resolveHookProjectRoot(cwd) {
+  return resolveProjectRoot(cwd);
+}
+function log(prefix, msg) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}
+`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+  }
+}
+var LAST_COMPLETED_FILE = join2(STATE_DIR, "last-completed-workflow.json");
+var LAST_COMPLETED_TTL_MS = 60 * 60 * 1e3;
+var INVOCATIONS_DIR = join2(STATE_DIR, "invocations");
+var INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1e3;
+var DISPATCH_INTENT_DIR = join2(STATE_DIR, "dispatch-intent");
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function getField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = current[part];
+  }
+  return current != null ? String(current) : "";
+}
+function outputPreToolUse(opts) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: opts.decision,
+      ...opts.reason && { permissionDecisionReason: opts.reason },
+      ...opts.context && { additionalContext: opts.context }
+    }
+  };
+  console.log(JSON.stringify(output));
+}
+
+// hooks/playwright-output-guard.ts
+var HOOK = "PLAYWRIGHT-OUTPUT-GUARD";
+var PROJECT_ROOT2 = process.env.CLAUDE_PROJECT_DIR ?? resolveHookProjectRoot(process.cwd()) ?? process.cwd();
+var GUIDANCE = 'Playwright Output Guard: screenshots n\xE3o podem cair na raiz do repo (auto-checkpoint os varre \u2014 recorr\xEAncia S266-S268). Use `filename: ".playwright-mcp/<nome>.png"` (descart\xE1vel, gitignored), `filename: ".cobaia-evidence/<sess\xE3o>/<nome>.png"` (evid\xEAncia a versionar), ou omita `filename` (default j\xE1 vai para .playwright-mcp/).';
+function evaluateFilename(filename) {
+  if (!filename) return { decision: "allow" };
+  const resolved = isAbsolute(filename) ? normalize(filename) : resolve(PROJECT_ROOT2, filename);
+  const dir = dirname3(resolved);
+  if (dir === PROJECT_ROOT2) {
+    return { decision: "deny", reason: GUIDANCE };
+  }
+  if (!resolved.startsWith(PROJECT_ROOT2 + "/") && !isAbsolute(filename)) {
+    return { decision: "deny", reason: GUIDANCE };
+  }
+  return { decision: "allow" };
+}
+var defaultDeps = {
+  readStdin,
+  output: outputPreToolUse,
+  log
+};
+async function mainWithDeps(deps) {
+  const stdin = await deps.readStdin();
+  const filename = getField(stdin, "tool_input.filename");
+  const result = evaluateFilename(filename || void 0);
+  deps.log(HOOK, `filename=${filename || "(none)"} decision=${result.decision}`);
+  if (result.decision === "deny") {
+    deps.output({ decision: "deny", reason: result.reason });
+    return;
+  }
+  deps.output({
+    decision: "allow",
+    ...filename ? {} : {
+      context: "[PLAYWRIGHT-OUTPUT-GUARD] sem filename: output em .playwright-mcp/ (gitignored)."
+    }
+  });
+}
+async function main() {
+  await mainWithDeps(defaultDeps);
+}
+main().catch(() => process.exit(0));
+export {
+  PROJECT_ROOT2 as PROJECT_ROOT,
+  evaluateFilename,
+  mainWithDeps
+};

package/hooks/playwright-output-guard.ts

@@ -0,0 +1,130 @@
+/**
+ * playwright-output-guard.ts — PreToolUse[browser_take_screenshot] hook (S269 item g)
+ *
+ * Problema: @playwright/mcp resolve `filename` contra o WORKSPACE ROOT
+ * (workspaceFile em packages/playwright-core/src/tools/backend/context.ts),
+ * não contra o outputDir. Filenames sem diretório caem na raiz do repo e o
+ * auto-checkpoint (`git add -A`) varre os PNGs para dentro de commits —
+ * recorrência observada em S266/S267/S268.
+ *
+ * Fix em camadas:
+ *   1. Este hook NEGA filenames que resolveriam para a raiz do projeto,
+ *      instruindo o agente a usar `.playwright-mcp/` (gitignored) ou
+ *      `.cobaia-evidence/<sessão>/` (evidência versionável).
+ *   2. `.gitignore` com `/*.png` etc. como cinto-e-suspensório.
+ *
+ * Política:
+ *   - sem filename            → ALLOW (default = <cwd>/.playwright-mcp/, gitignored)
+ *   - filename em subdiretório → ALLOW
+ *   - filename bare / ./x.png / absoluto-na-raiz / traversal → DENY
+ *   - stdin não-parseável     → ALLOW (fail-open: nunca bloquear por infra)
+ */
+
+import { dirname, isAbsolute, normalize, resolve } from 'node:path';
+import {
+  log,
+  readStdin,
+  getField,
+  outputPreToolUse,
+  resolveHookProjectRoot,
+} from './lib/api-client.js';
+
+const HOOK = 'PLAYWRIGHT-OUTPUT-GUARD';
+
+/**
+ * Raiz do projeto contra a qual `filename` é resolvido.
+ *
+ * ⚠️ NÃO derive de `__filename` (era o bug, S396/RFC-040 §18.12): sob o modelo
+ * de distribuição por plugin (§18) este arquivo roda a partir de
+ * `~/.claude/plugins/cache/<marketplace>/orchestrator/<versão>/hooks/`, então
+ * `dirname(__filename)/../..` resolveria para o CACHE DO PLUGIN em vez do repo
+ * do usuário. O guard não quebraria (fail-open), mas `dir === PROJECT_ROOT`
+ * nunca casaria — viraria um NO-OP SILENCIOSO, a pior falha possível para um
+ * gate. Cadeia de resolução, do mais autoritativo ao último recurso:
+ *   1. `CLAUDE_PROJECT_DIR` — injetado pelo harness, correto por construção;
+ *   2. walk-up pelo sentinel `.orchestrator` (primitivo RFC-040 C1);
+ *   3. `process.cwd()` — hooks rodam com cwd = diretório do projeto.
+ */
+export const PROJECT_ROOT =
+  process.env.CLAUDE_PROJECT_DIR ?? resolveHookProjectRoot(process.cwd()) ?? process.cwd();
+
+export interface GuardDecision {
+  decision: 'allow' | 'deny';
+  reason?: string;
+}
+
+const GUIDANCE =
+  'Playwright Output Guard: screenshots não podem cair na raiz do repo (auto-checkpoint os varre — recorrência S266-S268). ' +
+  'Use `filename: ".playwright-mcp/<nome>.png"` (descartável, gitignored), ' +
+  '`filename: ".cobaia-evidence/<sessão>/<nome>.png"` (evidência a versionar), ' +
+  'ou omita `filename` (default já vai para .playwright-mcp/).';
+
+/**
+ * Avalia o filename pedido pelo agente.
+ * DENY quando o arquivo resolveria para a raiz do projeto (ou acima dela).
+ */
+export function evaluateFilename(filename: string | undefined): GuardDecision {
+  if (!filename) return { decision: 'allow' };
+
+  const resolved = isAbsolute(filename) ? normalize(filename) : resolve(PROJECT_ROOT, filename);
+
+  const dir = dirname(resolved);
+
+  // Cairia exatamente na raiz do projeto → DENY
+  if (dir === PROJECT_ROOT) {
+    return { decision: 'deny', reason: GUIDANCE };
+  }
+
+  // Traversal para fora do projeto → DENY (o próprio MCP também negaria,
+  // mas aqui damos guidance acionável em vez de erro críptico)
+  if (!resolved.startsWith(PROJECT_ROOT + '/') && !isAbsolute(filename)) {
+    return { decision: 'deny', reason: GUIDANCE };
+  }
+
+  return { decision: 'allow' };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Dependency injection (testável sem IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  output: (opts: { decision: 'allow' | 'deny'; reason?: string; context?: string }) => void;
+  log: (prefix: string, msg: string) => void;
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  output: outputPreToolUse,
+  log,
+};
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const stdin = await deps.readStdin();
+  const filename = getField(stdin, 'tool_input.filename');
+
+  const result = evaluateFilename(filename || undefined);
+  deps.log(HOOK, `filename=${filename || '(none)'} decision=${result.decision}`);
+
+  if (result.decision === 'deny') {
+    deps.output({ decision: 'deny', reason: result.reason });
+    return;
+  }
+
+  deps.output({
+    decision: 'allow',
+    ...(filename
+      ? {}
+      : {
+          context:
+            '[PLAYWRIGHT-OUTPUT-GUARD] sem filename: output em .playwright-mcp/ (gitignored).',
+        }),
+  });
+}
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
+main().catch(() => process.exit(0));