terramend 0.2.0

package/src/agents/claudePretoolGate.test.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION } from "#app/agents/claudePretoolGate";
+
+// Tripwire for the subagent gate's load-bearing assumption: claude-code
+// populates `agent_id` in the PreToolUse hook payload for subagent tool calls
+// (the gate fails OPEN for subagents otherwise). claude-code ships as a native
+// binary, so we can't assert the behavior statically — instead we pin the
+// verified version and fail CI on any bump, forcing a human to re-verify
+// `createBaseHookInput` before updating the pin + the constant together.
+describe("subagent gate ↔ claude-code agent_id contract", () => {
+  const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8")) as {
+    devDependencies?: Record<string, string>;
+    dependencies?: Record<string, string>;
+  };
+
+  it("pinned @anthropic-ai/claude-code matches the verified version", () => {
+    const pinned =
+      pkg.devDependencies?.["@anthropic-ai/claude-code"] ??
+      pkg.dependencies?.["@anthropic-ai/claude-code"];
+    expect(
+      pinned,
+      "claude-code was bumped: re-verify that subagent tool calls still populate " +
+        "`agent_id` in the PreToolUse hook (createBaseHookInput) BEFORE updating " +
+        "CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION — the subagent gate fails OPEN otherwise.",
+    ).toBe(CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION);
+  });
+});

package/src/agents/claudePretoolGate.ts

@@ -0,0 +1,173 @@
+/**
+ * Claude Code `PreToolUse` hook source — written into `ctx.tmpdir` at runtime
+ * and registered via a tmpdir-scoped `settings.json` referenced by
+ * `--settings <path>` (see action/agents/claude.ts).
+ *
+ * Closes the subagent → state-mutating MCP tool path that motivated the
+ * 2026-05-18 zed-industries/cloud incident (`reviewfrog` lens called
+ * `checkout_pr` mid-review and the orchestrator's next push clobbered an
+ * unrelated branch). Pairs with the `tool.execute.before` hook in
+ * action/agents/opencodePlugin.ts; both runtimes share the deny list at
+ * action/agents/subagentToolGates.ts.
+ *
+ * PreToolUse hook contract (verified against yasasbanukaofficial/claude-code
+ * `src/utils/hooks/hooksConfigManager.ts` and `src/utils/hooks.ts`):
+ *   - stdin: JSON with `hook_event_name: "PreToolUse"`, `tool_name`,
+ *     `tool_input`, `tool_use_id`, `session_id`, `cwd`, `transcript_path`,
+ *     and crucially `agent_id` / `agent_type` populated when the call
+ *     originates from a subagent (set by the SDK when a Task/Agent
+ *     dispatches a tool — see `createBaseHookInput` in claude-code source).
+ *   - exit 0 → allow, no output shown
+ *   - exit 2 → block tool call AND show stderr to model (this is the path
+ *     we want for the deny case — the subagent gets a clear refusal it can
+ *     reason about and pick a different action)
+ *   - other → show stderr to user only, continue with tool call
+ *
+ * The hook itself is intentionally tiny: stdin → JSON → check `agent_id`
+ * presence + `tool_name` against the deny list → exit 0 or 2. No deps.
+ *
+ * Why the script source is a string template, not a separate `.ts` file
+ * shipped with the action: the action runs as a published npm package; at
+ * install time we don't have the source on disk in a stable place. Embedding
+ * the source into `dist/main.mjs` and writing it out per-run keeps the path
+ * inside `ctx.tmpdir` (where `--settings` can find it) and survives bundle
+ * minification.
+ */
+
+import { SUBAGENT_DENIED_TOOLS } from "#app/agents/subagentToolGates";
+
+/**
+ * The pinned `@anthropic-ai/claude-code` version against which the subagent
+ * gate's `agent_id` discriminator was last verified (see the contract notes in
+ * the gate source below). The gate fails OPEN for subagents if claude-code ever
+ * stops populating `agent_id` in the PreToolUse hook payload, so a version bump
+ * must be paired with a re-verification of `createBaseHookInput`.
+ *
+ * `claudePretoolGate.test.ts` asserts this equals the version pinned in
+ * `package.json` — that test fails on any bump, forcing the re-verification
+ * before the pin and this constant are updated together.
+ *
+ * 2.1.170 verified 2026-06-10 against the schema embedded in the shipped
+ * binary: the base hook input declares `agent_id` as optional with the
+ * describe-text "Present only when the hook fires from within a subagent
+ * (e.g., a tool called by an AgentTool worker). Absent for the main thread,
+ * even in --agent sessions." — exactly the discriminator the gate relies on.
+ */
+export const CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION = "2.1.170" as const;
+
+/**
+ * Source written to `<ctx.tmpdir>/terramend-pretool-gate.mjs`. Plain ESM,
+ * no TypeScript, no dependencies — node executes it directly via the
+ * `#!/usr/bin/env node` shebang and the executable bit set by the harness.
+ */
+export const CLAUDE_PRETOOL_GATE_FILENAME = "terramend-pretool-gate.mjs" as const;
+
+export const CLAUDE_PRETOOL_GATE_SOURCE = `#!/usr/bin/env node
+// AUTOGENERATED by Terramend. PreToolUse hook that hard-blocks state-mutating
+// MCP tool calls from subagents. See action/agents/claudePretoolGate.ts.
+
+const SUBAGENT_DENIED_TOOLS = new Set(${JSON.stringify(SUBAGENT_DENIED_TOOLS)});
+
+function stripMcpPrefix(toolName) {
+  if (toolName.startsWith("mcp__terramend__")) return toolName.slice("mcp__terramend__".length);
+  return toolName;
+}
+
+let stdin = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  stdin += chunk;
+});
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(stdin);
+  } catch {
+    // malformed input — exit non-blocking so the run continues. user-only
+    // stderr per the hook contract.
+    process.stderr.write("terramend-pretool-gate: malformed stdin JSON\\n");
+    process.exit(1);
+  }
+  const toolName = typeof payload?.tool_name === "string" ? payload.tool_name : "";
+  // claude-code populates agent_id whenever a tool call originates inside
+  // a Task/Agent subagent dispatch (createBaseHookInput in claude-code
+  // source). on the orchestrator's main thread agent_id is undefined.
+  // agent_type can be set on the orchestrator itself via --agent, so it's
+  // not a reliable subagent discriminator on its own; agent_id is.
+  // contract verified against @anthropic-ai/claude-code 2.1.170 (pinned in
+  // package.json; see CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION + the version
+  // tripwire in claudePretoolGate.test.ts); re-verify createBaseHookInput if
+  // that bumps — if agent_id ever stops being populated the gate fails OPEN.
+  const agentId = typeof payload?.agent_id === "string" ? payload.agent_id : "";
+  if (!agentId) process.exit(0);
+  const bare = stripMcpPrefix(toolName);
+  if (!SUBAGENT_DENIED_TOOLS.has(bare)) process.exit(0);
+  process.stderr.write(
+    "subagent attempted to call denied tool '" + bare + "'. " +
+      "subagents share the orchestrator's in-process working tree and toolState; " +
+      "state-changing MCP tools (checkout_pr, push_branch, create_pull_request_review, " +
+      "report_progress, etc.) are reserved for the orchestrator. " +
+      "report findings back to the orchestrator and let it perform the mutation.\\n"
+  );
+  process.exit(2);
+});
+`;
+
+/**
+ * Settings JSON shape registered via `claude --settings <path>`. The
+ * matcher `^mcp__terramend__` is treated as a regex by claude-code's
+ * `matchesPattern` helper (anything outside `[a-zA-Z0-9_|]` triggers the
+ * regex branch — verified in src/utils/hooks.ts), so this anchors at the
+ * start of the tool name and fires for every Terramend MCP tool. We narrow
+ * inside the script itself rather than declaring per-tool matchers because
+ * the deny list is the source of truth.
+ *
+ * The hook process inherits the parent's PATH, so `node` resolves to the
+ * runner's node binary; the `--settings` flag accepts either a path or a
+ * literal JSON string per claude-code source `src/main.tsx` (`Path to a
+ * settings JSON file or a JSON string`), but we use a path so the script
+ * and its config sit side-by-side under `ctx.tmpdir`.
+ *
+ * `execToolDenyRules` are the native exec tools (Bash/Monitor/REPL/Workflow +
+ * their `Agent(...)` forms) to deny at a settings-source rule — the
+ * authoritative, bypass-immune layer. `--disallowedTools` alone (a `cliArg`
+ * deny) was observed to leak under `--dangerously-skip-permissions`, so the
+ * deny is carried here too. Both consumers use both returned fields: the flag
+ * `--settings` JSON (covers non-CI runs) writes the whole object, and
+ * `buildManagedSettings` (CI, /etc managed settings) spreads `hooks` and folds
+ * `permissions.deny` into its richer deny list.
+ */
+export function buildClaudePretoolGateSettings(
+  scriptAbsolutePath: string,
+  execToolDenyRules: string[],
+): {
+  hooks: {
+    PreToolUse: Array<{
+      matcher: string;
+      hooks: Array<{ type: "command"; command: string; timeout?: number }>;
+    }>;
+  };
+  permissions: { deny: string[] };
+} {
+  return {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: "^mcp__terramend__",
+          hooks: [
+            {
+              type: "command",
+              // shell-quote-safe because tmpdir paths created via
+              // node:fs.mkdtempSync don't contain spaces, but pass via a
+              // literal that node parses as a single argv entry to be
+              // defensive against future tmpdir layout changes.
+              command: `node ${JSON.stringify(scriptAbsolutePath)}`,
+              timeout: 5,
+            },
+          ],
+        },
+      ],
+    },
+    permissions: { deny: execToolDenyRules },
+  };
+}

package/src/agents/gateServer.test.ts

@@ -0,0 +1,204 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { type GateServerHandle, startGateServer } from "#app/agents/gateServer";
+import type { AgentRunContext, PostRunIssues } from "#app/agents/shared";
+
+const collectPostRunIssuesMock = vi.fn();
+const shouldRunReflectionMock = vi.fn();
+
+vi.mock("#app/agents/postRun", () => ({
+  collectPostRunIssues: (ctx: unknown, opts: unknown) => collectPostRunIssuesMock(ctx, opts),
+  buildPostRunPrompt: (issues: PostRunIssues) => `post-run prompt: ${JSON.stringify(issues)}`,
+  buildLearningsReflectionPrompt: (path: string) => `reflection prompt for ${path}`,
+  shouldRunReflection: (mode: string | undefined) => shouldRunReflectionMock(mode),
+}));
+
+const noIssues: PostRunIssues = {};
+const dirtyIssues: PostRunIssues = { dirtyTree: "M src/main.tf" };
+
+function makeCtx(
+  toolState: { learningsFilePath?: string; selectedMode?: string } = {},
+): AgentRunContext {
+  return { toolState } as unknown as AgentRunContext;
+}
+
+let handle: GateServerHandle | undefined;
+
+async function startServer(ctx: AgentRunContext): Promise<GateServerHandle> {
+  handle = await startGateServer(ctx);
+  return handle;
+}
+
+function gateFetch(server: GateServerHandle, init?: RequestInit): Promise<Response> {
+  return fetch(server.url, {
+    headers: { authorization: `Bearer ${server.token}` },
+    ...init,
+  });
+}
+
+beforeEach(() => {
+  collectPostRunIssuesMock.mockResolvedValue(noIssues);
+  shouldRunReflectionMock.mockReturnValue(false);
+});
+
+afterEach(async () => {
+  if (handle) {
+    await handle[Symbol.asyncDispose]();
+    handle = undefined;
+  }
+  vi.clearAllMocks();
+});
+
+describe("gate server routing and auth", () => {
+  it("binds a loopback url and a uuid bearer token", async () => {
+    const server = await startServer(makeCtx());
+    expect(server.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/gates$/);
+    expect(server.token).toMatch(/^[0-9a-f-]{36}$/);
+  });
+
+  it("returns 404 for unknown paths and non-GET methods", async () => {
+    const server = await startServer(makeCtx());
+
+    const wrongPath = await fetch(server.url.replace("/gates", "/other"), {
+      headers: { authorization: `Bearer ${server.token}` },
+    });
+    expect(wrongPath.status).toBe(404);
+
+    const wrongMethod = await gateFetch(server, {
+      method: "POST",
+      headers: { authorization: `Bearer ${server.token}` },
+    });
+    expect(wrongMethod.status).toBe(404);
+  });
+
+  it("rejects missing or wrong bearer tokens without consuming budget", async () => {
+    collectPostRunIssuesMock.mockResolvedValue(dirtyIssues);
+    const server = await startServer(makeCtx());
+
+    const noAuth = await fetch(server.url);
+    expect(noAuth.status).toBe(403);
+
+    const wrongAuth = await fetch(server.url, {
+      headers: { authorization: "Bearer not-the-token" },
+    });
+    expect(wrongAuth.status).toBe(403);
+
+    // gate state was never read — the budget is untouched
+    expect(collectPostRunIssuesMock).not.toHaveBeenCalled();
+
+    // all MAX_POST_RUN_RETRIES blocks are still available afterwards
+    for (let i = 0; i < 3; i++) {
+      const res = await gateFetch(server);
+      expect(await res.json()).toMatchObject({ block: true });
+    }
+  });
+});
+
+describe("gate decisions", () => {
+  it("allows the stop when gates are clean and no reflection is pending", async () => {
+    const server = await startServer(makeCtx());
+    const res = await gateFetch(server);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("application/json");
+    expect(await res.json()).toEqual({ block: false });
+  });
+
+  it("blocks with the combined gate prompt while issues persist", async () => {
+    collectPostRunIssuesMock.mockResolvedValue(dirtyIssues);
+    const server = await startServer(makeCtx());
+
+    const res = await gateFetch(server);
+    const body = (await res.json()) as { block: boolean; reason: string };
+    expect(body.block).toBe(true);
+    expect(body.reason).toContain("post-run prompt:");
+    expect(body.reason).toContain("M src/main.tf");
+  });
+
+  it("allows the stop once the retry budget is exhausted (terminal hard-fail)", async () => {
+    collectPostRunIssuesMock.mockResolvedValue(dirtyIssues);
+    const server = await startServer(makeCtx());
+
+    for (let i = 0; i < 3; i++) {
+      const res = await gateFetch(server);
+      expect(await res.json()).toMatchObject({ block: true });
+    }
+
+    const exhausted = await gateFetch(server);
+    expect(await exhausted.json()).toEqual({ block: false });
+  });
+
+  it("nudges summaryStale exactly once, then skips it on later collections", async () => {
+    collectPostRunIssuesMock
+      .mockResolvedValueOnce({ summaryStale: { filePath: "/tmp/summary.md" } })
+      .mockResolvedValue(noIssues);
+    const server = await startServer(makeCtx());
+
+    const first = await gateFetch(server);
+    expect(await first.json()).toMatchObject({ block: true });
+    expect(collectPostRunIssuesMock).toHaveBeenLastCalledWith(expect.anything(), {
+      skipSummaryStale: false,
+    });
+
+    const second = await gateFetch(server);
+    expect(await second.json()).toEqual({ block: false });
+    expect(collectPostRunIssuesMock).toHaveBeenLastCalledWith(expect.anything(), {
+      skipSummaryStale: true,
+    });
+  });
+
+  it("delivers the reflection nudge once when gates are clean", async () => {
+    shouldRunReflectionMock.mockReturnValue(true);
+    const server = await startServer(
+      makeCtx({ learningsFilePath: "/tmp/learnings.md", selectedMode: "Remediate" }),
+    );
+
+    const first = await gateFetch(server);
+    const body = (await first.json()) as { block: boolean; reason: string };
+    expect(body.block).toBe(true);
+    expect(body.reason).toBe("reflection prompt for /tmp/learnings.md");
+    expect(shouldRunReflectionMock).toHaveBeenCalledWith("Remediate");
+
+    // one-shot: the second stop is allowed
+    const second = await gateFetch(server);
+    expect(await second.json()).toEqual({ block: false });
+  });
+
+  it("skips reflection when no learnings file was seeded", async () => {
+    shouldRunReflectionMock.mockReturnValue(true);
+    const server = await startServer(makeCtx({ selectedMode: "Remediate" }));
+
+    const res = await gateFetch(server);
+    expect(await res.json()).toEqual({ block: false });
+    expect(shouldRunReflectionMock).not.toHaveBeenCalled();
+  });
+
+  it("skips reflection when the selected mode opts out", async () => {
+    shouldRunReflectionMock.mockReturnValue(false);
+    const server = await startServer(
+      makeCtx({ learningsFilePath: "/tmp/learnings.md", selectedMode: "Review" }),
+    );
+
+    const res = await gateFetch(server);
+    expect(await res.json()).toEqual({ block: false });
+  });
+
+  it("allows the stop when the gate collection itself throws", async () => {
+    collectPostRunIssuesMock.mockRejectedValue(new Error("github 500"));
+    const server = await startServer(makeCtx());
+
+    const res = await gateFetch(server);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ block: false });
+  });
+});
+
+describe("gate server disposal", () => {
+  it("stops accepting connections after dispose", async () => {
+    const server = await startServer(makeCtx());
+    const url = server.url;
+    await server[Symbol.asyncDispose]();
+    handle = undefined;
+
+    const err = await fetch(url).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+  });
+});

package/src/agents/gateServer.ts

@@ -0,0 +1,124 @@
+/**
+ * gate server — localhost HTTP sidecar that returns Stop-hook decisions for
+ * the Claude harness. the managed Stop hook (see `action/agents/claude.ts`)
+ * curls this server on every stop and writes back the resulting
+ * `{decision: "block", reason}` to inject a follow-up turn inside the live
+ * `queryLoop`, replacing the pre-PR-#795 `--resume <sessionId>` subprocess.
+ *
+ * the server captures `ctx` by closure so every request reads the latest
+ * mutations from MCP tool callbacks (which run in the same process). the
+ * counters live here, not on `toolState`, because gate-retry budget and
+ * reflection one-shot are harness concerns the literal `toolState` design
+ * rule (see `action/toolState.ts`) explicitly excludes.
+ *
+ * decision policy mirrors the old `runPostRunRetryLoop`:
+ *   - gates dirty + budget remaining → block with combined gate prompt
+ *   - gates clean + reflection pending → block with reflection prompt
+ *   - otherwise → allow stop
+ * `summaryStale` is a one-shot nudge; once delivered the gate is suppressed
+ * so a deliberately-unchanged file doesn't burn the retry budget. when the
+ * budget is exhausted with hard-fail gates still failing, we allow the stop
+ * so `finalizeAgentResult` can render the terminal `AgentResult.success =
+ * false` — that state cannot be set from a stdout-only hook.
+ */
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import {
+  buildLearningsReflectionPrompt,
+  buildPostRunPrompt,
+  collectPostRunIssues,
+  shouldRunReflection,
+} from "#app/agents/postRun";
+import { type AgentRunContext, hasPostRunIssues, MAX_POST_RUN_RETRIES } from "#app/agents/shared";
+import { log } from "#app/utils/cli";
+
+export interface GateServerHandle {
+  url: string;
+  // bearer token the Stop hook must present. Passed to the agent process via a
+  // `_TOKEN`-suffixed env var so filterEnv() strips it from the agent's shell
+  // sandbox — only the real Stop hook (a child of the agent process, inheriting
+  // its full env) can read it. Without this, any loopback caller (incl. the
+  // agent) could poison the retry budget by hitting GET /gates.
+  token: string;
+  [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+export async function startGateServer(ctx: AgentRunContext): Promise<GateServerHandle> {
+  let blockCount = 0;
+  let reflectionDelivered = false;
+  let summaryStaleNudged = false;
+  const token = randomUUID();
+
+  const server = createServer((req, res) => {
+    void (async () => {
+      if (req.method !== "GET" || req.url !== "/gates") {
+        res.writeHead(404).end();
+        return;
+      }
+      // Authenticate before reading state or mutating counters — an unauthorized
+      // request must not consume the retry budget.
+      if (req.headers.authorization !== `Bearer ${token}`) {
+        res.writeHead(403).end();
+        return;
+      }
+      try {
+        const issues = await collectPostRunIssues(ctx, { skipSummaryStale: summaryStaleNudged });
+        if (hasPostRunIssues(issues)) {
+          if (blockCount >= MAX_POST_RUN_RETRIES) {
+            log.info("» gate-server: retry budget exhausted, allowing stop for terminal hard-fail");
+            res.writeHead(200, { "content-type": "application/json" }).end('{"block":false}');
+            return;
+          }
+          if (issues.summaryStale) summaryStaleNudged = true;
+          blockCount++;
+          const reason = buildPostRunPrompt(issues);
+          log.info(`» gate-server: blocking (attempt ${blockCount}/${MAX_POST_RUN_RETRIES})`);
+          res
+            .writeHead(200, { "content-type": "application/json" })
+            .end(JSON.stringify({ block: true, reason }));
+          return;
+        }
+        const learningsPath = ctx.toolState.learningsFilePath;
+        if (
+          !reflectionDelivered &&
+          learningsPath &&
+          shouldRunReflection(ctx.toolState.selectedMode)
+        ) {
+          reflectionDelivered = true;
+          const reason = buildLearningsReflectionPrompt(learningsPath);
+          log.info("» gate-server: delivering reflection nudge");
+          res
+            .writeHead(200, { "content-type": "application/json" })
+            .end(JSON.stringify({ block: true, reason }));
+          return;
+        }
+        res.writeHead(200, { "content-type": "application/json" }).end('{"block":false}');
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.warning(`» gate-server handler error: ${msg}`);
+        // never block claude on a server-side fault — allow the stop and
+        // let the harness's terminal hard-fail path own the decision.
+        res.writeHead(200, { "content-type": "application/json" }).end('{"block":false}');
+      }
+    })();
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const addr = server.address();
+  if (!addr || typeof addr === "string") {
+    throw new Error("gate-server: failed to bind localhost port");
+  }
+  const url = `http://127.0.0.1:${addr.port}/gates`;
+  log.debug(`» gate-server listening at ${url}`);
+
+  return {
+    url,
+    token,
+    [Symbol.asyncDispose]: async () => {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}

package/src/agents/index.ts

@@ -0,0 +1,10 @@
+import { claude } from "#app/agents/claude";
+// In-process OpenCode harness, adapted to opencode-ai >=1.14.x SDK-v2 /
+// Effect-ts CLI rewrite. (The legacy CLI-subprocess harness was removed; see
+// git history if a revert is ever needed.)
+import { opencode } from "#app/agents/opencode";
+import type { Agent } from "#app/agents/shared";
+
+export type { Agent, AgentUsage } from "#app/agents/shared";
+
+export const agents = { claude, opencode } satisfies Record<string, Agent>;

package/src/agents/nativeFsDenies.ts

@@ -0,0 +1,82 @@
+// Canonical native-FS-tool deny set shared by the OpenCode and Claude harnesses.
+//
+// The agent's NATIVE FS tools (Read/Write/Edit/Glob/Grep) run in the agent
+// process OUTSIDE the bash mount-namespace sandbox (FS_MOUNTS in
+// action/mcp/shell.ts), so they need an independent deny — without it a
+// prompt-injected agent could plant a git filter or hook via the native edit
+// tool, bypassing the shell sandbox entirely. See wiki/security.md "Native
+// Tool Filesystem Sandbox".
+//
+// WRITES are denied across ALL of .git, READS only on .git/config:
+//   - nothing legitimately WRITES under .git via native tools — real commits
+//     go through the MCP git tools, which run in the action process OUTSIDE
+//     this permission gate. so a blanket write-deny is free, and it robustly
+//     covers every code-exec surface an enumerated list would miss:
+//     .git/config, .git/config.worktree, .git/modules/*/config (all carry the
+//     same core.hooksPath / clean+smudge filter / alias / credential.helper
+//     exec vectors) plus .git/hooks/* and .git/info/attributes. the deny also
+//     covers the `.git` gitfile itself and nested `*/.git` gitfiles (worktree /
+//     submodule layouts), whose `gitdir:` pointer is the same exec surface.
+//   - READS stay narrow (.git/config only) because over-blocking .git reads
+//     would break legit native orientation reads (.git/HEAD, refs), and the
+//     read threat is low — ASKPASS keeps live tokens out of .git/config.
+//
+// The two agents express denies differently, so the surfaces are encoded once
+// here and formatted per-agent:
+//   - OpenCode: worktree-relative patterns under the per-tool `read`/`edit`
+//     permission keys (Wildcard dialect: `*` is regex `.*`, matching `/`
+//     recursively). The `external_directory` gate can't restrict within-project
+//     paths (it short-circuits inside the repo root via Instance.containsPath),
+//     and the `grep`/`glob` permissions match the search pattern rather than a
+//     filepath — so only `read` and `edit` can path-deny within the project.
+//   - Claude: gitignore-style globs (`**` = recursive) per (tool, path) in
+//     managed-settings `permissions.deny`.
+
+/** worktree-relative blanket WRITE deny for the entire `.git` tree, in
+ * OpenCode Wildcard dialect (`*` compiles to regex `.*`, matching `/`
+ * recursively — see packages/core/src/util/wildcard.ts). spread into the
+ * `edit` ruleset after a `"*": "allow"` baseline — `evaluate` is
+ * last-match-wins by key order, so the deny keys must follow the wildcard
+ * allow.
+ *
+ * four patterns, because the root-anchored descendants glob only matches
+ * paths under a root `.git` *directory* — it misses `.git` when it's a gitfile
+ * (worktree / submodule layouts: a regular file whose `gitdir:` line redirects
+ * git metadata) and misses nested gitfiles (a `.git` inside a subdirectory).
+ * rewriting either pointer is the same code-exec surface (`core.hooksPath`,
+ * clean/smudge filters, credential.helper) the blanket deny exists to seal, so
+ * we cover the gitfile itself and any nested `.git` too. */
+export const GIT_NATIVE_WRITE_DENY_OPENCODE: Record<string, "deny"> = {
+  ".git": "deny",
+  ".git/*": "deny",
+  "*/.git": "deny",
+  "*/.git/*": "deny",
+};
+
+/** worktree-relative narrow READ deny (`.git/config` only), in OpenCode
+ * Wildcard dialect. spread into the `read` ruleset after the `"*": "allow"`
+ * baseline. */
+export const GIT_NATIVE_READ_DENY_OPENCODE: Record<string, "deny"> = {
+  ".git/config": "deny",
+};
+
+/** native FS tools Claude exposes that can read or enumerate files. */
+const CLAUDE_READ_TOOLS = ["Read", "Grep", "Glob"] as const;
+
+/** Claude `permissions.deny` entries for the blanket `.git` WRITE deny —
+ * mirrors {@link GIT_NATIVE_WRITE_DENY_OPENCODE}. `**` is recursive. the exact
+ * `.git` entry plus the recursive-prefix gitfile entry cover the gitfile
+ * pointer (root + nested) that the root-anchored descendants glob alone misses;
+ * the recursive-prefix descendants entry covers nested gitdirs. */
+export const GIT_NATIVE_WRITE_DENY_CLAUDE: string[] = [
+  "Edit(.git)",
+  "Edit(.git/**)",
+  "Edit(**/.git)",
+  "Edit(**/.git/**)",
+];
+
+/** Claude `permissions.deny` entries for the narrow `.git/config` READ deny,
+ * one per read/enumerate tool — mirrors {@link GIT_NATIVE_READ_DENY_OPENCODE}. */
+export const GIT_NATIVE_READ_DENY_CLAUDE: string[] = CLAUDE_READ_TOOLS.map(
+  (tool) => `${tool}(.git/config)`,
+);