@mortz.prk/opencode-auto-mode 1.0.1 → 1.1.1

package/src/score/history.ts

@@ -0,0 +1,141 @@
+import { evaluateVcsGate, type VcsState } from "../gates.js";
+import { isLongOption } from "../shell-policy.js";
+import { ask, high, type RequestScore } from "./types.js";
+
+const HISTORY_SUBCOMMANDS = new Set(["rebase", "filter-branch", "filter-repo"]);
+const FORCE_PUSH_OPTIONS = ["--force", "--force-with-lease", "--force-if-includes", "--delete", "--mirror", "--prune"];
+
+/** GNU option parsing accepts unambiguous abbreviations, so long options are prefix-matched. */
+function hasLong(args: readonly string[], name: string): boolean {
+  return args.some((arg) => isLongOption(arg, name));
+}
+
+function hasAnyLong(args: readonly string[], names: readonly string[]): boolean {
+  return names.some((name) => hasLong(args, name));
+}
+
+function pushRewritesHistory(args: readonly string[]): boolean {
+  if (hasAnyLong(args, FORCE_PUSH_OPTIONS)) return true;
+  return args.some((arg) => /^-[^-]*[fd]/.test(arg) || arg.startsWith("+") || /^:.+/.test(arg));
+}
+
+function deletesRef(args: readonly string[], shortFlag: RegExp): boolean {
+  return hasAnyLong(args, ["--delete", "--force"]) || args.some((arg) => shortFlag.test(arg));
+}
+
+/**
+ * True unless the reset only touches the index/working tree for given paths
+ * (`git reset [<commit>] -- <pathspec>...`), which leaves HEAD and the
+ * current branch untouched. Any other form (mode flags, or a bare commit
+ * argument with no pathspec) moves HEAD.
+ */
+function resetMovesHead(args: readonly string[]): boolean {
+  const rest = args.slice(1);
+  if (hasAnyLong(rest, ["--hard", "--soft", "--mixed", "--merge", "--keep"])) return true;
+  const dashIndex = rest.indexOf("--");
+  if (dashIndex !== -1) return dashIndex === rest.length - 1;
+  return rest.filter((arg) => !arg.startsWith("-")).length <= 1;
+}
+
+/**
+ * The force-create option of each branch-switching subcommand, with the short
+ * letters that take a value so a bundle like `-bB` is read as `-b B` rather
+ * than as a force create.
+ */
+const FORCE_CREATE: Record<string, { short: string; valueLetters: string; long?: string }> = {
+  checkout: { short: "B", valueLetters: "bB" },
+  switch: { short: "C", valueLetters: "cC", long: "--force-create" },
+};
+
+/** The branch name a short bundle force-creates, or undefined when it creates no branch. */
+function shortForceCreate(word: string, option: { short: string; valueLetters: string },
+  next: string | undefined): { branch?: string } | undefined {
+  const letters = word.slice(1);
+  for (let index = 0; index < letters.length; index++) {
+    if (!option.valueLetters.includes(letters[index])) continue;
+    if (letters[index] !== option.short) return undefined;
+    const attached = letters.slice(index + 1);
+    return { branch: attached.length ? attached : next };
+  }
+  return undefined;
+}
+
+/** True for a short-option bundle (`-qB`), which is where the force-create letter can appear. */
+function isShortBundle(word: string): boolean {
+  return word.startsWith("-") && !word.startsWith("--") && word.length > 1;
+}
+
+/** The branch name a long force-create option attaches (`=trunk`) or takes from the next word. */
+function longForceCreate(word: string, next: string | undefined): string | undefined {
+  const separator = word.indexOf("=");
+  return separator === -1 ? next : word.slice(separator + 1);
+}
+
+/**
+ * `checkout -B`/`switch -C`/`switch --force-create` reset an existing branch
+ * before switching to it. The branch name is the option's attached value
+ * (`-Btrunk`, `--force-create=trunk`) or the following word, so a start point
+ * (`HEAD~1`) is never mistaken for the branch; `--` ends option parsing.
+ */
+function forceCreate(args: readonly string[]): { branch?: string } | undefined {
+  const option = FORCE_CREATE[args[0] ?? ""];
+  if (option === undefined) return undefined;
+  const rest = args.slice(1);
+  for (let index = 0; index < rest.length; index++) {
+    const word = rest[index];
+    if (word === "--") return undefined;
+    if (option.long !== undefined && isLongOption(word, option.long))
+      return { branch: longForceCreate(word, rest[index + 1]) };
+    if (!isShortBundle(word)) continue;
+    const created = shortForceCreate(word, option, rest[index + 1]);
+    if (created !== undefined) return created;
+  }
+  return undefined;
+}
+
+function forceResetsBranch(args: readonly string[]): boolean {
+  return forceCreate(args) !== undefined;
+}
+
+/** True when a parsed Git invocation rewrites or deletes history. */
+export function historyChange(words: readonly string[]): boolean {
+  if (words[0] !== "git") return false;
+  const args = words.slice(1);
+  const first = args[0];
+  if (first === "push") return pushRewritesHistory(args);
+  if (first === "commit") return hasLong(args, "--amend");
+  if (first === "reset") return resetMovesHead(args);
+  if (first === "branch") return deletesRef(args, /^-[^-]*[dDf]/);
+  if (first === "tag") return deletesRef(args, /^-[^-]*[df]/);
+  if (first === "checkout" || first === "switch") return forceResetsBranch(args);
+  return HISTORY_SUBCOMMANDS.has(first ?? "");
+}
+
+/** Git global options alter cwd/config or helper execution, so the subcommand is not trustworthy. */
+export function isGitGlobalOption(argv: readonly string[]): boolean {
+  return argv[0] === "git" && argv[1]?.startsWith("-") === true;
+}
+
+function pushesToDefaultBranch(argv: readonly string[], defaultBranch: string): boolean {
+  if (argv[0] !== "git" || argv[1] !== "push") return false;
+  return argv.slice(2).some((arg) =>
+    arg.replace(/^\+/, "").split(":").pop()?.replace(/^refs\/heads\//, "") === defaultBranch);
+}
+
+/** Name of the branch that a force-reset `checkout -B`/`switch -C` would overwrite, if any. */
+function forceResetTarget(argv: readonly string[]): string | undefined {
+  if (argv[0] !== "git") return undefined;
+  return forceCreate(argv.slice(1))?.branch;
+}
+
+/** Scores one verified history-changing invocation, or the missing precondition that asks for review. */
+export function historyScore(scanned: readonly (readonly string[])[], gitState?: VcsState): RequestScore {
+  const gate = evaluateVcsGate(gitState);
+  if (!gate.allowed) return ask(gate.reason);
+  const defaultBranch = gitState?.defaultBranch;
+  if (defaultBranch && scanned.some((argv) => pushesToDefaultBranch(argv, defaultBranch)))
+    return ask("Explicit push destination is the default branch");
+  if (defaultBranch && scanned.some((argv) => forceResetTarget(argv) === defaultBranch))
+    return ask("Force-reset target is the default branch");
+  return high("History changes satisfy VCS preconditions but still require review");
+}

package/src/score/index.ts

@@ -0,0 +1,37 @@
+import type { AutoModeOptions } from "../config.js";
+import type { PermissionRequest } from "../reviewer.js";
+import { projectRoot } from "../tiers.js";
+import { isFileAction, scoreFileAction } from "./files.js";
+import { checkRequestLimits } from "./limits.js";
+import { scoreShellRequest } from "./shell.js";
+import { high, low, type RequestScore } from "./types.js";
+
+const NETWORK_ACTIONS = new Set(["webfetch", "websearch"]);
+const INTERACTIVE_ACTIONS = new Set(["question", "todowrite"]);
+
+/** The evaluated root comes from the caller when given, else from the location itself. */
+function resolveWorktreeRoot(request: PermissionRequest): string | undefined {
+  return request.worktreeRoot ?? (request.projectDir ? projectRoot(request.projectDir) : undefined);
+}
+
+/** The caller decides which host effects enter review. Native deny is always the
+ * caller's responsibility; residual asks and native allows share these guards. */
+export function scoreRequest(request: PermissionRequest & { worktreeRoot?: string }, options: AutoModeOptions): RequestScore {
+  const { action, resources, projectDir } = request;
+  // Reject malformed requests before root discovery touches the filesystem.
+  const rejected = checkRequestLimits(action, resources);
+  if (rejected) return rejected;
+  const worktreeRoot = resolveWorktreeRoot(request);
+  if (action === "shell") return scoreShellRequest(request, worktreeRoot);
+  if (isFileAction(action)) return scoreFileAction(action, resources, options, projectDir, worktreeRoot);
+  // No host allowlist exists, so a URL/query name cannot bound what is fetched.
+  if (NETWORK_ACTIONS.has(action)) return high("Network fetch/search has no verified host allowlist");
+  if (INTERACTIVE_ACTIONS.has(action)) return low("User interaction without host side effects");
+  // JavaScript can hide egress behind aliases, templates and computed URLs.
+  // Even literal allowlisted fetches do not prove the rest of the program safe.
+  if (action === "execute")
+    return high("Code Mode is dynamic execution; outbound hosts cannot be proven statically");
+  // MCP names are not a capability declaration. Unknown and MCP tools always
+  // stay HIGH: no tool name alone establishes a verified read-only capability.
+  return high("Unknown tool capability");
+}

package/src/score/limits.ts

@@ -0,0 +1,24 @@
+import { ask, high, type RequestScore } from "./types.js";
+
+/** Bounds the scorer accepts before it parses or resolves any request text. */
+const MAX_RESOURCES = 256;
+const MAX_RESOURCE_CHARS = 65_536;
+const MAX_RESOURCE_BYTES = 262_144;
+/** User interaction is complete without any resource text. */
+const INTERACTIVE_ACTIONS = new Set(["question", "todowrite"]);
+/** The guard's existing reason for malformed shell requests; keep one manual floor. */
+const SHELL_LIMIT_REASON = "Shell command exceeds parsing limits";
+
+/** Malformed shell requests keep the guard's manual floor; other actions stay HIGH. */
+function limitScore(action: string, reason: string): RequestScore {
+  return action === "shell" ? ask(SHELL_LIMIT_REASON) : high(reason);
+}
+
+/** Request-level limits shared by every action. */
+export function checkRequestLimits(action: string, resources: readonly string[]): RequestScore | undefined {
+  if (!resources.length && !INTERACTIVE_ACTIONS.has(action)) return limitScore(action, "Missing request resources");
+  if (resources.length > MAX_RESOURCES || resources.some((resource) => resource.length > MAX_RESOURCE_CHARS) ||
+      resources.reduce((total, resource) => total + Buffer.byteLength(resource), 0) > MAX_RESOURCE_BYTES)
+    return limitScore(action, "Request exceeds scoring limits");
+  return undefined;
+}

package/src/score/shell-argv.ts

@@ -0,0 +1,74 @@
+import { basename } from "node:path";
+import { operandRoles, resolveExecutable } from "../shell-policy.js";
+import { parseShellCommands, type ParsedShellCommands } from "../shell.js";
+import { high, type RequestScore } from "./types.js";
+
+/**
+ * One shell request parsed once, so every deny, scope and baseline check reads
+ * the same argv representation.
+ */
+export interface ShellScan {
+  /** Parsed form of each resource; undefined when the parser refuses the text. */
+  commands: (ParsedShellCommands | undefined)[];
+  /** Every simple argv list, in resource order. */
+  parsedWords: string[][];
+  /** `parsedWords` after leading wrappers are removed. */
+  effective: string[][];
+  /** `effective` with the executable reduced to its basename, as deny checks read it. */
+  scanned: string[][];
+  /** File operands, excluding command names, options and redirect targets. */
+  operands: string[];
+}
+
+function effectiveArgv(argv: readonly string[]): string[] {
+  const executable = resolveExecutable(argv);
+  return executable ? argv.slice(executable.index) : [...argv];
+}
+
+function scannedArgv(argv: readonly string[]): string[] {
+  return [basename(argv[0] ?? ""), ...argv.slice(1)];
+}
+
+export function scanShell(resources: readonly string[]): ShellScan {
+  const commands = resources.map((resource) => parseShellCommands(resource));
+  const parsedWords = commands.flatMap((command) => command?.segments.map((segment) => segment.words) ?? [])
+    .filter((argv) => argv.length);
+  const effective = parsedWords.map(effectiveArgv);
+  return {
+    commands,
+    parsedWords,
+    effective,
+    scanned: effective.map(scannedArgv),
+    operands: commands.flatMap((command) => command?.operands ?? []),
+  };
+}
+
+/** File targets are command-specific operands, attached path values, and redirects. */
+export function pathTargets(scan: ShellScan): string[] {
+  return scan.commands.flatMap((command) => command === undefined ? [] : [
+    ...command.redirects,
+    ...command.segments.flatMap((segment) => {
+      const roles = operandRoles(segment.words);
+      return [
+        ...roles.paths.map((index) => segment.words[index]!),
+        ...roles.pathValues,
+      ];
+    }),
+  ]);
+}
+
+function hasWrapperPrelude(argv: readonly string[]): boolean {
+  const executable = resolveExecutable(argv);
+  if (!executable) return false;
+  return argv.slice(0, executable.index).some((word) =>
+    word.includes("/") || word.startsWith("-") || /^[A-Za-z_][A-Za-z0-9_]*=/.test(word));
+}
+
+export function executableShapeScore(scan: ShellScan): RequestScore | undefined {
+  // Effective argv is sufficient for deny checks, not for bounded scope:
+  // a repo-controlled wrapper, wrapper options (cwd/output/config), or
+  // leading environment assignments can change where a build operates.
+  if (scan.parsedWords.some(hasWrapperPrelude)) return high("Wrapper executable or effects require review");
+  if (scan.effective.some((argv) => argv[0]?.includes("/"))) return high("Path-qualified executable");
+  return undefined;
+}

package/src/score/shell-baseline.ts

@@ -0,0 +1,113 @@
+import { resolve } from "node:path";
+import type { ReviewResult } from "../reviewer.js";
+import type { ParsedShellCommands } from "../shell.js";
+import { isInProject, projectRoot } from "../tiers.js";
+import { pathTargets, type ShellScan } from "./shell-argv.js";
+import { high, low, medium, type RequestScore } from "./types.js";
+
+/** Writes that never reach a regular file and cannot escape the project. */
+const SAFE_DEVICES = new Set(["/dev/null", "/dev/stdout", "/dev/stderr"]);
+/** Commands whose subcommands are only gray-band when they stay inside the project. */
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm"]);
+const INSTALL_SUBCOMMANDS = new Set(["install", "add", "ci"]);
+const BUILDERS = new Set(["cargo", "go"]);
+const BUILD_SUBCOMMANDS = new Set(["test", "build", "check"]);
+const FORGE_SUBCOMMANDS = new Set(["pr", "issue", "repo", "run"]);
+const FORGE_READS = new Set(["view", "list", "diff", "checks"]);
+const UNSCOPED_INSTALL_FLAGS = /^(?:-g|--global|--prefix|--cwd|--directory)/;
+const GIT_GLOBAL_OVERRIDE = /^(?:-c|--git-dir|--work-tree|--exec-path)/;
+
+function operandEscapes(candidate: string, locationDir: string, worktreeRoot: string): boolean {
+  if (SAFE_DEVICES.has(candidate)) return false;
+  const pathLike = candidate.startsWith("/") || candidate.startsWith("~") ||
+    /(?:^|[/\\])\.\.(?:[/\\]|$)/.test(candidate);
+  if (!pathLike) return false;
+  if (candidate.startsWith("~") || /[$`\0]/.test(candidate)) return true;
+  return !isInProject(resolve(locationDir, candidate), worktreeRoot);
+}
+
+/**
+ * True when a shell operand provably leaves the project scope. Tildes and
+ * parameter expansion cannot be resolved statically, so they are never low.
+ * Option values (`--output=/outside/file`) are judged as well as the whole word.
+ */
+function escapesProject(operand: string, locationDir: string, worktreeRoot: string): boolean {
+  const candidates = operand.includes("=") ? [operand, ...operand.split("=").slice(1)] : [operand];
+  return candidates.some((candidate) => operandEscapes(candidate, locationDir, worktreeRoot));
+}
+
+function isInProjectWords(words: readonly string[], projectDir?: string, worktreeRoot?: string): boolean {
+  if (!projectDir || !worktreeRoot) return false;
+  return !words.some((word) => word.includes("/") && !word.startsWith("--") &&
+    !isInProject(resolve(projectDir, word), worktreeRoot));
+}
+
+function isMediumGit(words: readonly string[]): boolean {
+  return words[1] === "commit" && !words.some((word) => GIT_GLOBAL_OVERRIDE.test(word));
+}
+
+function isMediumInstall(words: readonly string[], subcommand?: string): boolean {
+  if (!INSTALL_SUBCOMMANDS.has(subcommand ?? "")) return false;
+  return words.includes("--ignore-scripts") && !words.some((word) => UNSCOPED_INSTALL_FLAGS.test(word));
+}
+
+function isForgeRead(command?: string, words: readonly string[] = []): boolean {
+  return command === "gh" && FORGE_SUBCOMMANDS.has(words[1] ?? "") && FORGE_READS.has(words[2] ?? "");
+}
+
+function isMediumBun(words: readonly string[], subcommand?: string): boolean {
+  return subcommand === "test" || isMediumInstall(words, subcommand);
+}
+
+function isMediumInvocation(words: readonly string[]): boolean {
+  const [command, subcommand] = words;
+  if (command === "git") return isMediumGit(words);
+  if (command === "bun") return isMediumBun(words, subcommand);
+  if (PACKAGE_MANAGERS.has(command ?? "")) return isMediumInstall(words, subcommand);
+  if (BUILDERS.has(command ?? "")) return BUILD_SUBCOMMANDS.has(subcommand ?? "");
+  return isForgeRead(command, words);
+}
+
+/** Direct in-project runners. Running arbitrary package scripts stays HIGH. */
+function mediumShell(words: readonly string[], projectDir?: string, worktreeRoot = projectDir): boolean {
+  if (!isInProjectWords(words, projectDir, worktreeRoot)) return false;
+  return isMediumInvocation(words);
+}
+
+function isBoundedCommand(command: ParsedShellCommands | undefined): boolean {
+  return !command?.compound && !command?.segments.some((segment) => segment.write);
+}
+
+function wordCount(parsedWords: readonly (readonly string[])[]): number {
+  return parsedWords.reduce((total, argv) => total + argv.length, 0);
+}
+
+function isBoundedMedium(scan: ShellScan, projectDir?: string, worktreeRoot?: string): boolean {
+  return scan.commands.every(isBoundedCommand) &&
+    scan.operands.length === wordCount(scan.parsedWords) &&
+    scan.effective.every((argv) => mediumShell(argv, projectDir, worktreeRoot));
+}
+
+function isReadOnlyEligible(guarded: ReviewResult | undefined, scan: ShellScan): boolean {
+  if (guarded?.decision !== "allow") return false;
+  return !scan.scanned.some((argv) => ["bun", "gh", "git"].includes(argv[0] ?? ""));
+}
+
+function readOnlyScore(scan: ShellScan, projectDir?: string, worktreeRoot?: string): RequestScore {
+  // A read-only command still reads whatever its operands or attached option
+  // values name. Low risk requires every one to stay inside the evaluated project.
+  const locationDir = projectDir ?? process.cwd();
+  const scopeRoot = worktreeRoot ?? projectRoot(locationDir);
+  if (pathTargets(scan).some((operand) => escapesProject(operand, locationDir, scopeRoot)))
+    return high("Shell path operand resolves outside the project");
+  return low("Parsed read-only command with protected-path checks");
+}
+
+/** Picks the residual band after every deny and ask has been ruled out. */
+export function scoreShellBaseline(scan: ShellScan, guarded: ReviewResult | undefined,
+  projectDir?: string, worktreeRoot?: string): RequestScore {
+  if (isReadOnlyEligible(guarded, scan)) return readOnlyScore(scan, projectDir, worktreeRoot);
+  if (isBoundedMedium(scan, projectDir, worktreeRoot))
+    return medium("In-project build, test, install without scripts, commit or forge read");
+  return high("Shell command has unbounded side effects");
+}

package/src/score/shell-safety.ts

@@ -0,0 +1,54 @@
+import type { PermissionRequest } from "../reviewer.js";
+import { protectedSegment, recursiveExternalDelete, type ParsedShellCommands } from "../shell.js";
+import { hasSymlinkTraversal, isProtected, isProtectedShellWord } from "../tiers.js";
+import { historyChange, historyScore, isGitGlobalOption } from "./history.js";
+import { executableShapeScore, pathTargets, type ShellScan } from "./shell-argv.js";
+import { ask, deny, high, type RequestScore } from "./types.js";
+
+function commandTouchesProtected(command: ParsedShellCommands | undefined, projectDir?: string): boolean {
+  if (!command) return false;
+  return command.segments.some((segment) => protectedSegment(segment, projectDir)) ||
+    command.leftovers.some((word) => isProtectedShellWord(word, projectDir));
+}
+
+/** A redirection always names a file, so its target takes the full path-aware check. */
+function redirectsProtected(commands: readonly (ParsedShellCommands | undefined)[], projectDir?: string): boolean {
+  return commands.some((command) => command?.redirects.some((target) => isProtected(target, projectDir)));
+}
+
+/** Denies and asks that depend only on the literal parsed command text. */
+function literalShellScore(scan: ShellScan, request: PermissionRequest, worktreeRoot?: string): RequestScore | undefined {
+  if (scan.scanned.some((argv) => recursiveExternalDelete(argv, request.projectDir, worktreeRoot)))
+    return deny("Recursive/force deletion outside the project");
+  // Git global options alter cwd/config or helper execution. Do not guess the
+  // effective subcommand or let a reviewer lift this uncertainty.
+  if (scan.scanned.some(isGitGlobalOption))
+    return ask("Git global options require manual approval");
+  // A history-rewriting invocation is gated once, against the request's VCS facts.
+  if (scan.scanned.some(historyChange)) return historyScore(scan.scanned, request.gitState);
+  // No regex fallback. Only the guard's literal, fully parsed representation
+  // can establish a low-risk compound; scripts and uncertain syntax stay HIGH.
+  if (scan.commands.some((command) => !command?.complete)) return high("Complex or dynamic shell syntax");
+  return undefined;
+}
+
+/** Protected paths deny; a path that traverses a symlink asks for human review. */
+function protectedPathScore(scan: ShellScan, projectDir?: string): RequestScore | undefined {
+  // Wrappers do not erase destructive semantics (env rm / command git push).
+  // Each simple command is judged by its own grammar, so a pattern/script/filter
+  // is data even when spelled like a path, while tokens outside any command keep
+  // the generic word check.
+  if (redirectsProtected(scan.commands, projectDir) ||
+      scan.commands.some((command) => commandTouchesProtected(command, projectDir)))
+    return deny("Protected path access");
+  if (pathTargets(scan).some((arg) => hasSymlinkTraversal(arg, projectDir)))
+    return ask("Symlink traversal requires human approval");
+  return undefined;
+}
+
+/** Ordered shell safety pipeline: literal denies, then paths, then executable shape. */
+export function shellSafetyScore(scan: ShellScan, request: PermissionRequest, worktreeRoot?: string): RequestScore | undefined {
+  const literal = literalShellScore(scan, request, worktreeRoot);
+  if (literal?.deny || literal?.ask) return literal;
+  return protectedPathScore(scan, request.projectDir) ?? literal ?? executableShapeScore(scan);
+}

package/src/score/shell.ts

@@ -0,0 +1,30 @@
+import type { PermissionRequest, ReviewResult } from "../reviewer.js";
+import { guardShell, visibleShellDeny } from "../shell.js";
+import { scanShell, type ShellScan } from "./shell-argv.js";
+import { scoreShellBaseline } from "./shell-baseline.js";
+import { shellSafetyScore } from "./shell-safety.js";
+import { ask, deny, type RequestScore } from "./types.js";
+
+/** Honours a guard deny/ask before the residual scorer runs. */
+function guardScore(guarded: ReviewResult | undefined, resources: readonly string[],
+  projectDir?: string, worktreeRoot?: string): RequestScore | undefined {
+  if (guarded?.decision === "deny") return deny(guarded.reason);
+  if (guarded?.decision !== "ask") return undefined;
+  // An ask is a manual-approval floor, not a clearance: a deny already visible
+  // in the literal prefix must still win before the ask is honored.
+  const blocked = visibleShellDeny(resources, projectDir, worktreeRoot);
+  if (blocked !== undefined) return deny(blocked);
+  return ask(guarded.reason);
+}
+
+/** Scores one shell request: guard floor, hard safety checks, then residual band. */
+export function scoreShellRequest(request: PermissionRequest, worktreeRoot?: string): RequestScore {
+  const { resources, projectDir } = request;
+  const guarded = guardShell(resources, projectDir);
+  const rejected = guardScore(guarded, resources, projectDir, worktreeRoot);
+  if (rejected) return rejected;
+  const scan: ShellScan = scanShell(resources);
+  const unsafe = shellSafetyScore(scan, request, worktreeRoot);
+  if (unsafe) return unsafe;
+  return scoreShellBaseline(scan, guarded, projectDir, worktreeRoot);
+}

package/src/score/types.ts

@@ -0,0 +1,14 @@
+/** The risk band a permission request falls into, with the reason shown to the user. */
+export interface RequestScore {
+  band: "low" | "medium" | "high";
+  reason: string;
+  deny?: boolean;
+  ask?: boolean;
+}
+
+export const low = (reason: string): RequestScore => ({ band: "low", reason });
+export const medium = (reason: string): RequestScore => ({ band: "medium", reason });
+export const high = (reason: string): RequestScore => ({ band: "high", reason });
+export const deny = (reason: string): RequestScore => ({ band: "high", reason, deny: true });
+/** Missing VCS preconditions gate history changes into manual review, not a hard deny. */
+export const ask = (reason: string): RequestScore => ({ band: "high", reason, ask: true });

package/src/score.ts

@@ -0,0 +1,9 @@
+/**
+ * Compatibility entry point for `./score.js` imports.
+ *
+ * Scoring lives in the focused modules under `./score/`; this file deliberately
+ * re-exports the public surface instead of carrying implementation, so existing
+ * callers and the packaged plugin entry keep the same import path.
+ */
+export { scoreRequest } from "./score/index.js";
+export type { RequestScore } from "./score/types.js";