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

package/bin/adl

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

package/bin/reconcile

@@ -186,6 +186,7 @@ collect_sweep_backups() {
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 repo_root="$(cd "$script_dir/.." && pwd)"
 manifest="${manifest:-$repo_root/packages/fleet/manifest.json}"
+manifest="$(cd "$(dirname "$manifest")" && pwd)/$(basename "$manifest")"
 # shellcheck source=lib/bun-compile-build.sh
 source "$script_dir/lib/bun-compile-build.sh"
 # shellcheck source=lib/adl-package.sh
@@ -3055,13 +3056,13 @@ fi
 if [[ "$global_agents_enabled" == true ]]; then
   if [[ "$mode" != apply ]]; then
     echo "global-tools: global agents mode=status home=$administrator_home"
-    "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode status
+    "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode status --host "$device" --manifest "$manifest"
   else
     echo "global-tools: global agents mode=deploy home=$administrator_home (as $administrator)"
     # The exact target files are authoritative global artifacts. Drift is
-    # replaced from GLOBAL-AGENTS.md with no backup or leave-in-place branch.
+    # replaced from TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md with no backup or leave-in-place branch.
     (cd /tmp && sudo -u "$administrator" -H env PATH="${brew_bin%/*}:/usr/bin:/bin" \
-      "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode deploy)
+      "$BASH" "$script_dir/global-agents" --home "$administrator_home" --mode deploy --host "$device" --manifest "$manifest")
   fi
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/adl-agent-control-linux-x64",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "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/README.md

@@ -474,6 +474,17 @@ rendered by `src/deploy/opencode-template.ts` from `assets/opencode-plugin.templ
 `assets/hooks.json` and the OpenCode surface in `deploy-profile.json`. Do not edit
 the deployed file by hand; re-run `adl install`.
 
+- The deployed file uses OpenCode v2's plugin shape (`export default { id, setup }`,
+  with `setup(ctx)` imperatively registering hooks via `ctx.session.hook` /
+  `ctx.tool.hook` / `ctx.event.subscribe` — confirmed against
+  `github.com/anomalyco/opencode/blob/dev/packages/core/src/plugin/module.ts`
+  and the promise adapter at
+  `github.com/anomalyco/opencode/blob/dev/packages/plugin/src/promise/adapter.ts`).
+  v2 dropped v1's `chat.message` + `experimental.chat.system.transform` events; the
+  template maps the equivalent flow to `ctx.session.hook("prompt", ...)` (run
+  `user-prompt-submit` per submission, stash the additionalContext) and
+  `ctx.session.hook("context", ...)` (push stashed context into `event.system`
+  immediately before provider dispatch).
 - The deployed file has no multi-line comments (Tarun 2026-10-08, Bug 602), so it
   passes compliance control REP-007. Its header is a single line pointing here.
 - Fallback projection: an event with no documented OpenCode equivalent runs on a
@@ -481,5 +492,8 @@ the deployed file by hand; re-run `adl install`.
   `packages/agent-hooks/deploy-profile.json` (today `SessionEnd -> SessionIdle`).
   The generated file lists the map as one line, `// Event fallbacks: A -> B, C -> D`,
   and emits no line at all when the map is empty.
+- `UserPromptSubmit` is intentionally not routed to any opencode slot — the v2
+  public plugin model has no replacement for v1's `chat.message` event; the rule
+  still runs for claude/codex/cursor/kimi through their own carriers.
 - Source of truth for hook commands is `assets/hooks.json`; the generated arrays
   carry `command`, `matcher`, `timeoutMs` and `fallbackFor` per entry.

package/packages/agent-hooks/assets/opencode-plugin.template.ts

@@ -2,6 +2,8 @@
 
 __ADL_FALLBACK_ENTRIES__
 
+// OpenCode v2 plugin: `export default { id, setup }`; setup(ctx) imperatively registers hooks via ctx.session.hook / ctx.tool.hook / ctx.event.subscribe.
+
 interface HookCommandSpec {
   command: string;
   matcher?: string;
@@ -27,10 +29,6 @@ const HOOKS_TOOL_EXECUTE_AFTER: HookCommandSpec[] = [
 __ADL_ARRAY_HOOKS_TOOL_EXECUTE_AFTER__
 ];
 
-const HOOKS_CHAT_MESSAGE: HookCommandSpec[] = [
-__ADL_ARRAY_HOOKS_CHAT_MESSAGE__
-];
-
 const HOOKS_EVENT_SESSION_CREATED: HookCommandSpec[] = [
 __ADL_ARRAY_HOOKS_EVENT_SESSION_CREATED__
 ];
@@ -47,30 +45,41 @@ async function runHookCommand(
   payload: Record<string, unknown>,
   cwd: string,
 ): Promise<{ exitCode: number | null; stdout: string; stderr: string }> {
-  try {
-    const proc = Bun.spawn(["/bin/sh", "-c", spec.command], {
-      cwd,
-      stdin: "pipe",
-      stdout: "pipe",
-      stderr: "pipe",
-      ...(spec.timeoutMs ? { timeout: spec.timeoutMs, killSignal: "SIGTERM" } : {}),
-    });
-    proc.stdin.write(JSON.stringify(payload));
-    proc.stdin.end();
-    const [stdout, stderr] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    await proc.exited;
-    if (proc.exitCode !== 0 && proc.exitCode !== 2) {
-      console.error("[" + PLUGIN_NAME + "] hook command exited " + proc.exitCode + ": " + spec.command);
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve) => {
+    try {
+      const proc = spawn("/bin/sh", ["-c", spec.command], {
+        cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      let stdout = "";
+      let stderr = "";
+      proc.stdout!.on("data", (chunk: Buffer) => { stdout += chunk.toString("utf8"); });
+      proc.stderr!.on("data", (chunk: Buffer) => { stderr += chunk.toString("utf8"); });
+      const timer = spec.timeoutMs
+        ? setTimeout(() => { try { proc.kill("SIGTERM"); } catch {} }, spec.timeoutMs)
+        : null;
+      proc.on("error", (err) => {
+        if (timer) clearTimeout(timer);
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("[" + PLUGIN_NAME + "] hook command crashed: " + spec.command + " -- " + message);
+        resolve({ exitCode: null, stdout: "", stderr: message });
+      });
+      proc.on("exit", (code) => {
+        if (timer) clearTimeout(timer);
+        if (code !== 0 && code !== 2) {
+          console.error("[" + PLUGIN_NAME + "] hook command exited " + code + ": " + spec.command);
+        }
+        resolve({ exitCode: code, stdout, stderr });
+      });
+      proc.stdin!.write(JSON.stringify(payload));
+      proc.stdin!.end();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[" + PLUGIN_NAME + "] hook command crashed: " + spec.command + " -- " + message);
+      resolve({ exitCode: null, stdout: "", stderr: message });
     }
-    return { exitCode: proc.exitCode, stdout, stderr };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error("[" + PLUGIN_NAME + "] hook command crashed: " + spec.command + " -- " + message);
-    return { exitCode: null, stdout: "", stderr: message };
-  }
+  });
 }
 
 function denyReason(result: { exitCode: number | null; stdout: string; stderr: string }): string | undefined {
@@ -113,9 +122,7 @@ function applyUpdatedInput(
   }
 }
 
-const adlPromptContext = new Map<string, string>();
-
-function extractHookContext(result: { exitCode: number | null; stdout: string; stderr: string }): string | undefined {
+function extractHookContext(result: { stdout: string }): string | undefined {
   const trimmed = result.stdout.trim();
   if (!trimmed) return undefined;
   try {
@@ -130,91 +137,120 @@ function extractHookContext(result: { exitCode: number | null; stdout: string; s
   return trimmed;
 }
 
-export const __ADL_PLUGIN_IDENTIFIER__ = async ({ directory }: { directory: string }) => {
-  return {
-  "chat.message": async (input: any, output: any) => {
-    const parts = output && Array.isArray(output.parts) ? output.parts : [];
-    const promptText = parts.filter((p: any) => p && p.type === "text").map((p: any) => p.text).join(" ");
-    let context: string | undefined;
-    for (const spec of HOOKS_CHAT_MESSAGE) {
+export default {
+  id: "__ADL_PLUGIN_NAME__",
+  setup: async (ctx: any) => {
+    const cwd = ctx.location?.directory ?? process.cwd();
+    const adlPromptContext = new Map<string, string[]>();
+
+    // Per-prompt: run user-prompt-submit, stash additionalContext keyed by sessionID.
+    await ctx.session.hook("prompt", async (event: any) => {
+      const sessionID: string | undefined = event?.sessionID;
+      if (!sessionID) return;
+      const promptText: string = event?.prompt?.text ?? "";
+      const out: string[] = [];
       const payload = {
         hook_event_name: "UserPromptSubmit",
         prompt: promptText,
-        cwd: directory,
-        session_id: input && input.sessionID,
+        cwd,
+        session_id: sessionID,
       };
-      const result = await runHookCommand(spec, payload, directory);
+      const result = await runHookCommand(
+        { command: "adl hook user-prompt-submit --host=opencode", timeoutMs: 15000 },
+        payload,
+        cwd,
+      );
       const extracted = extractHookContext(result);
-      if (extracted) context = context ? context + " " + extracted : extracted;
-    }
-    const sessionID = input && input.sessionID;
-    if (sessionID) {
-      if (context) adlPromptContext.set(sessionID, context);
+      if (extracted) out.push(extracted);
+      if (out.length) adlPromptContext.set(sessionID, out);
       else adlPromptContext.delete(sessionID);
-    }
-  },
-  "experimental.chat.system.transform": async (input: any, output: any) => {
-    const sessionID = input && input.sessionID;
-    if (!sessionID) return;
-    const context = adlPromptContext.get(sessionID);
-    if (context && output && Array.isArray(output.system)) {
-      output.system.push(context);
-    }
-  },
-  "tool.execute.before": async (input: ToolHookInput, output: ToolHookOutput) => {
-    for (const spec of HOOKS_TOOL_EXECUTE_BEFORE) {
-      if (spec.matcher && !new RegExp("^(?:" + spec.matcher + ")$", "i").test(input.tool)) continue;
-      const payload = {
-        hook_event_name: "PreToolUse",
-        tool_name: input.tool,
-        tool_input: output.args,
-        cwd: directory,
-        session_id: input.sessionID,
-      };
-      const result = await runHookCommand(spec, payload, directory);
-      const reason = denyReason(result);
-      if (reason) throw new Error(reason);
-      applyUpdatedInput(result, output);
-    }
-  },
-  "tool.execute.after": async (input: ToolHookInput, output: ToolHookOutput) => {
-    for (const spec of HOOKS_TOOL_EXECUTE_AFTER) {
-      if (spec.matcher && !new RegExp("^(?:" + spec.matcher + ")$", "i").test(input.tool)) continue;
-      const payload = {
-        hook_event_name: "PostToolUse",
-        tool_name: input.tool,
-        tool_input: output.args,
-        cwd: directory,
-        session_id: input.sessionID,
-      };
-      const result = await runHookCommand(spec, payload, directory);
-      // PostToolUse cannot block: the tool call already completed.
-    }
-  },
-  event: async ({ event }: { event: any }) => {
-    if (event && event.type === "session.created") {
-      for (const spec of HOOKS_EVENT_SESSION_CREATED) {
+    });
+
+    // Before provider dispatch: push stashed context into the system prompt array.
+    await ctx.session.hook("context", (event: any) => {
+      const sessionID: string | undefined = event?.sessionID;
+      if (!sessionID) return;
+      const out = adlPromptContext.get(sessionID);
+      if (!out || out.length === 0) return;
+      if (!Array.isArray(event.system)) return;
+      for (const text of out) {
+        event.system.push({ type: "text", text });
+      }
+    });
+
+    // Pre-tool-use: deny / rewrite. Always runs pre-tool-use; crg:pre-commit only on bash.
+    await ctx.tool.hook("execute.before", async (event: any) => {
+      const input = event as ToolHookInput;
+      const output = { args: (event?.input ?? {}) as Record<string, unknown> };
+      for (const spec of HOOKS_TOOL_EXECUTE_BEFORE) {
+        if (spec.matcher && !new RegExp("^(?:" + spec.matcher + ")$", "i").test(input.tool)) continue;
         const payload = {
-          hook_event_name: "SessionStart",
-          cwd: directory,
-          session_id: event.properties && (event.properties.sessionID || (event.properties.info && event.properties.info.id)),
+          hook_event_name: "PreToolUse",
+          tool_name: input.tool,
+          tool_input: output.args,
+          cwd,
+          session_id: input.sessionID,
         };
-        await runHookCommand(spec, payload, directory);
+        const result = await runHookCommand(spec, payload, cwd);
+        const reason = denyReason(result);
+        if (reason) throw new Error(reason);
+        applyUpdatedInput(result, output);
       }
-    }
-    if (event && event.type === "session.idle") {
-      for (const spec of HOOKS_EVENT_SESSION_IDLE) {
+      if (output.args !== event?.input && event && "input" in event) {
+        event.input = output.args;
+      }
+    });
+
+    // Post-tool-use: observational, can't block. Runs after-file-edit on write|edit.
+    await ctx.tool.hook("execute.after", async (event: any) => {
+      const input = event as ToolHookInput;
+      for (const spec of HOOKS_TOOL_EXECUTE_AFTER) {
+        if (spec.matcher && !new RegExp("^(?:" + spec.matcher + ")$", "i").test(input.tool)) continue;
         const payload = {
-          hook_event_name: "SessionIdle",
-          cwd: directory,
-          session_id: event.properties && (event.properties.sessionID || (event.properties.info && event.properties.info.id)),
-          ...(spec.fallbackFor ? { fallback_for: spec.fallbackFor } : {}),
+          hook_event_name: "PostToolUse",
+          tool_name: input.tool,
+          tool_input: (event?.input ?? {}),
+          cwd,
+          session_id: input.sessionID,
         };
-        await runHookCommand(spec, payload, directory);
+        await runHookCommand(spec, payload, cwd);
       }
+    });
+
+    // session.created / session.idle: subscribe to the event stream and dispatch.
+    if (ctx.event && typeof ctx.event.subscribe === "function") {
+      (async () => {
+        try {
+          for await (const event of ctx.event.subscribe()) {
+            const type = event?.type;
+            if (type === "session.created") {
+              const sessionID: string | undefined = event?.properties?.sessionID ?? event?.properties?.info?.id;
+              for (const spec of HOOKS_EVENT_SESSION_CREATED) {
+                const payload = {
+                  hook_event_name: "SessionStart",
+                  cwd,
+                  session_id: sessionID,
+                };
+                await runHookCommand(spec, payload, cwd);
+              }
+            } else if (type === "session.idle") {
+              const sessionID: string | undefined = event?.properties?.sessionID ?? event?.properties?.info?.id;
+              for (const spec of HOOKS_EVENT_SESSION_IDLE) {
+                const payload = {
+                  hook_event_name: "SessionIdle",
+                  cwd,
+                  session_id: sessionID,
+                  ...(spec.fallbackFor ? { fallback_for: spec.fallbackFor } : {}),
+                };
+                await runHookCommand(spec, payload, cwd);
+              }
+            }
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.error("[" + PLUGIN_NAME + "] event subscriber crashed: " + message);
+        }
+      })();
     }
   },
-  };
-};
-
-export default __ADL_PLUGIN_IDENTIFIER__;
+};

package/packages/agent-hooks/src/deploy/opencode-template.ts

@@ -1,11 +1,10 @@
 /**
  * Fills assets/opencode-plugin.template.ts with the rendered hook arrays
- * (render.ts's renderOpencodeSlots), the profile's pluginName, and the
- * identifier derived from it — reproducing this repo's own committed
- * `.opencode/plugins/adl-repo.ts` byte-for-byte for the current
- * deploy-profile.json + assets/hooks.json, except the header (a one-line
- * comment plus an optional one-line fallback comment; no multi-line comments in
- * deployed code, Bug 602). See README "Generated OpenCode plugin".
+ * (render.ts's renderOpencodeSlots) and the profile's pluginName — reproducing
+ * this repo's own committed `.opencode/plugins/adl-repo.ts` byte-for-byte for
+ * the current deploy-profile.json + assets/hooks.json, except the header
+ * (a one-line comment plus an optional one-line fallback comment; no multi-line
+ * comments in deployed code, Bug 602). See README "Generated OpenCode plugin".
  */
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -13,14 +12,6 @@ import type { HookSurface } from './profile.ts'
 import { OPENCODE_SLOTS, type RenderedOpencodeEntry, renderOpencodeSlots } from './render.ts'
 import type { CanonicalHooksDoc } from './source.ts'
 
-/** kebab-case -> camelCase, e.g. "adl-repo" -> "adlRepo". Ported from the deleted generator's toIdentifier (git show 5b34d10:packages/agent-skills/src/create/opencode.ts). */
-function toCamelCase(pluginName: string): string {
-  return pluginName
-    .split('-')
-    .map((part, index) => (index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
-    .join('')
-}
-
 function serializeEntry(entry: RenderedOpencodeEntry): string {
   const fields: string[] = [`command: ${JSON.stringify(entry.command)}`]
   if (entry.matcher !== undefined) fields.push(`matcher: ${JSON.stringify(entry.matcher)}`)
@@ -68,9 +59,5 @@ export function renderOpencodePlugin(options: RenderOpencodePluginOptions): stri
   if (!out.includes('__ADL_PLUGIN_NAME__')) throw new Error(`opencode plugin template is missing marker __ADL_PLUGIN_NAME__: ${templatePath}`)
   out = out.split('__ADL_PLUGIN_NAME__').join(surface.pluginName)
 
-  const identifier = `${toCamelCase(surface.pluginName)}Plugin`
-  if (!out.includes('__ADL_PLUGIN_IDENTIFIER__')) throw new Error(`opencode plugin template is missing marker __ADL_PLUGIN_IDENTIFIER__: ${templatePath}`)
-  out = out.split('__ADL_PLUGIN_IDENTIFIER__').join(identifier)
-
   return out
 }

package/packages/agent-hooks/src/deploy/render.ts

@@ -119,24 +119,33 @@ export interface RenderedOpencodeEntry {
 const OPENCODE_SLOT_FOR_EVENT: Readonly<Record<string, string>> = {
   PreToolUse: 'HOOKS_TOOL_EXECUTE_BEFORE',
   PostToolUse: 'HOOKS_TOOL_EXECUTE_AFTER',
-  UserPromptSubmit: 'HOOKS_CHAT_MESSAGE',
   SessionStart: 'HOOKS_EVENT_SESSION_CREATED',
   SessionEnd: 'HOOKS_EVENT_SESSION_IDLE',
 }
 
+/**
+ * Canonical events intentionally NOT routed to any opencode plugin slot.
+ * v2's public plugin model dropped the v1 `chat.message` +
+ * `experimental.chat.system.transform` pair that carried UserPromptSubmit,
+ * so the rule still runs for claude/codex/cursor/kimi through their own
+ * carriers but is invisible to the opencode surface. Add a new entry here
+ * only with the same justification.
+ */
+const OPENCODE_UNSUPPORTED_CANONICAL_EVENTS: ReadonlySet<string> = new Set(['UserPromptSubmit'])
+
 export const OPENCODE_SLOTS: readonly string[] = [
   'HOOKS_TOOL_EXECUTE_BEFORE',
   'HOOKS_TOOL_EXECUTE_AFTER',
-  'HOOKS_CHAT_MESSAGE',
   'HOOKS_EVENT_SESSION_CREATED',
   'HOOKS_EVENT_SESSION_IDLE',
 ]
 
-/** slot name -> rendered entries, in source order. Every event in `doc` must have a known slot (see OPENCODE_SLOT_FOR_EVENT). */
+/** slot name -> rendered entries, in source order. Every event in `doc` must have a known slot or be in OPENCODE_UNSUPPORTED_CANONICAL_EVENTS. */
 export function renderOpencodeSlots(doc: CanonicalHooksDoc, surface: HookSurface): ReadonlyMap<string, readonly RenderedOpencodeEntry[]> {
   const out = new Map<string, RenderedOpencodeEntry[]>()
   for (const slot of OPENCODE_SLOTS) out.set(slot, [])
   for (const [event, groups] of doc) {
+    if (OPENCODE_UNSUPPORTED_CANONICAL_EVENTS.has(event)) continue
     const slot = OPENCODE_SLOT_FOR_EVENT[event]
     if (slot === undefined) throw new Error(`opencode-plugin has no template slot for canonical event "${event}"`)
     // `fallbackFor` names the CANONICAL event being substituted (e.g.

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 {