@brainervirus/workit-core 8.23.0 → 8.25.0

package/src/git/rev.ts

@@ -515,6 +515,250 @@ export function resolveRef(cwd: string, ref: string): string | null {
   return line(git(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]));
 }
 
+/** The branch origin's HEAD names (`origin/main`), or null. */
+export function originHeadRef(cwd: string): string | null {
+  return line(git(cwd, ["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"]));
+}
+
+/** The top of the working tree, or null outside one. */
+export function worktreeTop(cwd: string): string | null {
+  return line(git(cwd, ["rev-parse", "--show-toplevel"]));
+}
+
+/** Whether git tracks `file` (repo-relative) in the index of the checkout at `top`. */
+export function isTracked(top: string, file: string): boolean {
+  return git(top, ["ls-files", "--error-unmatch", "--", file]).ok;
+}
+
+/**
+ * The files whose own change differs between two versions of a branch: the
+ * judged `from` (forked from `fromFork`) and the current `to` (forked from
+ * `toFork`), compared by exact blob and mode, never by diff text (#334). A
+ * file the branch touches on one side only differs. A file it touches on
+ * both sides is unchanged only when the base left it alone between the forks
+ * and the branch's resulting blob is identical, so a hunk moved within a
+ * file, a re-indent or a base edit in a file the branch touches always
+ * counts. Null when git cannot read either side: the caller fails closed.
+ */
+export function ownChangeDrift(
+  cwd: string,
+  range: { from: string; to: string; fromFork: string; toFork: string },
+): string[] | null {
+  const before = diffRaw(cwd, range.fromFork, range.from);
+  const after = diffRaw(cwd, range.toFork, range.to);
+  if (!before || !after) return null;
+  const judged = new Map(before.map((entry) => [entry.path, entry]));
+  const current = new Map(after.map((entry) => [entry.path, entry]));
+  const same = (a: RawEntry | undefined, b: RawEntry | undefined): boolean =>
+    a !== undefined &&
+    b !== undefined &&
+    a.oldMode === b.oldMode &&
+    a.oldBlob === b.oldBlob &&
+    a.newMode === b.newMode &&
+    a.newBlob === b.newBlob;
+  return [...new Set([...judged.keys(), ...current.keys()])]
+    .filter((file) => !same(judged.get(file), current.get(file)))
+    .toSorted();
+}
+
+/**
+ * Whether the branch's own files are identical at `from` (on `fromBase`) and
+ * `to` (on `toBase`): ownChangeDrift from each head's fork is empty. The
+ * exactness behind every patch-equal carry; false when git cannot tell.
+ */
+export function sameOwnChange(
+  cwd: string,
+  range: { from: string; to: string; fromBase: string; toBase: string },
+): boolean {
+  const fromFork = mergeBase(cwd, range.fromBase, range.from);
+  const toFork = mergeBase(cwd, range.toBase, range.to);
+  if (!fromFork || !toFork) return false;
+  return ownChangeDrift(cwd, { from: range.from, to: range.to, fromFork, toFork })?.length === 0;
+}
+
+/**
+ * The verbatim patch-ids of the non-merge commits of `fork..head` (empty
+ * commits have none) and how many merge commits the range holds: unlike
+ * `--stable`, whitespace counts, so a re-indent is another patch. Diff
+ * options are pinned as in patchId. Null when git fails, or has no
+ * `patch-id --verbatim`: the caller fails closed.
+ */
+export function commitPatchIds(
+  cwd: string,
+  fork: string,
+  head: string,
+): { patchIds: string[]; merges: number } | null {
+  if (!safeArg(fork) || !safeArg(head)) return null;
+  const range = `${fork}..${head}`;
+  const merges = line(git(cwd, ["rev-list", "--count", "--merges", range]));
+  const log = git(
+    cwd,
+    [
+      "log",
+      "--no-merges",
+      "-p",
+      "-U3",
+      "--diff-algorithm=myers",
+      "--indent-heuristic",
+      "--no-color",
+      "--no-ext-diff",
+      "--no-textconv",
+      "--no-renames",
+      "--full-index",
+      "--src-prefix=a/",
+      "--dst-prefix=b/",
+      "--format=commit %H",
+      range,
+      "--",
+    ],
+    { timeoutMs: GIT_TIMEOUTS.worktree },
+  );
+  if (merges === null || !log.ok) return null;
+  if (!log.stdout.trim()) return { patchIds: [], merges: Number(merges) };
+  const ids = git(cwd, ["patch-id", "--verbatim"], { input: log.stdout });
+  if (!ids.ok) return null;
+  return {
+    patchIds: ids.stdout
+      .split("\n")
+      .map((entry) => entry.trim().split(/\s+/u)[0])
+      .filter(Boolean),
+    merges: Number(merges),
+  };
+}
+
+/** Pinned diff options for the review-lane reads: user config never changes them. */
+const LANE_DIFF = [
+  "-c",
+  "core.quotePath=false",
+  "diff",
+  "--no-color",
+  "--no-ext-diff",
+  "--no-textconv",
+  "--no-renames",
+];
+
+/** `fork..head`, or with `head` null the working tree's tracked changes since `fork`. */
+const laneRange = (fork: string, head: string | null): string[] | null => {
+  if (!safeArg(fork) || (head !== null && !safeArg(head))) return null;
+  return head === null ? [fork] : [fork, head];
+};
+
+export type NumstatEntry = { path: string; added: number; deleted: number; binary: boolean };
+
+/** Added and deleted lines per file of `fork..head` (no renames); null when git fails. */
+export function diffNumstat(cwd: string, fork: string, head: string | null): NumstatEntry[] | null {
+  const range = laneRange(fork, head);
+  if (!range) return null;
+  const run = git(cwd, [...LANE_DIFF, "--numstat", "-z", ...range, "--"]);
+  if (!run.ok) return null;
+  const out: NumstatEntry[] = [];
+  for (const record of run.stdout.split("\0")) {
+    const match = /^(-|\d+)\t(-|\d+)\t(.+)$/su.exec(record.replace(/^\n/u, ""));
+    if (!match) continue;
+    const binary = match[1] === "-";
+    out.push({
+      path: match[3],
+      added: binary ? 0 : Number(match[1]),
+      deleted: binary ? 0 : Number(match[2]),
+      binary,
+    });
+  }
+  return out;
+}
+
+/** One file of `git diff --raw`: modes and blob ids on each side (zeros: absent or the working tree). */
+export type RawEntry = {
+  path: string;
+  oldMode: string;
+  newMode: string;
+  oldBlob: string;
+  newBlob: string;
+};
+
+/**
+ * The changed files of `fork..head` (or the working tree) with their modes
+ * and blob ids, read NUL-separated so no path is ever quoted or split.
+ * Null when git fails.
+ */
+export function diffRaw(cwd: string, fork: string, head: string | null): RawEntry[] | null {
+  const range = laneRange(fork, head);
+  if (!range) return null;
+  const run = git(cwd, [...LANE_DIFF, "--raw", "-z", "--no-abbrev", ...range, "--"]);
+  if (!run.ok) return null;
+  const fields = run.stdout.split("\0");
+  const out: RawEntry[] = [];
+  for (let index = 0; index + 1 < fields.length; index += 2) {
+    const meta = /^:(\d{6}) (\d{6}) ([0-9a-f]+) ([0-9a-f]+) [A-Z]\d*$/u.exec(
+      fields[index].replace(/^\n/u, ""),
+    );
+    if (!meta) return null;
+    out.push({
+      path: fields[index + 1],
+      oldMode: meta[1],
+      newMode: meta[2],
+      oldBlob: meta[3],
+      newBlob: meta[4],
+    });
+  }
+  return out;
+}
+
+/** The contents of `ids` (blob ids), by id; null when git fails. Missing objects are left out. */
+export function readBlobs(cwd: string, ids: readonly string[]): Map<string, Buffer> | null {
+  const out = new Map<string, Buffer>();
+  const wanted = [...new Set(ids)].filter((id) => /^[0-9a-f]{40,64}$/u.test(id));
+  if (!wanted.length) return out;
+  const run = spawnSync("git", ["cat-file", "--batch"], {
+    cwd,
+    input: `${wanted.join("\n")}\n`,
+    maxBuffer: MAX_BUFFER,
+    timeout: GIT_TIMEOUTS.local,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+  });
+  if (run.status !== 0 || !run.stdout) return null;
+  const bytes = run.stdout;
+  let at = 0;
+  for (const id of wanted) {
+    const end = bytes.indexOf(0x0a, at);
+    if (end < 0) return null;
+    const header = bytes.subarray(at, end).toString("utf8").split(" ");
+    at = end + 1;
+    if (header[1] === "missing") continue;
+    const size = Number(header[2]);
+    if (header[0] !== id || !Number.isSafeInteger(size)) return null;
+    out.set(id, bytes.subarray(at, at + size));
+    at += size + 1;
+  }
+  return out;
+}
+
+/** Blob ids of the files named `name` anywhere in the tree of `rev`, by path; null when git fails. */
+export function treeFilesNamed(cwd: string, rev: string, name: string): Map<string, string> | null {
+  if (!safeArg(rev)) return null;
+  const run = git(cwd, ["ls-tree", "-r", "-z", "--full-tree", rev]);
+  if (!run.ok) return null;
+  const out = new Map<string, string>();
+  for (const record of run.stdout.split("\0")) {
+    const match = /^\d{6} blob ([0-9a-f]+)\t(.+)$/su.exec(record);
+    if (match && (match[2] === name || match[2].endsWith(`/${name}`))) out.set(match[2], match[1]);
+  }
+  return out;
+}
+
+/** The text of `file` (a fixed repo path) at `rev`; null when it is absent or git fails. */
+export function fileAt(cwd: string, rev: string, file: string): string | null {
+  if (!safeArg(rev)) return null;
+  const run = git(cwd, ["cat-file", "blob", `${rev}:${file}`]);
+  return run.ok ? run.stdout : null;
+}
+
+/** Untracked, not ignored files of the working tree (repo-relative). */
+export function untrackedFiles(cwd: string): string[] {
+  const run = git(cwd, ["ls-files", "-z", "--others", "--exclude-standard"]);
+  return run.ok ? run.stdout.split("\0").filter(Boolean) : [];
+}
+
 /**
  * Commits `head` lacks from `base` (behind) and has on top of it (ahead), and
  * whether `base` is already an ancestor of `head`. Null when either side

package/src/hooks/cwd-normalize.ts

@@ -1,16 +1,32 @@
-// `cd <dir> && workit <args>` → `workit --cwd <dir> <args>` (issue #388).
-// On Claude Code the compound does not match a `Bash(workit:*)` allow rule
+// `cd <dir> && workit <args>` → `workit <verb> --cwd <dir> <rest>` (issue #388).
+// On Claude Code the compound does not match a `Bash(workit …)` allow rule
 // (every subcommand must match, and a `cd` outside the working dirs breaks
 // it), so the auto-mode classifier judged it. The rewrite is exact and
 // conservative: one literal directory, one workit call, and only read-only
 // filters after it. Anything else is left alone. Pure string work.
-import { segmentsOf } from "./shell-words";
+//
+// The verb goes first (issue #297): Workit's enumerated host rules, such as
+// `Bash(workit git *)`, cannot match a variable directory before the verb.
+// `--cwd` and `--json` mean the same anywhere before `--` (main.ts
+// parseGlobals), so moving them never changes what runs.
+import { WORKIT_ALLOWED_VERBS } from "./delivery-verbs";
+import { segmentsOf, type Segment } from "./shell-words";
 
 // A directory spelled as one literal word: bare, '…' or "…" with no expansion.
-const COMPOUND =
-  /^\s*cd\s+([A-Za-z0-9_./@%+:,=-]+|'[^'$`\\\n]*'|"[^"$`\\!\n]*")\s*&&\s*(workit(?:\s[\s\S]*)?)$/u;
+const DIR = String.raw`[A-Za-z0-9_./@%+:,=-]+|'[^'$${"`"}\\\n]*'|"[^"$${"`"}\\!\n]*"`;
+const COMPOUND = new RegExp(String.raw`^\s*cd\s+(${DIR})\s*&&\s*(workit(?:\s[\s\S]*)?)$`, "u");
+// `workit` then `--json` / `--cwd <dir>` globals, then the verb.
+const GLOBALS_FIRST = new RegExp(
+  String.raw`^(\s*workit)((?:\s+(?:--json|--cwd(?:=|\s+)(?:${DIR})))+)\s+([a-z][a-z-]*)(?=\s|$)`,
+  "u",
+);
+const VERB_FIRST = /^((?:--json\s+)*)([a-z][a-z-]*)(?=\s|$)/u;
+const VERBS = new Set<string>(WORKIT_ALLOWED_VERBS);
 const FILTERS = new Set(["tail", "head", "grep"]);
 
+const clean = (s: Segment): boolean =>
+  !s.unanalyzable && !s.group && !s.subs?.length && !s.stdin?.length && !s.redirects.length;
+
 // A filter that reads only stdin, so moving the cwd cannot change what it
 // reads: flags and counts for tail/head, one pattern for grep (no -r/-R/-f).
 const stdinOnly = (words: readonly string[]): boolean => {
@@ -22,8 +38,9 @@ const stdinOnly = (words: readonly string[]): boolean => {
 };
 
 /**
- * The command rewritten to `workit --cwd <dir> …`, or null when it is not
- * exactly `cd <literal dir> && workit … [2>&1] [| tail|head|grep …]*`.
+ * The command rewritten to `workit <verb> --cwd <dir> …` (`workit --cwd <dir>
+ * …` for a verb no host rule lists), or null when it is not exactly
+ * `cd <literal dir> && workit … [2>&1] [| tail|head|grep …]*`.
  */
 export const cwdRewrite = (command: string): string | null => {
   const match = COMPOUND.exec(command);
@@ -36,10 +53,27 @@ export const cwdRewrite = (command: string): string | null => {
   const [head, ...filters] = segments;
   if (!head || head.words[0] !== "workit") return null;
   if (head.words.some((w) => w === "--cwd" || w.startsWith("--cwd="))) return null;
-  const clean = (s: (typeof segments)[number]) =>
-    !s.unanalyzable && !s.group && !s.subs?.length && !s.stdin?.length && !s.redirects.length;
   if (!segments.every(clean)) return null;
   if (!segments.slice(0, -1).every((s) => s.pipe)) return null;
   if (!filters.every((s) => FILTERS.has(s.words[0] ?? "") && stdinOnly(s.words))) return null;
-  return `workit --cwd ${dir} ${rest.slice("workit".length).trimStart()}`.trimEnd();
+  const args = rest.slice("workit".length).trimStart();
+  const verb = VERB_FIRST.exec(args);
+  if (!verb?.[2] || !VERBS.has(verb[2])) return `workit --cwd ${dir} ${args}`.trimEnd();
+  const json = verb[1] ? " --json" : "";
+  return `workit ${verb[2]} --cwd ${dir}${json}${args.slice(verb[0].length)}`.trimEnd();
+};
+
+/**
+ * `workit --cwd <dir> <verb> …` (with any `--json` there) rewritten with the
+ * verb first, for a verb the host rules list; null otherwise. Only the words
+ * before the first verb move, and only in a command that is that one call
+ * (no `;`, `&&`, `|`, newline, substitution or redirect).
+ */
+export const verbFirst = (command: string): string | null => {
+  const match = GLOBALS_FIRST.exec(command);
+  const [whole, lead, globals, verb] = match ?? [];
+  if (!whole || !verb || !VERBS.has(verb) || !globals?.includes("--cwd")) return null;
+  const segments = segmentsOf(command);
+  if (segments.length !== 1 || !segments.every(clean)) return null;
+  return `${lead} ${verb}${globals}${command.slice(whole.length)}`;
 };

package/src/hooks/delivery-verbs.ts

@@ -0,0 +1,129 @@
+// The Workit verbs a host may run without asking (issue #297, decision
+// mvk5q3io): delivery and state verbs whose own gates (grants, non-author
+// verdicts, branch policy) decide. One list for every host's permission
+// block: Claude Code `Bash(workit <verb> *)`, Codex `prefix_rule`, Cursor
+// `Shell(workit <verb>)`, and the OpenCode plugin's ask-to-allow.
+//
+// Never listed: verbs that run an arbitrary command (`check -- <cmd>`,
+// `lock run -- <cmd>`, `test-audit`, `fanout check`), change authority
+// (`grant`), install or remove host config (`init`, `upgrade`, `setup`,
+// `uninstall`, `launch`), delete data (`gc`), import state (`state`) or write
+// outside the forge flow (`youtrack`, `changelog`, `knowledge`, `handoff`).
+// Pure string work: the OpenCode plugin bundles it.
+import { segmentsOf, type ShellDialect } from "./shell-words";
+
+export const WORKIT_ALLOWED_VERBS = [
+  "git",
+  "pr",
+  "ci",
+  "stack",
+  "release",
+  "task",
+  "ledger",
+  "evidence",
+  "finding",
+  "decision",
+  "worker",
+  "verify-delivery",
+  "policy",
+  "doctor",
+  "help",
+] as const;
+
+/**
+ * Flags that override a Workit gate: a host never allows them unasked.
+ * Workit has no `--admin` flag and refuses a bare `--force` push itself.
+ */
+export const WORKIT_BYPASS_FLAGS = ["--unverified", "--overwrite-unintegrated"] as const;
+
+const ALLOWED = new Set<string>(WORKIT_ALLOWED_VERBS);
+
+const isBypass = (word: string): boolean =>
+  WORKIT_BYPASS_FLAGS.some((flag) => word === flag || word.startsWith(`${flag}=`));
+
+/** `workit`, `workit-cli`, or either by path. */
+const isWorkitWord = (word: string): boolean => /^(?:.*[\\/])?workit(?:-cli)?$/u.test(word);
+
+/**
+ * Is `words` one Workit call of an allowed verb? Global `--json` and
+ * `--cwd <dir>` may come first (they mean the same anywhere before `--`);
+ * `--session` may not (it changes the acting identity). A bypass flag before
+ * `--` disqualifies it, and so does a word the shell expands there (`expands`,
+ * indexes into `words`): `${F:---unverified}` could become one.
+ */
+export const isAllowedWorkitCall = (
+  words: readonly string[],
+  expands: readonly number[] = [],
+): boolean => {
+  if (words[0] !== "workit") return false;
+  let at = 1;
+  for (;;) {
+    const word = words[at];
+    if (word === "--json") at += 1;
+    else if (word === "--cwd") at += 2;
+    else if (word?.startsWith("--cwd=")) at += 1;
+    else break;
+  }
+  const verb = words[at];
+  if (verb === undefined) return false;
+  if (verb === "--version") return at === words.length - 1;
+  if (!ALLOWED.has(verb)) return false;
+  const end = words.indexOf("--");
+  const limit = end < 0 ? words.length : end;
+  return !words.slice(0, limit).some(isBypass) && !expands.some((index) => index < limit);
+};
+
+const bypassReason = (flag: string) =>
+  `Workit: \`${flag}\` overrides a Workit gate, so the user decides this call (no allow rule covers it).`;
+const EXPANSION_REASON =
+  "Workit: an expansion before `--` could become a bypass flag, so the user decides this call (no allow rule covers it).";
+
+/**
+ * The ask reason for a Workit call in `command` that carries a bypass flag
+ * before its `--` or a word the shell expands there, or null. Words are read after shell quoting, so `"--unverified"`,
+ * `--unverif''ied` or a tab-separated flag are found where a host's string
+ * rule could miss them. A command the tokenizer cannot analyze is judged on
+ * its text with quotes and backslashes removed.
+ */
+export const workitBypassFlag = (
+  command: string,
+  dialect: ShellDialect = "posix",
+): string | null => {
+  for (const segment of segmentsOf(command, dialect)) {
+    if (segment.unanalyzable) {
+      const text = command.replaceAll(/['"\\`]/gu, "");
+      if (!/\bworkit\b/u.test(text)) return null;
+      const found = WORKIT_BYPASS_FLAGS.find((flag) => text.includes(flag));
+      return found ? bypassReason(found) : null;
+    }
+    const start = segment.words.findIndex(isWorkitWord);
+    if (start < 0) continue;
+    const words = segment.words.slice(start + 1);
+    const end = words.indexOf("--");
+    const flag = (end < 0 ? words : words.slice(0, end)).find(isBypass);
+    if (flag) return bypassReason(flag.split("=")[0] ?? flag);
+    const limit = start + 1 + (end < 0 ? words.length : end);
+    if (segment.expands?.some((index) => index > start && index < limit)) return EXPANSION_REASON;
+  }
+  return null;
+};
+
+/**
+ * Is the whole shell `command` allowed Workit calls only? Every segment must
+ * be one, with no substitution, redirect, group or heredoc anywhere.
+ */
+export const isAllowedWorkitCommand = (command: string): boolean => {
+  const segments = segmentsOf(command);
+  return (
+    segments.length > 0 &&
+    segments.every(
+      (s) =>
+        !s.unanalyzable &&
+        !s.group &&
+        !s.subs?.length &&
+        !s.stdin?.length &&
+        !s.redirects.length &&
+        isAllowedWorkitCall(s.words, s.expands),
+    )
+  );
+};

package/src/hooks/handle.ts

@@ -9,7 +9,8 @@ import type { HostDescriptor, Support } from "./descriptor";
 import { branchGuidance } from "../core/branch";
 import { workspaceTrailers } from "../core/workspaces";
 import { judgeBranch, recordIssuedSession, verdictCommand } from "../host-session";
-import { cwdRewrite } from "./cwd-normalize";
+import { cwdRewrite, verbFirst } from "./cwd-normalize";
+import { workitBypassFlag } from "./delivery-verbs";
 import { heavyDenial, heavyGate, rewriteNote, splitDenial } from "./heavy-gate";
 import { shellPolicy } from "./policy";
 import {
@@ -121,7 +122,7 @@ const subagentStartText = (
   if (role === "implementer")
     // No host isolation: the lead makes the worktree, Workit's hooks confine
     // the implementer to it (worktree-confine.ts), and workit git works there.
-    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree, the one its brief names (the lead makes it with \`workit fanout worktree create <slice>\` before spawning), never in the lead's checkout, within its brief's scope. Workit binds it to the first Workit worktree it changes: from then on an edit or a mutating git command outside that worktree is denied, and before then so is one outside every Workit worktree. Run Workit against the worktree one verb per call, never \`cd … &&\` chains or \`$VAR\` paths: \`workit --cwd <worktree> git commit -m "<message>" -- <paths>\`, \`workit --cwd <worktree> check <name>\`. The worktree is on the brief's branch once the lead made it; otherwise switch with \`workit --cwd <worktree> git branch <branch> --base <base>\` (or \`--kind <kind> --slug <slug>\`, which picks the base); branch policy hooks still deny protected or non-compliant branches, raw git included.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+    return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree, the one its brief names (the lead makes it with \`workit fanout worktree create <slice>\` before spawning), never in the lead's checkout, within its brief's scope. Workit binds it to the first Workit worktree it changes: from then on an edit or a mutating git command outside that worktree is denied, and before then so is one outside every Workit worktree. Run Workit against the worktree one verb per call, never \`cd … &&\` chains or \`$VAR\` paths: \`workit git --cwd <worktree> commit -m "<message>" -- <paths>\`, \`workit check --cwd <worktree> <name>\` (verb first, so host allow rules match). The worktree is on the brief's branch once the lead made it; otherwise switch with \`workit git --cwd <worktree> branch <branch> --base <base>\` (or \`--kind <kind> --slug <slug>\`, which picks the base); branch policy hooks still deny protected or non-compliant branches, raw git included.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
   if (role !== "judge" || !event.agentId) return readOnly;
   const own = subagentSession(session, event.agentId);
@@ -152,7 +153,8 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
   if (
     deps.descriptor.transport !== "hook-process" ||
     !PRE_TOOL.has(input.event.kind) ||
-    decision.kind === "deny"
+    decision.kind === "deny" ||
+    decision.kind === "ask"
   )
     return decision;
   const delta = standingDelta(input);
@@ -223,10 +225,14 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
       const rewrites = usable(descriptor.shellPolicy.rewrite);
       if (plan.kind === "rewrite" && !rewrites && canDeny) return heavyDenial(event.command, plan);
       const lease = plan.kind === "rewrite" && rewrites ? plan : null;
-      // `cd <dir> && workit …` becomes `workit --cwd <dir> …` (issue #388). A
-      // workit command is never heavy itself, so the lease plan wins when set.
+      // `cd <dir> && workit …` becomes `workit <verb> --cwd <dir> …` (issue
+      // #388), and `workit --cwd <dir> <verb>` puts the verb first (#297), so
+      // Workit's enumerated allow rules match. A workit command is never heavy
+      // itself, so the lease plan wins when set.
       const cwdCommand =
-        !lease && rewrites && input.host === "claude_code" ? cwdRewrite(event.command) : null;
+        !lease && rewrites && input.host === "claude_code"
+          ? (cwdRewrite(event.command) ?? verbFirst(event.command))
+          : null;
       const aside = plan.kind === "passthrough" ? plan.note : null;
       // The command will run: note HEAD so the post-tool hook (or the next
       // command, without one) can tell whether a raw commit moved it.
@@ -235,6 +241,15 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
         event.command,
         postTool ? callKey(event.toolUseId, event.command) : NEXT_COMMAND,
       );
+      // Claude Code: a Workit bypass flag always reaches the user, whatever
+      // the allow rules match (issue #297). Words, not text, so quoting
+      // cannot hide it; a deny above still wins. A leased command runs under
+      // `workit lock run`, which no Workit rule allows.
+      const bypass =
+        !lease && input.host === "claude_code"
+          ? workitBypassFlag(event.command, event.dialect)
+          : null;
+      if (bypass) return { kind: "ask", reason: bypass };
       const rewrittenTo = lease?.command ?? cwdCommand;
       const rewritten = (text: string | null): HookDecision =>
         rewrittenTo

package/src/hooks/hosts/claude-code.ts

@@ -298,6 +298,17 @@ const render = (decision: HookDecision, native: string | null) => {
       },
       exitCode: 0,
     };
+  if (decision.kind === "ask" && native === "PreToolUse")
+    return {
+      json: {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "ask",
+          permissionDecisionReason: decision.reason,
+        },
+      },
+      exitCode: 0,
+    };
   if (decision.kind === "context" && native !== null && CONTEXT_EVENTS.has(native))
     return {
       json: { hookSpecificOutput: { hookEventName: native, additionalContext: decision.text } },

package/src/hooks/index.ts

@@ -19,6 +19,12 @@ export {
   type SessionHandle,
 } from "./context";
 export { shellPolicy } from "./policy";
+export {
+  isAllowedWorkitCall,
+  isAllowedWorkitCommand,
+  WORKIT_ALLOWED_VERBS,
+  WORKIT_BYPASS_FLAGS,
+} from "./delivery-verbs";
 export { heavyDenial, heavyGate, splitDenial } from "./heavy-gate";
 export { shellGate, shellWrites, writeGate } from "./write-gate";
 export { liveOwner } from "../core/live-session";

package/src/hooks/protocol.ts

@@ -97,6 +97,8 @@ export type HookDecision =
   | { kind: "context"; text: string }
   /** The reason text always carries its own correction (principle 3). */
   | { kind: "deny"; reason: string; unblock: string | null }
+  /** shell.pre: let the user decide, whatever the host's rules allow. Never an allow. */
+  | { kind: "ask"; reason: string }
   /**
    * shell.pre: run `command` instead (the heavy-command lease rewrite).
    * `input` is the host's tool input with the command replaced, where the

package/src/hooks/raw-git.ts

@@ -602,8 +602,15 @@ function walk(
     // (The heavy-command reader, `seen`, stops at workit: a wrapped command
     // already runs under the lease.)
     const wrapped = seen ? null : workitCheckTail(words);
-    if (wrapped)
-      return "script" in wrapped ? nested(wrapped.script, "posix") : runs([wrapped.argv]);
+    if (wrapped) {
+      // `--cwd <dir>` is where the wrapped command runs, not the shell's directory.
+      const outer = dir;
+      if (wrapped.cwd !== null) dir = joinDir(dir, wrapped.cwd);
+      if ("script" in wrapped) nested(wrapped.script, "posix");
+      else runs([wrapped.argv]);
+      dir = outer;
+      return;
+    }
     if (CD.has(name)) {
       const target = cdTarget(words);
       dir = target === null ? os.homedir() : joinDir(dir, target);
@@ -699,22 +706,25 @@ const PACKAGE_RUNNERS = new Set(["npx", "bunx", "pnpx"]);
 /**
  * What a `workit check [flags] -- <cmd…>` (or `workit lock run -- <cmd…>`,
  * also through `npx @brainervirus/workit-cli`) runs: the script of `--shell`,
- * else the argv. Null for any other command.
+ * else the argv, and the `--cwd` it runs in (null: the shell's). Null for any
+ * other command.
  */
 export function workitCheckTail(
   words: readonly string[],
-): { script: string } | { argv: string[] } | null {
+): (({ script: string } | { argv: string[] }) & { cwd: string | null }) | null {
   let at = 0;
   if (PACKAGE_RUNNERS.has(commandName(words[0]))) {
     at = words.findIndex((word, index) => index > 0 && !word.startsWith("-"));
     if (at < 0 || !WORKIT_PACKAGE.test(words[at])) return null;
   } else if (!/^workit(?:\.exe|\.cmd)?$/.test(commandName(words[0]))) return null;
-  const args = words.slice(at + 1);
+  const { rest: args, cwd } = skipWorkitGlobals(words.slice(at + 1));
   if (args[0] !== "check" && !(args[0] === "lock" && args[1] === "run")) return null;
   const split = args.indexOf("--");
   const tail = split < 0 ? [] : args.slice(split + 1);
   if (!tail.length) return null;
-  return args.slice(0, split).includes("--shell") ? { script: tail.join(" ") } : { argv: tail };
+  return args.slice(0, split).includes("--shell")
+    ? { script: tail.join(" "), cwd }
+    : { argv: tail, cwd };
 }
 
 /**
@@ -791,7 +801,12 @@ export function workitInvocations(
 /** Workit's global options before the verb: `--json`, and these (`--name value` or `--name=value`). */
 const WORKIT_GLOBAL = /^--(?:cwd|session|token|as)(=|$)/;
 
-/** An invocation's arguments without the global options before the verb, and the last `--cwd` among them. */
+/**
+ * An invocation's arguments without the global options before the verb and
+ * without any `--cwd` before `--`, and the last `--cwd`. Like the CLI's
+ * parseGlobals, `--cwd` counts anywhere before `--`, so `workit <verb> --cwd
+ * <dir> …` (the form host allow rules match) runs in `<dir>` here too.
+ */
 export function skipWorkitGlobals(args: readonly string[]): { rest: string[]; cwd: string | null } {
   let cwd: string | null = null;
   let at = 0;
@@ -804,7 +819,18 @@ export function skipWorkitGlobals(args: readonly string[]): { rest: string[]; cw
       at++;
     } else if (args[at] !== "--json") break;
   }
-  return { rest: args.slice(at), cwd };
+  const rest: string[] = [];
+  for (; at < args.length; at++) {
+    const arg = args[at];
+    if (arg === "--") {
+      rest.push(...args.slice(at));
+      break;
+    }
+    if (arg.startsWith("--cwd=")) cwd = arg.slice("--cwd=".length);
+    else if (arg === "--cwd" && args[at + 1] !== undefined) cwd = args[++at];
+    else rest.push(arg);
+  }
+  return { rest, cwd };
 }
 
 /** What one raw invocation means for workit. */