opencode-worktree-guardian 0.1.0

package/src/git.ts

@@ -0,0 +1,288 @@
+import { execFile, spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { promisify } from "node:util";
+import { gitMetadataFromError, withGitMetadata } from "./types.ts";
+import type { ExecFileOptionsWithStringEncoding, SpawnOptionsWithoutStdio } from "node:child_process";
+import type { GitCommandFailure, GitCommandOutput, WorktreeEntry } from "./types.ts";
+
+const execFileAsync = promisify(execFile);
+
+export type TryGitResult =
+  | ({ readonly ok: true } & GitCommandOutput)
+  | ({ readonly ok: false; readonly error: GitCommandFailure } & GitCommandOutput);
+
+export type GitStashEntry = { readonly name: string; readonly commit: string; readonly message: string };
+export type GitRefEntry = { readonly name: string; readonly commit: string; readonly date: string; readonly subject: string };
+export type GitBranchEntry = { readonly name: string; readonly commit: string };
+export type GitCommitEntry = { readonly commit: string; readonly subject: string };
+export type GitRecoveryCandidates = { readonly reflog: readonly (GitCommitEntry & { readonly selector: string })[]; readonly unreachable: readonly string[] };
+type CreateSafetyRefOptions = { readonly sessionId?: unknown; readonly branch?: unknown; readonly commit?: string; readonly timestamp?: unknown };
+type GitExecOptions = Omit<ExecFileOptionsWithStringEncoding, "encoding">;
+type GitSpawnOptions = Omit<SpawnOptionsWithoutStdio, "stdio">;
+
+export async function runGit(repoPath: string, args: readonly string[], options: GitExecOptions = {}): Promise<GitCommandOutput> {
+  try {
+    const { stdout, stderr } = await execFileAsync("git", ["-C", repoPath, ...args], {
+      maxBuffer: 10 * 1024 * 1024,
+      encoding: "utf8",
+      ...options,
+    });
+    return { stdout: stdout.trim(), stderr: stderr.trim() };
+  } catch (error) {
+    throw withGitMetadata(error, gitMetadataFromError(args, error));
+  }
+}
+
+export async function runGitNullSeparated(repoPath: string, args: readonly string[], options: GitSpawnOptions = {}): Promise<string[]> {
+  return new Promise<string[]>((resolve, reject) => {
+    const child = spawn("git", ["-C", repoPath, ...args], { ...options, stdio: ["ignore", "pipe", "pipe"] });
+    const decoder = new StringDecoder("utf8");
+    const stderrDecoder = new StringDecoder("utf8");
+    const entries: string[] = [];
+    let current = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      const text = decoder.write(chunk);
+      const parts = text.split("\0");
+      parts[0] = current + parts[0];
+      current = parts.pop() ?? "";
+      for (const part of parts) {
+        const entry = part.trim();
+        if (entry) entries.push(entry);
+      }
+    });
+
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += stderrDecoder.write(chunk);
+    });
+
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      reject(withGitMetadata(error, gitMetadataFromError(args, error, { stdout: "", stderr: stderr.trim() })));
+    });
+
+    child.on("close", (code, signal) => {
+      const finalText = decoder.end();
+      if (finalText) current += finalText;
+      stderr += stderrDecoder.end();
+      const finalEntry = current.trim();
+      if (finalEntry) entries.push(finalEntry);
+      if (code === 0) {
+        resolve(entries);
+        return;
+      }
+      const error = new Error(`git ${args.join(" ")} failed${signal ? ` with signal ${signal}` : ` with exit code ${code}`}`);
+      reject(withGitMetadata(error, {
+        gitArgs: [...args],
+        gitStdout: "",
+        gitStderr: stderr.trim(),
+        ...(typeof code === "number" ? { gitExitCode: code } : {}),
+        ...(signal ? { gitSignal: signal } : {}),
+      }));
+    });
+  });
+}
+
+export async function tryGit(repoPath: string, args: readonly string[]): Promise<TryGitResult> {
+  try {
+    return { ok: true, ...(await runGit(repoPath, args)) };
+  } catch (error) {
+    const failure = withGitMetadata(error, gitMetadataFromError(args, error));
+    return { ok: false, error: failure, stdout: failure.gitStdout, stderr: failure.gitStderr };
+  }
+}
+
+export async function getRepoRoot(cwd: string) {
+  return (await runGit(cwd, ["rev-parse", "--show-toplevel"])).stdout;
+}
+
+export async function getCommonGitDir(repoRoot: string) {
+  return (await runGit(repoRoot, ["rev-parse", "--path-format=absolute", "--git-common-dir"])).stdout;
+}
+
+export async function getCurrentBranch(repoRoot: string) {
+  const result = await tryGit(repoRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  return result.ok ? result.stdout : null;
+}
+
+export async function getHeadCommit(repoRoot: string) {
+  return (await runGit(repoRoot, ["rev-parse", "HEAD"])).stdout;
+}
+
+export async function getBranchCommit(repoRoot: string, branch: string) {
+  return (await runGit(repoRoot, ["rev-parse", "--verify", `refs/heads/${branch}^{commit}`])).stdout;
+}
+
+export async function getRefCommit(repoRoot: string, ref: string) {
+  return (await runGit(repoRoot, ["rev-parse", "--verify", `${ref}^{commit}`])).stdout;
+}
+
+export async function getStatusPorcelain(repoRoot: string) {
+  return (await runGit(repoRoot, ["status", "--porcelain"])).stdout;
+}
+
+export async function getDirtyFiles(repoRoot: string) {
+  const { stdout: status } = await execFileAsync("git", ["-C", repoRoot, "status", "--porcelain=v1", "--untracked-files=all", "-z"], { maxBuffer: 10 * 1024 * 1024 });
+  if (!status) return [];
+  const files: string[] = [];
+  const entries = status.split("\0").filter(Boolean);
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    const statusCode = entry.slice(0, 2);
+    const filePath = entry.slice(3);
+    if (filePath) files.push(filePath);
+    if (statusCode.includes("R") || statusCode.includes("C")) {
+      const sourcePath = entries[index + 1];
+      if (sourcePath) files.push(sourcePath);
+      index += 1;
+    }
+  }
+  return [...new Set(files)];
+}
+
+export async function getIgnoredFiles(repoRoot: string) {
+  const status = (await runGit(repoRoot, ["status", "--porcelain", "--ignored"])).stdout;
+  if (!status) return [];
+  return status.split("\n").filter((line) => line.startsWith("!! ")).map((line) => line.slice(3)).filter(Boolean);
+}
+
+export async function listStashes(repoRoot: string): Promise<GitStashEntry[]> {
+  const result = await tryGit(repoRoot, ["stash", "list", "--format=%gd%x00%H%x00%gs"]);
+  if (!result.ok || !result.stdout) return [];
+  return result.stdout.split("\n").map((line: string) => {
+    const [name, commit, message] = line.split("\0");
+    return { name, commit, message };
+  });
+}
+
+export async function listWorktrees(repoRoot: string): Promise<WorktreeEntry[]> {
+  const { stdout } = await runGit(repoRoot, ["worktree", "list", "--porcelain"]);
+  if (!stdout) return [];
+  const entries: WorktreeEntry[] = [];
+  let current: { path: string; head?: string; branch?: string; detached?: boolean; bare?: boolean } | null = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      if (current) entries.push(current);
+      current = { path: line.slice("worktree ".length) };
+    } else if (current && line.startsWith("HEAD ")) {
+      current.head = line.slice("HEAD ".length);
+    } else if (current && line.startsWith("branch ")) {
+      current.branch = line.slice("branch ".length).replace(/^refs\/heads\//, "");
+    } else if (current && line === "detached") {
+      current.detached = true;
+    } else if (current && line === "bare") {
+      current.bare = true;
+    }
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+
+function safeRefSegment(value: unknown) {
+  const segment = String(value ?? "")
+    .replace(/^refs\//, "")
+    .replace(/\.\.+/g, ".")
+    .replace(/[^A-Za-z0-9._/-]+/g, "-")
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\/+/g, "/");
+  return segment.length > 0 ? segment : "unknown";
+}
+
+function defaultRefTimestamp() {
+  return new Date().toISOString().replace(/[-:.]/g, "").slice(0, 15);
+}
+
+function safeRefTimestamp(timestamp: unknown) {
+  if (timestamp instanceof Date) return defaultRefTimestampFromDate(timestamp);
+  const stamp = safeRefSegment(timestamp);
+  return stamp === "unknown" ? defaultRefTimestamp() : stamp;
+}
+
+function defaultRefTimestampFromDate(timestamp: Date) {
+  return timestamp.toISOString().replace(/[-:.]/g, "").slice(0, 15);
+}
+
+export function buildSafetyRef(sessionId: string, branch: string, timestamp: unknown = new Date()) {
+  const stamp = safeRefTimestamp(timestamp);
+  return `refs/opencode-guardian/${safeRefSegment(sessionId)}/${safeRefSegment(branch)}/${stamp}`;
+}
+
+export function buildPreservedRef(sessionId: string, branch: string, timestamp: unknown = new Date()) {
+  const stamp = safeRefTimestamp(timestamp);
+  return `refs/opencode-guardian/preserved/${safeRefSegment(sessionId)}/${safeRefSegment(branch)}/${stamp}`;
+}
+
+export async function createRef(repoRoot: string, refName: string, commit = "HEAD") {
+  await runGit(repoRoot, ["update-ref", refName, commit]);
+  return refName;
+}
+
+export async function createSafetyRef(repoRoot: string, { sessionId, branch, commit = "HEAD", timestamp }: CreateSafetyRefOptions = {}) {
+  const ref = buildSafetyRef(String(sessionId ?? ""), String(branch ?? ""), timestamp);
+  await createRef(repoRoot, ref, commit);
+  return ref;
+}
+
+export async function listRefs(repoRoot: string, prefix: string): Promise<GitRefEntry[]> {
+  const result = await tryGit(repoRoot, ["for-each-ref", "--format=%(refname)%00%(objectname)%00%(committerdate:iso8601)%00%(subject)", prefix]);
+  if (!result.ok || !result.stdout) return [];
+  return result.stdout.split("\n").map((line: string) => {
+    const [name, commit, date, subject] = line.split("\0");
+    return { name, commit, date, subject };
+  });
+}
+
+export async function isAncestor(repoRoot: string, commit: string, ref: string) {
+  const result = await tryGit(repoRoot, ["merge-base", "--is-ancestor", commit, ref]);
+  return result.ok;
+}
+
+export async function listUnmergedCommits(repoRoot: string, head: string, baseRef: string): Promise<GitCommitEntry[]> {
+  const result = await runGit(repoRoot, ["log", "--format=%H%x00%s", `${baseRef}..${head}`]);
+  if (!result.stdout) return [];
+  return result.stdout.split("\n").map((line: string) => {
+    const [commit, subject] = line.split("\0");
+    return { commit, subject };
+  });
+}
+
+export async function pushBranch(repoRoot: string, remote: string, branch: string) {
+  await runGit(repoRoot, ["push", "-u", remote, branch]);
+}
+
+export async function fetchRemote(repoRoot: string, remote: string) {
+  await runGit(repoRoot, ["fetch", remote]);
+}
+
+export async function removeWorktree(repoRoot: string, worktreePath: string) {
+  await runGit(repoRoot, ["worktree", "remove", worktreePath]);
+}
+
+export async function deleteBranch(repoRoot: string, branch: string) {
+  await runGit(repoRoot, ["branch", "-d", "--", branch]);
+}
+
+export async function abandonBranch(repoRoot: string, branch: string) {
+  await runGit(repoRoot, ["branch", "-D", "--", branch]);
+}
+
+export async function listBranches(repoRoot: string): Promise<GitBranchEntry[]> {
+  const result = await tryGit(repoRoot, ["for-each-ref", "--format=%(refname:short)%00%(objectname)", "refs/heads"]);
+  if (!result.ok || !result.stdout) return [];
+  return result.stdout.split("\n").map((line: string) => {
+    const [name, commit] = line.split("\0");
+    return { name, commit };
+  });
+}
+
+export async function listRecoveryCandidates(repoRoot: string): Promise<GitRecoveryCandidates> {
+  const reflog = await tryGit(repoRoot, ["reflog", "--format=%H%x00%gd%x00%gs", "-n", "25"]);
+  const unreachable = await tryGit(repoRoot, ["fsck", "--no-reflogs", "--unreachable"]);
+  return {
+    reflog: reflog.ok && reflog.stdout ? reflog.stdout.split("\n").map((line: string) => {
+      const [commit, selector, subject] = line.split("\0");
+      return { commit, selector, subject };
+    }) : [],
+    unreachable: unreachable.stdout ? unreachable.stdout.split("\n").filter(Boolean) : [],
+  };
+}

package/src/guards/allowlists.ts

@@ -0,0 +1,83 @@
+import type { AllowDecision, GuardOptions } from "../types.ts";
+import type { CommandSegment } from "./guard-types.ts";
+import { hasAliasCapableRuntimeConfig, isForcePushToken, parseGitInvocation, pushRefspecs } from "./git-invocation.ts";
+import { stringOption } from "./options.ts";
+import { cdTarget, READ_ONLY_SHELL_COMMANDS, SHELL_COMMANDS, stripCommandWrappers } from "./shell-prefix.ts";
+import { commandSegments, commandSegmentsWithSeparators, SEGMENT_BREAKS, tokenizeCommand } from "./shell-parser.ts";
+
+export const STASH_READ_ONLY = new Set<string>(["list", "show"]);
+const READ_ONLY_GIT_COMMANDS = new Set(["status", "diff", "log", "show", "rev-parse", "branch", "worktree", "stash", "remote", "ls-files"]);
+const NORMAL_AGENT_GIT_COMMANDS = new Set(["add", "commit", "fetch", "push"]);
+
+function hasUnsafeReadOnlySyntax(command: string, tokens: readonly string[]): boolean {
+  return command.includes("`") || command.includes("$(") || /[<>]/.test(command) || tokens.some((token) => SEGMENT_BREAKS.has(token));
+}
+
+function isAllowedReadOnlyGit(segment: CommandSegment): boolean {
+  const parsed = parseGitInvocation(segment);
+  if (!parsed?.subcommand || !READ_ONLY_GIT_COMMANDS.has(parsed.subcommand)) return false;
+  const { subcommand, rest } = parsed;
+
+  if (subcommand === "status") {
+    return rest.every((token) => token.startsWith("-") || token === "--");
+  }
+  if (subcommand === "branch") {
+    return rest.every((token) => token === "--list" || token === "--show-current" || token === "-a" || token === "-r" || token.startsWith("--format="));
+  }
+  if (subcommand === "worktree") {
+    return rest[0] === "list" && rest.slice(1).every((token) => token.startsWith("-"));
+  }
+  if (subcommand === "stash") {
+    const action = rest.find((token) => !token.startsWith("-")) ?? "list";
+    return STASH_READ_ONLY.has(action);
+  }
+  if (subcommand === "remote") {
+    return rest.length === 0 || rest.every((token) => token === "-v" || token === "--verbose");
+  }
+  if (subcommand === "diff") {
+    return !rest.some((token) => token === "--output" || token.startsWith("--output=") || token === "--ext-diff" || token === "--textconv");
+  }
+  return true;
+}
+
+export function classifyReadOnlyInspectionCommand(command: unknown): AllowDecision {
+  if (typeof command !== "string" || command.trim() === "") return { allowed: false, reason: "empty command" };
+  const tokens = tokenizeCommand(command);
+  if (hasUnsafeReadOnlySyntax(command, tokens)) return { allowed: false, reason: "compound or redirected shell syntax is not read-only allowlisted" };
+  const segment = commandSegments(tokens)[0] ?? [];
+  const stripped = stripCommandWrappers(segment);
+  if (stripped.length === 1 && READ_ONLY_SHELL_COMMANDS.has(stripped[0] ?? "")) return { allowed: true, reason: null };
+  if (SHELL_COMMANDS.has(stripped[0] ?? "")) return { allowed: false, reason: "shell payload execution is not read-only allowlisted" };
+  if (isAllowedReadOnlyGit(segment)) return { allowed: true, reason: null };
+  return { allowed: false, reason: "command is not read-only allowlisted" };
+}
+
+function isAllowedNormalAgentGit(segment: CommandSegment, options: GuardOptions = {}): boolean {
+  if (isAllowedReadOnlyGit(segment)) return true;
+  const parsed = parseGitInvocation(segment, options);
+  if (!parsed?.subcommand || !NORMAL_AGENT_GIT_COMMANDS.has(parsed.subcommand)) return false;
+  if (hasAliasCapableRuntimeConfig(parsed.configs)) return false;
+
+  const { subcommand, rest } = parsed;
+  if (subcommand === "commit") return !rest.some((token) => token === "--amend" || token.startsWith("--amend="));
+  if (subcommand === "push") {
+    if (rest.some(isForcePushToken)) return false;
+    if (rest.some((token) => token === "--delete" || token === "-d" || token === "--mirror")) return false;
+    return !pushRefspecs(rest).some((refspec) => refspec.startsWith("+") || refspec.startsWith(":"));
+  }
+  return true;
+}
+
+export function classifyNormalAgentGitCommand(command: unknown, options: GuardOptions = {}): AllowDecision {
+  if (typeof command !== "string" || command.trim() === "") return { allowed: false, reason: "empty command" };
+  const tokens = tokenizeCommand(command);
+  if (command.includes("`") || command.includes("$(") || /[<>|()]/.test(command)) return { allowed: false, reason: "compound shell syntax is not normal git passthrough" };
+  let effectiveCwd = stringOption(options, "cwd") ?? process.cwd();
+  for (const { segment, nextSeparator } of commandSegmentsWithSeparators(tokens)) {
+    const scopedOptions = { ...options, cwd: effectiveCwd };
+    if (!isAllowedNormalAgentGit(segment, scopedOptions)) return { allowed: false, reason: "command is not normal non-destructive git" };
+    if (nextSeparator === "||") return { allowed: false, reason: "fallback shell chains are not normal git passthrough" };
+    if (nextSeparator === ";" || nextSeparator === "&&") effectiveCwd = cdTarget(segment, effectiveCwd) ?? effectiveCwd;
+  }
+  return { allowed: true, reason: null };
+}

package/src/guards/classifier.ts

@@ -0,0 +1,39 @@
+import type { GuardCommandPayload, GuardDecision, GuardOptions } from "../types.ts";
+import { isRecordLike } from "../types.ts";
+import { classifySegment } from "./destructive-classifier.ts";
+import type { GuardBlockDecision } from "./guard-types.ts";
+import { stringOption } from "./options.ts";
+import { cdTarget } from "./shell-prefix.ts";
+import { commandSegmentsWithSeparators, findBacktickPayloads, tokenizeCommand } from "./shell-parser.ts";
+
+export function classifyGuardCommand(command: unknown, options: GuardOptions = {}): GuardDecision {
+  if (typeof command !== "string" || command.trim() === "") {
+    return { blocked: false, reason: null, command: "", tokens: [] };
+  }
+  for (const payload of findBacktickPayloads(command)) {
+    const nested = classifyGuardCommand(payload, options);
+    if (nested.blocked) return { ...nested, reason: `backtick command substitution is blocked: ${nested.reason}` };
+  }
+  const tokens = tokenizeCommand(command);
+  let effectiveCwd = stringOption(options, "cwd") ?? process.cwd();
+  for (const { segment, nextSeparator } of commandSegmentsWithSeparators(tokens)) {
+    const scopedOptions = { ...options, cwd: effectiveCwd };
+    const result = classifySegment(segment, scopedOptions, (payload, inheritedEnvAssignments) => {
+      const nested = classifyGuardCommand(payload, { ...scopedOptions, inheritedEnvAssignments });
+      return nested.blocked ? nested : null;
+    });
+    if (result) return { ...result, tokens };
+    if (nextSeparator === ";" || nextSeparator === "&&") {
+      effectiveCwd = cdTarget(segment, effectiveCwd) ?? effectiveCwd;
+    }
+  }
+  return { blocked: false, reason: null, command, tokens };
+}
+
+export function extractCommandText(input: GuardCommandPayload = {}, output: GuardCommandPayload = {}): unknown {
+  const outputArgs = isRecordLike(output.args) ? output.args : {};
+  const inputArgs = isRecordLike(input.args) ? input.args : {};
+  return outputArgs.command ?? inputArgs.command ?? inputArgs.code ?? input.command ?? output.command ?? "";
+}
+
+export type { GuardBlockDecision };

package/src/guards/destructive-classifier.ts

@@ -0,0 +1,189 @@
+import type { GuardOptions } from "../types.ts";
+import { STASH_READ_ONLY } from "./allowlists.ts";
+import type { CommandSegment, GuardBlockDecision } from "./guard-types.ts";
+import { isForcePushToken, parseGitInvocation, pushRefspecs } from "./git-invocation.ts";
+import { block, stringArrayOption, stringOption } from "./options.ts";
+import { isSameOrInside, matchesKnownWorktreePath, normalizeForCompare } from "./path-policy.ts";
+import { protectedBranchBypass } from "./protected-branch-policy.ts";
+import { shellPayload, stripCommandWrappers } from "./shell-prefix.ts";
+
+function hasForceCleanFlag(tokens: CommandSegment): boolean {
+  return tokens.some((token) => token === "--force" || token === "-f" || /^-[a-zA-Z]*f[a-zA-Z]*$/.test(token));
+}
+
+function hasDryRunFlag(tokens: CommandSegment): boolean {
+  return tokens.some((token) => token === "--dry-run" || token === "-n" || /^-[a-zA-Z]*n[a-zA-Z]*$/.test(token));
+}
+
+function isCheckoutPathRestore(rest: CommandSegment): boolean {
+  return rest.includes("--") && rest.indexOf("--") < rest.length - 1;
+}
+
+function isRestoreDestructive(rest: CommandSegment): boolean {
+  if (rest.includes("--staged") && !rest.includes("--worktree") && rest.every((token) => token === "--staged" || token.startsWith("-"))) {
+    return false;
+  }
+  return rest.includes("--worktree") || rest.some((token) => !token.startsWith("-"));
+}
+
+function isRecursiveForce(tokens: CommandSegment): boolean {
+  const flags = tokens.filter((token) => token.startsWith("-"));
+  return flags.some((flag) => flag.includes("r") || flag.includes("R")) && flags.some((flag) => flag.includes("f") || flag.includes("F"));
+}
+
+function targetsRepoManagedPath(targets: readonly string[], options: GuardOptions): boolean {
+  const cwd = options.cwd ?? process.cwd();
+  const explicitProtectedRoots = [stringOption(options, "repoRoot"), stringOption(options, "worktree")]
+    .filter((root): root is string => Boolean(root))
+    .map((root) => normalizeForCompare(root, cwd));
+  const protectedRoots = explicitProtectedRoots.length > 0 ? explicitProtectedRoots : [normalizeForCompare(cwd, cwd)];
+
+  return targets.some((target) => {
+    if (!target || target.startsWith("-")) return false;
+    const resolvedTarget = normalizeForCompare(target, cwd);
+    return protectedRoots.some((root) => isSameOrInside(resolvedTarget, root));
+  });
+}
+
+function findWorktreeAddPath(rest: CommandSegment): string | null {
+  let index = 1;
+  while (index < rest.length) {
+    const token = rest[index] ?? "";
+    if (token === "--") return rest[index + 1] ?? null;
+    if (!token.startsWith("-")) return token;
+    if (["-b", "-B", "--orphan"].includes(token)) {
+      index += 2;
+      continue;
+    }
+    if (token === "--detach" || token.startsWith("--orphan=")) {
+      index += 1;
+      continue;
+    }
+    index += 1;
+  }
+  return null;
+}
+
+function hasBranchDeleteFlag(tokens: CommandSegment): boolean {
+  return tokens.some((token) => {
+    if (token === "--delete" || token.startsWith("--delete=")) return true;
+    if (token.startsWith("--")) return false;
+    return /^-[A-Za-z]*[dD][A-Za-z]*$/.test(token);
+  });
+}
+
+function updateRefDeleteTarget(tokens: CommandSegment): string | null {
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index] ?? "";
+    if (token === "-d" || token === "--delete") {
+      for (let targetIndex = index + 1; targetIndex < tokens.length; targetIndex += 1) {
+        const candidate = tokens[targetIndex] ?? "";
+        if (candidate === "--") return tokens[targetIndex + 1] ?? null;
+        if (!candidate.startsWith("-")) return candidate;
+      }
+      return null;
+    }
+    if (token.startsWith("--delete=")) return token.slice("--delete=".length);
+  }
+  return null;
+}
+
+function hasUpdateRefStdin(tokens: CommandSegment): boolean {
+  return tokens.includes("--stdin");
+}
+
+function isBranchRefDeleteTarget(target: string | null): boolean {
+  return target === "HEAD" || target === "@" || Boolean(target?.startsWith("refs/heads/"));
+}
+
+function classifyGit(segment: CommandSegment, options: GuardOptions = {}): GuardBlockDecision | null {
+  const parsed = parseGitInvocation(segment, options);
+  if (!parsed?.subcommand) return null;
+  const { subcommand, rest, normalized, gitCwd, workTree, configs } = parsed;
+  const bypass = protectedBranchBypass(normalized, subcommand, rest, options, gitCwd, workTree, configs);
+  if (bypass) return bypass;
+  if (subcommand === "reset" && rest.includes("--hard")) {
+    return block("git reset --hard is blocked because it can discard session work", normalized);
+  }
+  if (subcommand === "clean" && hasForceCleanFlag(rest) && !hasDryRunFlag(rest)) {
+    return block("destructive git clean variants are blocked", normalized);
+  }
+  if (subcommand === "branch" && hasBranchDeleteFlag(rest)) {
+    return block("raw git branch deletion is blocked; use guardian_delete_worktree", normalized);
+  }
+  if (subcommand === "update-ref") {
+    if (hasUpdateRefStdin(rest)) {
+      return block("raw git update-ref --stdin is blocked; use guardian_delete_worktree", normalized);
+    }
+    const deleteTarget = updateRefDeleteTarget(rest);
+    if (isBranchRefDeleteTarget(deleteTarget)) {
+      return block("raw git branch ref deletion is blocked; use guardian_delete_worktree", normalized);
+    }
+  }
+  if (subcommand === "worktree" && ["remove", "prune"].includes(rest[0] ?? "")) {
+    return block("raw git worktree removal/prune is blocked; use guardian_delete_worktree", normalized);
+  }
+  if (subcommand === "worktree" && rest[0] === "add") {
+    const addPath = findWorktreeAddPath(rest);
+    const knownWorktreePaths = stringArrayOption(options, "knownWorktreePaths");
+    if (!addPath || !matchesKnownWorktreePath(addPath, knownWorktreePaths, options.cwd ?? process.cwd())) {
+      return block("raw git worktree add outside Guardian-owned roots is blocked; use guardian_start", normalized);
+    }
+  }
+  if (subcommand === "restore" && isRestoreDestructive(rest)) {
+    return block("destructive git restore variants are blocked", normalized);
+  }
+  if (subcommand === "checkout" && (rest.includes("-f") || rest.includes("--force") || isCheckoutPathRestore(rest))) {
+    return block("destructive git checkout variants are blocked", normalized);
+  }
+  if (subcommand === "switch" && rest.some((token) => token === "-f" || token === "--force" || token === "--discard-changes")) {
+    return block("destructive git switch variants are blocked", normalized);
+  }
+  if (subcommand === "stash") {
+    const action = rest.find((token) => !token.startsWith("-")) ?? "push";
+    if (!STASH_READ_ONLY.has(action)) {
+      return block("mutating git stash commands are blocked", normalized);
+    }
+  }
+  if (subcommand === "push" && (rest.some(isForcePushToken) || pushRefspecs(rest).some((refspec) => refspec.startsWith("+")))) {
+    return block("force push is blocked", normalized);
+  }
+  if (subcommand === "push" && rest.some((token) => token === "--mirror")) {
+    return block("mirror push is blocked because it can delete remote refs", normalized);
+  }
+  return null;
+}
+
+export function classifySegment(
+  segment: CommandSegment,
+  options: GuardOptions,
+  classifyNestedPayload: (payload: string, inheritedEnvAssignments: readonly string[]) => { readonly reason: string | null } | null,
+): GuardBlockDecision | null {
+  const payload = shellPayload(segment);
+  if (payload) {
+    const inheritedEnvAssignments = [...(Array.isArray(options.inheritedEnvAssignments) ? options.inheritedEnvAssignments : []), ...payload.assignments];
+    const nested = classifyNestedPayload(payload.payload, inheritedEnvAssignments);
+    if (nested) return block(`shell -c payload is blocked: ${nested.reason}`, segment);
+  }
+  const gitResult = classifyGit(segment, options);
+  if (gitResult) return gitResult;
+  const gitIndex = segment.findIndex((token) => token === "git");
+  if (gitIndex > 0) {
+    const nestedGitResult = classifyGit(segment.slice(gitIndex), options);
+    if (nestedGitResult) return nestedGitResult;
+  }
+  const stripped = stripCommandWrappers(segment);
+  if (stripped[0] === "opencode-worktree-workflow" && stripped[1] === "wt-clean" && stripped[2] === "apply") {
+    return block("opencode-worktree-workflow wt-clean apply is blocked", stripped);
+  }
+  if (stripped[0] === "rm" && isRecursiveForce(stripped.slice(1))) {
+    const targets = stripped.slice(1).filter((token) => !token.startsWith("-"));
+    if (targets.some((target) => matchesKnownWorktreePath(target, options.knownWorktreePaths ?? [], options.cwd ?? process.cwd()))) {
+      return block("rm -rf of a known worktree path is blocked", stripped);
+    }
+    if (targetsRepoManagedPath(targets, options)) {
+      return block("rm -rf inside the current repo/worktree is blocked; use guardian_delete_paths or guardian_hygiene", stripped);
+    }
+  }
+  return null;
+}