@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.33 → 0.1.34

package/bin/adl

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/adl
-size: 82920928 bytes
-sha256: 3e480a5aff47ee61aec30d26dad9d06dc8f3c4b33ca4b5ed1b8ef9b4a810bb99
+size: 82945504 bytes
+sha256: b6594d01b2ebea8949f80faa8da029598f8be7513fb1e3c7b63ddc01df4c8f02

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/adl-agent-control-linux-x64",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "adl CLI binary for linux/x64 (agent identity + Azure DevOps front door — see docs/architecture/cli-design.md)",
   "license": "UNLICENSED",
   "os": [

package/packages/agent-hooks/src/rules/impl/git-branch.ts

@@ -0,0 +1,63 @@
+// PBI 661 (Tarun, 2026-10-09): agents never change branches; both denies say "ask the user for git branch operations". See docs/architecture/agent-git-branch-rules.md
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { branchMutates, isHelpOnlyInvocation, isSequencerRecoveryOnly, switchCheckoutCreatesBranch } from './git-helpers.ts'
+import { LANDING_SUBCOMMANDS, resolveGitTarget } from './git-target.ts'
+import { gitAgentTail } from './messages.ts'
+
+const ASK_USER = 'ask the user for git branch operations'
+
+const UNRESOLVED =
+  'The commit target (which repository and branch this would land on) could not be determined statically from this command line. ' +
+  'Run `git commit` as its own command, or with `git -C <path>`, so the target is explicit. '
+
+function askUserMessage(ctx: MessageContext, unresolved = false) {
+  return { user: ASK_USER, agent: `DENIED ${ASK_USER}. ${unresolved ? UNRESOLVED : ''}${gitAgentTail(ctx.snippet)}` }
+}
+
+export const gitBranchMutation: RuleSpec = {
+  id: 'git.branch-mutation',
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny every mutating git branch form and branch creation via git switch -c / git checkout -b.',
+  params: noParams,
+  match(inv: Invocation): Finding | null {
+    if (inv.kind !== 'git') return null
+    const hit =
+      inv.subcommand === 'branch' ? branchMutates(inv.rest) : inv.subcommand === 'switch' || inv.subcommand === 'checkout' ? switchCheckoutCreatesBranch(inv.subcommand, inv.rest) : false
+    return hit ? { ruleId: 'git.branch-mutation', severity: 'deny', detail: {} } : null
+  },
+  message: (_finding: Finding, ctx: MessageContext) => askUserMessage(ctx),
+  corpus: {
+    deny: ['git branch foo', 'git branch -D old-feature', 'git branch -aD', 'git branch --delete --force old-feature', 'git branch -m old new', 'git switch -c new-branch', 'git checkout -b new-branch'],
+    allow: ['git branch', 'git branch -a', 'git branch -vv', 'git branch --show-current', "git branch --list 'feat/*'", 'git switch main', 'git checkout feature-x'],
+  },
+}
+
+export const gitCommitProtectedBranch: RuleSpec = {
+  id: 'git.commit-protected-branch',
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny git commit (and merge, cherry-pick, revert, am) while the target repo is on a protected branch, or when the target or its branch cannot be resolved.',
+  params: noParams,
+  match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
+    if (inv.kind !== 'git' || !LANDING_SUBCOMMANDS.has(inv.subcommand)) return null
+    if (isHelpOnlyInvocation(inv.rest)) return null // prints text, commits nothing
+    if (inv.subcommand !== 'commit' && isSequencerRecoveryOnly(inv.rest)) return null // --abort / --quit only end an operation
+    const target = resolveGitTarget(inv, ctx.command)
+    // null target or branch = unresolved: fail closed (docs/architecture/agent-git-branch-rules.md)
+    const branch = target === null ? null : ctx.index.currentBranch(target)
+    if (branch !== null && !ctx.agentConfig.protectedBranches.includes(branch)) return null
+    return { ruleId: 'git.commit-protected-branch', severity: 'deny', detail: { unresolved: branch === null ? 'yes' : 'no' } }
+  },
+  message: (finding: Finding, ctx: MessageContext) => askUserMessage(ctx, finding.detail['unresolved'] === 'yes'),
+  // Fixture branch is never protected, so deny entries are the fail-closed ones (docs/architecture/agent-git-branch-rules.md)
+  corpus: {
+    deny: ['cd "$REPO" && git commit -m x', 'git -C "$REPO" commit -m x', 'GIT_DIR="$D" git merge origin/integration'],
+    allow: ["git commit -m 'feat(x): y'", 'git status'],
+  },
+}

package/packages/agent-hooks/src/rules/impl/git-helpers.ts

@@ -61,9 +61,97 @@ export function commitAmends(rest: readonly Token[]): boolean {
   return hasFlag(rest, '--amend')
 }
 
-export function branchForceDeletes(rest: readonly Token[]): boolean {
-  if (hasFlagOrCluster(rest, [], ['D'])) return true
-  return hasFlagOrCluster(rest, ['--delete'], ['d']) && hasFlagOrCluster(rest, ['--force'], ['f'])
+/**
+ * Every long option `git branch -h` lists on git 2.56 (positive forms), plus the
+ * legacy `--set-upstream`. Used ONLY to resolve unique prefixes the way git's
+ * parse-options does; whether an option is allowed is `BRANCH_READ_ONLY_OPTIONS`.
+ */
+const BRANCH_POSITIVE_OPTIONS: readonly string[] = [
+  'verbose', 'quiet', 'track', 'set-upstream-to', 'set-upstream', 'unset-upstream', 'color', 'remotes', 'contains', 'no-contains', 'abbrev', 'all',
+  'delete', 'move', 'omit-empty', 'copy', 'list', 'show-current', 'create-reflog', 'edit-description', 'delete-merged', 'dry-run', 'force', 'merged',
+  'no-merged', 'forked', 'column', 'sort', 'points-at', 'ignore-case', 'recurse-submodules', 'format', 'help',
+]
+const BRANCH_ALL_OPTIONS: readonly string[] = [...new Set([...BRANCH_POSITIVE_OPTIONS, ...BRANCH_POSITIVE_OPTIONS.filter((name) => !name.startsWith('no-') && name !== 'help' && name !== 'remotes' && name !== 'all').map((name) => `no-${name}`)])]
+/** PBI 661 allowlist: the only `git branch` options that read and never write. Anything else (known or not) is a deny. */
+const BRANCH_READ_ONLY_OPTIONS: ReadonlySet<string> = new Set([
+  'verbose', 'quiet', 'color', 'remotes', 'all', 'list', 'show-current', 'omit-empty', 'ignore-case', 'dry-run', 'abbrev', 'column', 'help',
+  'contains', 'no-contains', 'merged', 'no-merged', 'forked', 'sort', 'points-at', 'format',
+  'no-verbose', 'no-quiet', 'no-color', 'no-abbrev', 'no-column', 'no-sort', 'no-points-at', 'no-format', 'no-omit-empty', 'no-ignore-case', 'no-dry-run',
+])
+/** Read-only options whose separate next token is their value. */
+const BRANCH_VALUE_OPTIONS: ReadonlySet<string> = new Set(['contains', 'no-contains', 'merged', 'no-merged', 'forked', 'sort', 'points-at', 'format'])
+/** Read-only options that put `git branch` in list mode, where positionals are patterns, not new branch names. */
+const BRANCH_LIST_OPTIONS: ReadonlySet<string> = new Set(['list', 'show-current', 'contains', 'no-contains', 'merged', 'no-merged', 'points-at', 'forked'])
+/** `-v -q -r -a -l -i`, alone or clustered; every other short letter writes or is unknown. */
+const BRANCH_READ_ONLY_LETTERS: readonly string[] = ['v', 'q', 'r', 'a', 'l', 'i']
+
+/** git's parse-options rule: an exact name wins, else the unique name that starts with `name`; `null` when unknown or ambiguous. */
+function resolveLongOption(name: string, table: readonly string[]): string | null {
+  if (table.includes(name)) return name
+  const candidates = table.filter((candidate) => candidate.startsWith(name))
+  return candidates.length === 1 ? (candidates[0] as string) : null
+}
+
+/**
+ * PBI 661: does this `git branch` argv change branches, or might it? Fail
+ * closed: only an argv made entirely of known read-only options (long options
+ * resolved by unique prefix as git does) is false. A bare positional with no
+ * list-mode option is a branch name to CREATE, so it is true.
+ */
+export function branchMutates(rest: readonly Token[]): boolean {
+  if (isHelpOnlyInvocation(rest)) return false
+  let listMode = false
+  let positionals = 0
+  for (let index = 0; index < rest.length; index++) {
+    const value = tokenValue(rest[index] as Token)
+    if (value === '--') {
+      positionals += rest.length - index - 1
+      break
+    }
+    if (value.startsWith('--')) {
+      const name = resolveLongOption(value.slice(2).split('=')[0] as string, BRANCH_ALL_OPTIONS)
+      if (name === null || !BRANCH_READ_ONLY_OPTIONS.has(name)) return true
+      if (BRANCH_LIST_OPTIONS.has(name)) listMode = true
+      if (BRANCH_VALUE_OPTIONS.has(name) && !value.includes('=')) index++
+    } else if (value.startsWith('-') && value.length > 1) {
+      const letters = [...value.slice(1)]
+      if (letters.some((letter) => !BRANCH_READ_ONLY_LETTERS.includes(letter))) return true
+      if (letters.includes('l')) listMode = true
+    } else {
+      positionals++
+    }
+  }
+  return positionals > 0 && !listMode
+}
+
+/** Long options that create a branch, per subcommand; `NON_CREATING` are the long options whose exact name must win over a longer creating one. */
+const CREATING_LONG_OPTIONS: Readonly<Record<string, readonly string[]>> = {
+  switch: ['create', 'force-create', 'orphan', 'track'],
+  checkout: ['orphan', 'track'],
+}
+const NON_CREATING_LONG_OPTIONS: readonly string[] = ['force', 'detach', 'discard-changes', 'merge', 'conflict', 'quiet', 'progress', 'no-progress', 'guess', 'no-guess', 'no-track', 'ignore-other-worktrees', 'recurse-submodules', 'no-recurse-submodules', 'overlay', 'no-overlay', 'ours', 'theirs', 'patch']
+
+/**
+ * PBI 661: `git switch -c/-C/-t/--create/--force-create/--orphan/--track` and
+ * `git checkout -b/-B/-t/--orphan/--track` create a branch, including any
+ * unique (or ambiguous-with-a-creating) long-option prefix (`--cr`, `--force-c`,
+ * `--orp`, `--tr`). Plain `git switch|checkout <existing>` is not matched.
+ */
+export function switchCheckoutCreatesBranch(subcommand: string, rest: readonly Token[]): boolean {
+  const longs = CREATING_LONG_OPTIONS[subcommand] ?? []
+  const letters = subcommand === 'switch' ? ['c', 'C', 't'] : ['b', 'B', 't']
+  for (const token of rest) {
+    const value = tokenValue(token)
+    if (value === '--') return false
+    if (value.startsWith('--')) {
+      const name = value.slice(2).split('=')[0] as string
+      if (longs.includes(name)) return true
+      if (name.length > 0 && !NON_CREATING_LONG_OPTIONS.includes(name) && longs.some((long) => long.startsWith(name))) return true
+    } else if (value.startsWith('-') && value.length > 1 && [...value.slice(1)].some((letter) => letters.includes(letter))) {
+      return true
+    }
+  }
+  return false
 }
 
 export function tagDeletes(rest: readonly Token[]): boolean {

package/packages/agent-hooks/src/rules/impl/git-history.ts

@@ -1,18 +1,18 @@
 /**
- * `branch -D`, `tag -d`, `switch -f`, `gc --prune[=<date>]`.
+ * `tag -d`, `switch -f`, `gc --prune[=<date>]`.
  * (`update-ref` in every form lives in git-plumbing.ts.)
  *
  * Ported from `blockedGitHistoryReason` in blocked-reason.mjs:78-86. None of
  * these bypass on a bare `--help`/`--version` the way the "core" rules do —
  * the original's `blockedGitPolicyReason` is called unconditionally, with no
- * `rmIsHelpOnly` gate — so neither does this. All four fall through
+ * `rmIsHelpOnly` gate — so neither does this. All three fall through
  * `classifyReason`'s default arm.
  */
 
 import type { Invocation } from '../shell/invocation.ts'
 import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
-import { branchForceDeletes, gcPrunesExplicitly, switchIsForced, tagDeletes } from './git-helpers.ts'
+import { gcPrunesExplicitly, switchIsForced, tagDeletes } from './git-helpers.ts'
 import { defaultGitMessage, detailString } from './messages.ts'
 
 function git(inv: Invocation): (Invocation & { kind: 'git' }) | null {
@@ -40,15 +40,6 @@ function make(id: string, subcommand: string, reasonFor: () => string, hits: (g:
   }
 }
 
-export const gitBranchForceDelete = make(
-  'git.branch-force-delete',
-  'branch',
-  () => 'git branch -D',
-  (g) => branchForceDeletes(g.rest),
-  ['git branch -D old-feature', 'git branch -aD', 'git branch --delete --force old-feature'],
-  ['git branch -d merged-feature', 'git branch feature-x', 'git branch -a'],
-)
-
 export const gitTagDelete = make(
   'git.tag-delete',
   'tag',
@@ -64,7 +55,7 @@ export const gitSwitchForce = make(
   () => 'git switch -f',
   (g) => switchIsForced(g.rest),
   ['git switch -f main', 'git switch --force main'],
-  ['git switch main', 'git switch -c new-branch'],
+  ['git switch main', 'git switch feat/existing'],
 )
 
 export const gitGcPrune = make(

package/packages/agent-hooks/src/rules/impl/git-target.ts

@@ -0,0 +1,423 @@
+// Best-effort static resolver of the repository a commit-like git command lands on. See docs/architecture/agent-git-branch-rules.md#resolver
+
+import { statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import type { BranchTarget } from '../ports.ts'
+import type { Invocation } from '../shell/invocation.ts'
+import { withoutRedirections } from '../shell/git-internals.ts'
+import { splitShell } from '../shell/split.ts'
+import { findMatchingBacktick, findMatchingParen } from '../shell/substitution.ts'
+import { type Token, basename, tokenValue, tokenize } from '../shell/token.ts'
+
+// Subcommands that add history to the current branch (pull, rebase, reset, amend are excluded: see docs/architecture/agent-git-branch-rules.md)
+export const LANDING_SUBCOMMANDS: ReadonlySet<string> = new Set(['commit', 'merge', 'cherry-pick', 'revert', 'am'])
+
+const ASSIGNMENT_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/
+const SHELLS: ReadonlySet<string> = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh'])
+/** Commands that re-run another command: a shell `-c` script behind one is followed. */
+const RE_EXECUTORS: ReadonlySet<string> = new Set(['xargs', 'parallel', 'env', 'nice', 'nohup', 'timeout', 'sudo', 'doas'])
+
+// Bash builtins and reserved words: `compgen -b` + `compgen -k` on bash 5.3 (docs/architecture/agent-git-branch-rules.md#closed-builtin-sets-and-their-provenance)
+const BASH_BUILTINS_AND_KEYWORDS: readonly string[] = (
+  '. : [ alias bg bind break builtin caller cd command compgen complete compopt continue declare dirs disown echo enable eval exec exit export false fc fg getopts hash help history jobs kill let local logout mapfile popd printf pushd pwd read readarray readonly return set shift shopt source suspend test times trap true type typeset ulimit umask unalias unset wait if then else elif fi case esac for select while until do done in function time { } ! [[ ]] coproc').split(' ')
+// zsh builtins and reserved words: `zsh -c 'print ${(k)builtins} ${(k)reswords}'` on zsh 5.9 (same doc section)
+const ZSH_BUILTINS_AND_RESERVED_WORDS: readonly string[] = (
+  'unset rehash popd ulimit local jobs disable [ compfiles printf autoload noglob pushln zle readonly exit false times sched setopt getln builtin let bg which unhash pwd zparseopts logout disown type source eval comptags compdescribe compctl r zmodload zregexparse history return exec compadd emulate chdir ttyctl test comparguments pushd functions float zstyle print declare comptry alias shift - . bindkey typeset true hash compset cd compvalues getopts compgroups export enable limit echotc echo wait dirs unsetopt read : integer bye echoti compquote unfunction fc vared unalias kill compcall where fg zformat suspend unlimit break set continue command zcompile whence umask trap log private if else end do then { select coproc } ! case [[ repeat done for while time esac until fi nocorrect foreach elif function'
+).split(' ')
+/** The closed set of shell builtins and reserved words (bash 5.3 + zsh 5.9): a head outside it is an external command or a function. */
+const SHELL_BUILTINS_AND_KEYWORDS: ReadonlySet<string> = new Set([...BASH_BUILTINS_AND_KEYWORDS, ...ZSH_BUILTINS_AND_RESERVED_WORDS])
+/** Builtins that only print or test: neutral (`printf -v` / `print -v` assign a variable and are not). */
+const READ_ONLY_BUILTINS: ReadonlySet<string> = new Set(['echo', 'printf', 'print', 'which', 'whence', 'where', 'true', 'false', 'test', '[', '[[', 'pwd', 'type', 'hash', 'help', ':', 'times', 'dirs', 'jobs'])
+/** Variables whose assignment (or export, or unset) changes what a later cd, `~` or shell startup does: unknown. */
+const SENSITIVE_VARIABLES: ReadonlySet<string> = new Set(['BASH_ENV', 'ENV', 'HOME', 'CDPATH', 'ZDOTDIR', 'PATH'])
+/** Variables that, as a prefix on a launched shell, change what that shell runs or means. */
+const SHELL_STARTUP_VARIABLES: ReadonlySet<string> = new Set(['BASH_ENV', 'ENV', 'ZDOTDIR', 'HOME', 'CDPATH'])
+/** git subcommands that move HEAD (or the worktree it is read from): after one, the branch a later landing command hits is unknown. */
+const HEAD_MOVERS: ReadonlySet<string> = new Set(['switch', 'checkout', 'worktree', 'stash', 'bisect', 'rebase', 'reset'])
+const GIT_VALUE_GLOBALS: ReadonlySet<string> = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env'])
+
+/** Does this piece run `git <HEAD_MOVER> ...` (behind any wrapper)? */
+function movesHead(rest: readonly Token[]): boolean {
+  const gitAt = rest.findIndex((token) => ['git', 'git.exe'].includes(basename(token)))
+  if (gitAt < 0) return false
+  for (let i = gitAt + 1; i < rest.length; i++) {
+    const value = tokenValue(rest[i] as Token)
+    if (value.startsWith('-')) {
+      if (GIT_VALUE_GLOBALS.has(value)) i++
+      continue
+    }
+    const subcommand = value.toLowerCase()
+    if (!HEAD_MOVERS.has(subcommand)) return false
+    // Read-only forms of stash/worktree do not move HEAD: `stash list|show`, `worktree list`.
+    const action = rest.slice(i + 1).map((token) => tokenValue(token)).find((arg) => !arg.startsWith('-'))
+    if (subcommand === 'stash' && (action === 'list' || action === 'show')) return false
+    if (subcommand === 'worktree' && action === 'list') return false
+    return true
+  }
+  return false
+}
+
+function namesDirectory(word: string): boolean {
+  try {
+    return statSync(word).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+interface Mutable {
+  dirs: string[]
+  gitDir?: string
+  workTree?: string
+  /** `HOME=` was assigned for this command: `~` no longer means the home directory we know. */
+  homeUnknown?: boolean
+}
+
+/** `~`, `~/x`, `$HOME`, `${HOME}` expand to the home directory; any other `$` or backtick is not static (`null`). */
+function expandPath(value: string, target: Mutable): string | null {
+  const home = homedir()
+  const tilde = value === '~' || value.startsWith('~/')
+  if (tilde) return target.homeUnknown === true ? null : home + value.slice(1)
+  for (const prefix of ['${HOME}', '$HOME']) {
+    if (value === prefix || value.startsWith(`${prefix}/`)) return target.homeUnknown === true ? null : home + value.slice(prefix.length)
+  }
+  return /[$`]/.test(value) || value === '' ? null : value
+}
+
+/** Apply `NAME=value` env assignments we care about; false when one is not static. */
+function applyEnv(target: Mutable, assignments: readonly string[]): boolean {
+  for (const assignment of assignments) {
+    const match = ASSIGNMENT_RE.exec(assignment)
+    if (!match) continue
+    const name = match[1] as string
+    if (name !== 'GIT_DIR' && name !== 'GIT_WORK_TREE') continue
+    const value = expandPath(match[2] as string, target)
+    if (value === null) return false
+    if (name === 'GIT_DIR') target.gitDir = value
+    else target.workTree = value
+  }
+  return true
+}
+
+function leadingAssignments(tokens: readonly Token[]): { assignments: string[]; rest: Token[] } {
+  let index = 0
+  const assignments: string[] = []
+  while (index < tokens.length && ASSIGNMENT_RE.test(tokenValue(tokens[index] as Token))) assignments.push(tokenValue(tokens[index++] as Token))
+  return { assignments, rest: tokens.slice(index) as Token[] }
+}
+
+/** `--git-dir`, `--work-tree`, `-C` among git's globals; false when one is not static. */
+function applyGlobals(target: Mutable, globals: readonly Token[]): boolean {
+  const values = globals.map((token) => tokenValue(token))
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index] as string
+    const take = (long: string): string | null => {
+      if (value === long) return values[++index] ?? ''
+      if (value.startsWith(`${long}=`)) return value.slice(long.length + 1)
+      return null
+    }
+    const gitDir = take('--git-dir')
+    if (gitDir !== null) {
+      const expanded = expandPath(gitDir, target)
+      if (expanded === null) return false
+      target.gitDir = expanded
+      continue
+    }
+    const workTree = take('--work-tree')
+    if (workTree !== null) {
+      const expanded = expandPath(workTree, target)
+      if (expanded === null) return false
+      target.workTree = expanded
+      continue
+    }
+    if (value === '-C' || (value.startsWith('-C') && value.length > 2)) {
+      const dir = expandPath(value === '-C' ? (values[++index] ?? '') : value.slice(2), target)
+      if (dir === null) return false
+      target.dirs.push(dir)
+    }
+  }
+  return true
+}
+
+/** Does this piece run our git invocation (possibly behind `env`/`command`/`builtin`/another wrapper)? */
+function runsInvocation(piece: readonly Token[], inv: Invocation & { kind: 'git' }): boolean {
+  const tokens = withoutRedirections(piece) // the classifier's `rest` has none either (`git commit -F - <<EOF`)
+  const values = tokens.map((token) => tokenValue(token))
+  const wanted = inv.rest.map((token) => tokenValue(token))
+  const tail = wanted.length === 0 ? values : values.slice(-wanted.length)
+  const gitAt = tokens.findIndex((token) => ['git', 'git.exe'].includes(basename(token)))
+  return gitAt >= 0 && values.indexOf(inv.subcommand, gitAt) > gitAt && tail.length === wanted.length && tail.every((value, index) => value === wanted[index])
+}
+
+/** Assignments reaching git from the piece: leading `NAME=v`, and `env NAME=v ...`. `null` when `env` carries options we do not model. */
+function pieceAssignments(tokens: readonly Token[]): string[] | null {
+  const { assignments, rest } = leadingAssignments(tokens)
+  let index = 0
+  while (index < rest.length && !['git', 'git.exe'].includes(basename(rest[index] as Token))) {
+    const name = basename(rest[index] as Token)
+    if (name === 'env') {
+      index++
+      while (index < rest.length && ASSIGNMENT_RE.test(tokenValue(rest[index] as Token))) assignments.push(tokenValue(rest[index++] as Token))
+      if (index < rest.length && tokenValue(rest[index] as Token).startsWith('-') && !['git', 'git.exe'].includes(basename(rest[index] as Token))) return null
+    } else if (name === 'command' || name === 'builtin') {
+      index++
+      while (index < rest.length && ['-p', '--'].includes(tokenValue(rest[index] as Token))) index++
+    } else {
+      index++ // another wrapper (nohup, time, ...): no environment of ours
+    }
+  }
+  return assignments
+}
+
+interface Parsed {
+  readonly tokens: readonly (readonly Token[] | null)[]
+  /** Text between consecutive pieces (operators, group characters, comments); `null` when the pieces could not be located in the source. */
+  readonly gaps: readonly string[] | null
+  /** Names of functions defined anywhere in the command (`f() {`, `function f`): a piece headed by one is unknown. */
+  readonly functions: ReadonlySet<string>
+}
+
+/** Heredoc delimiters opened by `<<` / `<<-` at the top level of one piece, or `'unparsable'`. Quotes, `\x` and `$(...)` are skipped. */
+function heredocDelimiters(piece: string): string[] | 'unparsable' {
+  const delimiters: string[] = []
+  for (let i = 0; i < piece.length; i++) {
+    const char = piece[i] as string
+    if (char === '\\') i++
+    else if (char === "'") {
+      const close = piece.indexOf("'", i + 1)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '"') {
+      let j = i + 1
+      while (j < piece.length && piece[j] !== '"') j += piece[j] === '\\' ? 2 : 1
+      if (j >= piece.length) return 'unparsable'
+      i = j
+    } else if (char === '`') {
+      const close = findMatchingBacktick(piece, i)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '$' && piece[i + 1] === '(') {
+      const close = findMatchingParen(piece, i + 1)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '<' && piece[i + 1] === '<' && piece[i + 2] !== '<' && piece[i - 1] !== '<') {
+      i += 2
+      if (piece[i] === '-') i++
+      while (piece[i] === ' ' || piece[i] === '\t') i++
+      let word = ''
+      let sawWord = false
+      for (; i < piece.length && !/[\s;|&<>()]/.test(piece[i] as string); i++) {
+        sawWord = true
+        const c = piece[i] as string
+        if (c === '\\') word += piece[++i] ?? ''
+        else if (c === "'" || c === '"') {
+          const close = piece.indexOf(c, i + 1)
+          if (close < 0) return 'unparsable'
+          word += piece.slice(i + 1, close)
+          i = close
+        } else word += c
+      }
+      if (!sawWord) return 'unparsable'
+      delimiters.push(word)
+      i--
+    }
+  }
+  return delimiters
+}
+
+/** `null`: unparseable (parse.uncertain refuses it). `'closed'`: a heredoc we cannot account for -- fail closed. */
+function parse(command: string): Parsed | null | 'closed' {
+  const split = splitShell(command)
+  if (split.invalid) return null
+  const tokens: (readonly Token[] | null)[] = split.pieces.map((piece) => {
+    const tokenized = tokenize(piece)
+    return tokenized.invalid ? null : tokenized.tokens
+  })
+  const functions = new Set<string>()
+  for (const match of command.matchAll(/([A-Za-z_][\w.:-]*)\s*\(\s*\)/g)) functions.add(match[1] as string)
+  for (const match of command.matchAll(/\bfunction\s+([A-Za-z_][\w.:-]*)/g)) functions.add(match[1] as string)
+  const gaps: string[] = []
+  let cursor = 0
+  for (const piece of split.pieces) {
+    const at = command.indexOf(piece, cursor)
+    if (at < 0) return { tokens, gaps: null, functions }
+    gaps.push(command.slice(cursor, at))
+    cursor = at + piece.length
+  }
+  // Heredoc body lines are not commands: drop them (docs/architecture/agent-git-branch-rules.md#resolver)
+  for (let i = 0; i < split.pieces.length; i++) {
+    const delimiters = heredocDelimiters(split.pieces[i] as string)
+    if (delimiters === 'unparsable') return 'closed'
+    if (delimiters.length === 0) continue
+    let body = i + 1
+    while (body < split.pieces.length && !(gaps[body] as string).includes('\n')) body++ // rest of the marker's own line
+    for (const delimiter of delimiters) {
+      let closed = false
+      for (; body < split.pieces.length && !closed; body++) {
+        closed = (split.pieces[body] as string).trim() === delimiter
+        tokens[body] = null
+        gaps[body] = '\n'
+      }
+      if (!closed) return 'closed'
+    }
+    i = body - 1
+  }
+  return { tokens, gaps, functions }
+}
+
+/** The gap as an operator when it is exactly `&&`, `;` or a newline; `null` for anything else (`||`, `|`, `&`, `(`, `{`, ...). */
+function plainGap(gap: string): '&&' | ';' | null {
+  const normalized = gap.replace(/#[^\n]*/g, '').replace(/\s*\n\s*/g, ';').replace(/\s+/g, '').replace(/;+/g, ';')
+  return normalized === '&&' ? '&&' : normalized === ';' || normalized === '' ? ';' : null
+}
+
+type StatePiece =
+  | { kind: 'cd'; dir: string }
+  | { kind: 'export'; assignments: string[] }
+  | { kind: 'unset'; names: string[] }
+  | { kind: 'bad' }
+  | { kind: 'neutral' }
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const SET_CLUSTER_RE = /^[-+][eux]*$/
+const SET_O_VALUES: readonly string[] = ['pipefail', 'errexit', 'nounset']
+
+/** `set` with only -e/-u/-x/+e/+u/+x (clusters allowed, `-euo pipefail`) and `-o|+o pipefail|errexit|nounset`. */
+function harmlessSet(args: readonly string[]): boolean {
+  if (args.length === 0) return false
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string
+    const cluster = /^([-+][eux]*)o$/.exec(arg)
+    if (cluster !== null || arg === '-o' || arg === '+o') {
+      if (!SET_O_VALUES.includes(args[++i] ?? '')) return false
+    } else if (!SET_CLUSTER_RE.test(arg) || arg.length < 2) {
+      return false
+    }
+  }
+  return true
+}
+
+function classify(piece: readonly Token[] | null, functions: ReadonlySet<string>): StatePiece {
+  if (piece === null) return { kind: 'neutral' }
+  const { assignments, rest } = leadingAssignments(withoutRedirections(piece))
+  const names = assignments.map((assignment) => assignment.split('=')[0] as string)
+  if (names.some((name) => name.startsWith('GIT_'))) return rest.length === 0 ? { kind: 'bad' } : classifyHead(rest, assignments, functions)
+  if (rest.length === 0) return names.some((name) => SENSITIVE_VARIABLES.has(name)) ? { kind: 'bad' } : { kind: 'neutral' }
+  return classifyHead(rest, assignments, functions)
+}
+
+function classifyHead(rest: readonly Token[], assignments: readonly string[], functions: ReadonlySet<string>): StatePiece {
+  const head = tokenValue(rest[0] as Token)
+  const args = rest.slice(1).map((token) => tokenValue(token))
+  if (/[$`]/.test(head) || functions.has(head)) return { kind: 'bad' }
+  if (!SHELL_BUILTINS_AND_KEYWORDS.has(head)) {
+    if (movesHead(rest)) return { kind: 'bad' }
+    // zsh autocd: a path (or a bare word naming a directory) used as a command changes directory.
+    if (head.includes('/') && !['git', 'git.exe'].includes(basename(rest[0] as Token))) return { kind: 'bad' }
+    if (head.startsWith('~') || head === '..' || (!head.includes('/') && namesDirectory(head))) return { kind: 'bad' }
+    // An external command cannot change this shell, but a shell it launches runs its startup files first.
+    const startup = assignments.some((assignment) => SHELL_STARTUP_VARIABLES.has(assignment.split('=')[0] as string))
+    return startup && (SHELLS.has(basename(rest[0] as Token)) || RE_EXECUTORS.has(basename(rest[0] as Token))) ? { kind: 'bad' } : { kind: 'neutral' }
+  }
+  if (READ_ONLY_BUILTINS.has(head)) return (head === 'printf' || head === 'print') && args.includes('-v') ? { kind: 'bad' } : { kind: 'neutral' }
+  if (head === 'command' && (args[0] === '-v' || args[0] === '-V')) return { kind: 'neutral' }
+  if (head === 'set') return harmlessSet(args) ? { kind: 'neutral' } : { kind: 'bad' }
+  if (head === 'cd' || head === 'pushd') return args.length !== 1 || args[0] === '' || (args[0] as string).startsWith('-') ? { kind: 'bad' } : { kind: 'cd', dir: args[0] as string }
+  if (head === 'export') {
+    if (args.length > 0 && args.every((arg) => /^GIT_(DIR|WORK_TREE)=/.test(arg))) return { kind: 'export', assignments: args }
+    return args.every((arg) => NAME_RE.test(arg.split('=')[0] as string) && !arg.startsWith('GIT_') && !SENSITIVE_VARIABLES.has(arg.split('=')[0] as string)) ? { kind: 'neutral' } : { kind: 'bad' }
+  }
+  if (head === 'unset') return args.every((arg) => NAME_RE.test(arg) && !SENSITIVE_VARIABLES.has(arg)) ? { kind: 'unset', names: args } : { kind: 'bad' }
+  return { kind: 'bad' }
+}
+
+// Credit or reject the pieces before `until`; fail closed on anything unknown. // See docs/architecture/agent-git-branch-rules.md#resolver
+function applyState(parsed: Parsed, until: number, target: Mutable): boolean {
+  for (let i = 0; i < until; i++) {
+    const state = classify(parsed.tokens[i] ?? null, parsed.functions)
+    if (state.kind === 'neutral') continue
+    if (state.kind === 'bad') return false
+    if (state.kind === 'unset') {
+      if (state.names.includes('GIT_DIR')) delete target.gitDir
+      if (state.names.includes('GIT_WORK_TREE')) delete target.workTree
+      continue
+    }
+    if (parsed.gaps === null) return false
+    const before = plainGap(parsed.gaps[i] as string)
+    if (before === null) return false
+    if (before === '&&' && (i === 0 || !['cd', 'export'].includes(classify(parsed.tokens[i - 1] ?? null, parsed.functions).kind))) return false
+    for (let j = i + 1; j <= Math.min(until, parsed.gaps.length - 1); j++) if (plainGap(parsed.gaps[j] as string) === null) return false
+    if (state.kind === 'cd') {
+      const dir = expandPath(state.dir, target)
+      if (dir === null) return false
+      target.dirs.push(dir)
+    } else if (!applyEnv(target, state.assignments)) {
+      return false
+    }
+  }
+  return true
+}
+
+// The `-c` script of a (re-executor-wrapped) shell piece, or 'unsafe' when a startup-file variable is set. // See docs/architecture/agent-git-branch-rules.md#resolver
+function shellScript(tokens: readonly Token[]): string | null | 'unsafe' {
+  const { rest } = leadingAssignments(tokens)
+  if (rest[0] === undefined) return null
+  let shellAt = 0
+  if (!SHELLS.has(basename(rest[0]))) {
+    if (!RE_EXECUTORS.has(basename(rest[0]))) return null
+    shellAt = rest.findIndex((token, index) => index > 0 && SHELLS.has(basename(token)))
+    if (shellAt < 0) return null
+  }
+  for (let index = shellAt + 1; index < rest.length - 1; index++) {
+    if (/^-[a-zA-Z]*c$/.test(tokenValue(rest[index] as Token))) {
+      const assignments = pieceAssignments(tokens)
+      return assignments === null || assignments.some((assignment) => SHELL_STARTUP_VARIABLES.has(assignment.split('=')[0] as string)) ? 'unsafe' : tokenValue(rest[index + 1] as Token)
+    }
+  }
+  return null
+}
+
+/** `undefined`: the invocation is not in `command`. `null`: it is, but its target is not static. */
+function walk(command: string, inv: Invocation & { kind: 'git' }, inherited: Mutable): BranchTarget | null | undefined {
+  const parsed = parse(command)
+  if (parsed === null) return undefined // unparseable: parse.uncertain's job to refuse
+  if (parsed === 'closed') return null
+  for (let i = 0; i < parsed.tokens.length; i++) {
+    const tokens = parsed.tokens[i]
+    if (tokens === null || tokens === undefined) continue
+    const target: Mutable = { ...inherited, dirs: [...inherited.dirs] }
+    if (runsInvocation(tokens, inv)) {
+      const assignments = pieceAssignments(tokens)
+      if (assignments === null || !applyState(parsed, i, target)) return null
+      if (assignments.some((assignment) => assignment.startsWith('HOME='))) target.homeUnknown = true
+      if (!applyEnv(target, assignments) || !applyGlobals(target, inv.globals)) return null
+      return target
+    }
+    const script = shellScript(tokens)
+    if (script === null) continue
+    if (script === 'unsafe') {
+      // The startup file may do anything, but only matters when our git is in there.
+      const unsafeInner = tokens.some((token) => tokenValue(token).includes(inv.subcommand))
+      if (unsafeInner) return null
+      continue
+    }
+    const probe: Mutable = { ...inherited, dirs: [...inherited.dirs] }
+    const inner = walk(script, inv, probe)
+    if (inner === undefined) continue
+    if (inner === null || !applyState(parsed, i, target)) return null
+    const nested = walk(script, inv, target)
+    return nested ?? null
+  }
+  return undefined
+}
+
+/** The statically resolved target of `inv` inside `command`, or `null` when it cannot be resolved. */
+export function resolveGitTarget(inv: Invocation & { kind: 'git' }, command: string | undefined): BranchTarget | null {
+  const found = command === undefined ? undefined : walk(command, inv, { dirs: [] })
+  if (found !== undefined) return found
+  // Not found as a piece (xargs, find -exec, ...): its own globals, after any unconditional cd/export before it.
+  const target: Mutable = { dirs: [] }
+  const parsed = command === undefined ? null : parse(command)
+  if (parsed === 'closed' || (parsed !== null && !applyState(parsed, parsed.tokens.length, target))) return null
+  return applyGlobals(target, inv.globals) ? target : null
+}

package/packages/agent-hooks/src/rules/ports.ts

@@ -45,6 +45,14 @@ export interface AgentPort {
  * `git.protected-tree-commit` can fail closed on "could not read the index"
  * instead of silently treating an unreadable index as a clean one.
  */
+/** Where a git invocation points, statically resolved from its command line (see `impl/git-target.ts`). */
+export interface BranchTarget {
+  /** `cd <dir>` and `git -C <dir>` values, in the order git applies them. */
+  readonly dirs: readonly string[]
+  readonly gitDir?: string
+  readonly workTree?: string
+}
+
 export interface RepoIndexPort {
   stagedPaths(): readonly string[] | null
   trackedModifiedPaths(): readonly string[] | null
@@ -64,6 +72,14 @@ export interface RepoIndexPort {
    * absent) the same as `null` (present, resolved to nothing).
    */
   configuredAlias?(verb: string): string | null
+  /**
+   * The checked-out branch of the repo a git invocation targets: the hook's
+   * root with `target.dirs` applied as `-C <dir>` values in order (relative
+   * ones composed), then `--git-dir` / `--work-tree` when given. `''` for a detached HEAD, `null` when it cannot be read (not a
+   * repository, git missing, timeout) so `git.commit-protected-branch` can
+   * fail closed instead of treating an unreadable HEAD as a safe one.
+   */
+  currentBranch(target: BranchTarget): string | null
 }
 
 export const liveEnv: EnvPort = {
@@ -159,6 +175,26 @@ export function liveRepoIndex(root: string): RepoIndexPort {
       }
     },
     resolveRemoteUrl: rewriteUrl,
+    currentBranch: (target) => {
+      try {
+        const out = execFileSync('git', [
+          '-C',
+          root,
+          ...target.dirs.flatMap((dir) => ['-C', dir]),
+          ...(target.gitDir === undefined ? [] : ['--git-dir', target.gitDir]),
+          ...(target.workTree === undefined ? [] : ['--work-tree', target.workTree]),
+          'branch',
+          '--show-current',
+        ], {
+          encoding: 'utf8',
+          timeout: 10_000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        return out.replace(/\n+$/, '')
+      } catch {
+        return null
+      }
+    },
     configuredAlias: (verb) => {
       try {
         const out = execFileSync('git', ['-C', root, 'config', '--get', `alias.${verb}`], {

package/packages/agent-hooks/src/rules/registry.ts

@@ -29,11 +29,11 @@ import { gitStash, gitClean, gitRebase, gitFilterBranch, gitRestore, gitReset, g
 import { gitNoVerify, gitAmend } from './impl/git-verify.ts'
 import { gitProtectedTreeCommit } from './impl/git-protected-tree.ts'
 import {
-  gitBranchForceDelete,
   gitTagDelete,
   gitSwitchForce,
   gitGcPrune,
 } from './impl/git-history.ts'
+import { gitBranchMutation, gitCommitProtectedBranch } from './impl/git-branch.ts'
 import {
   gitUpdateRef,
   gitSymbolicRefWrite,
@@ -95,7 +95,8 @@ export const GIT_RULES: readonly AnyRuleSpec[] = [
   gitNoVerify,
   gitAmend,
   gitProtectedTreeCommit,
-  gitBranchForceDelete,
+  gitBranchMutation,
+  gitCommitProtectedBranch,
   gitTagDelete,
   gitSwitchForce,
   gitWorktree,

package/packages/agent-settings/assets/GLOBAL-AGENTS.md

@@ -6,6 +6,11 @@ repo's own `AGENTS.md`.
 ## Communication
 - Address me as **Tarun**.
 - Short, scannable **bullet points** — not long prose. Lead with the answer; keep reasoning tight.
+- **Every reply has three parts, in this order:**
+  - a **TL;DR** of a few lines; information stays brief, and detail is given only when asked;
+  - an explicit **Recommendation**: what you would do and why, in one line;
+  - **one ask**: the single question or decision you need next.
+- **Keep a numbered list of open points** and show it when it changes. I answer them one at a time, so never bundle several questions into one reply.
 - If a task is ambiguous, ask exactly one clarifying question.
 
 ## Truthfulness (non-negotiable)