@dalzoubi/dev-agents-sync 2.2.1 → 2.2.3

package/README.md

@@ -116,7 +116,7 @@ The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions
 | Script | Event | Matcher | Mode | What it does |
 |---|---|---|---|---|
 | `steering-injector.sh` | `SessionStart` | `.*` | warning | Surfaces steering context at the start of a session. |
-| `managed-file-guard.sh` | `PostToolUse` | `.*` | warning | Guards managed files against unexpected edits. |
+| `managed-file-guard.sh` | `PostToolUse` | `Edit\|Write` | warning | Guards managed files against unexpected edits. |
 | `uncommitted-check.sh` | `Stop` | `.*` | warning | Flags uncommitted work when a session ends. |
 | `force-push-guard.sh` | `PreToolUse` | `Bash` | **blocking** | Denies `git push` carrying `--force` / `-f` / `--force-with-lease` at `main` or `master` (by explicit refspec, or by the checked-out branch when the push names no ref). Force-pushing a feature branch, and a plain push to `main`, both pass. |
 | `spec-approval-gate.sh` | `PreToolUse` | `Edit\|Write` | **blocking** | Denies an edit that sets a spec to `Status: Approved` while an unresolved clarification marker — a bare bracketed `NEEDS CLARIFICATION` token — remains in prose. Occurrences inside code spans or fenced blocks are documentation and never match. |
@@ -162,7 +162,20 @@ By default, `init` and `update` also register each installed hook in `.claude/se
 - **Additive** — every existing setting and every consumer-authored hook is preserved untouched.
 - **Idempotent** — running `update` twice produces no duplicate entries.
 - **Tagged** — each injected entry is marked as CLI-managed so it can be identified and removed later without disturbing consumer-authored hooks.
-- **Self-cleaning** — when the toolkit retires a hook, `update` also prunes the CLI-managed registration for it, so no consumer is left with an entry pointing at a script that no longer ships. Only tagged entries are pruned, and only the retired command within them: a consumer-authored entry for the same command is left untouched, and a command you added yourself inside a tagged entry survives alongside. The prune is reported on stderr (`info: dev-agents-sync: pruned N retired hook registration(s)`, counting registrations removed) and is computed — and surfaced in the `--dry-run` result — without writing anything. `rules-injector.sh` is the first retired hook — Claude Code now loads `.claude/rules/*.md` natively, so the hook is redundant.
+- **Self-cleaning** — when the toolkit retires a hook, `update` also prunes the CLI-managed registration for it, so no consumer is left with an entry pointing at a script that no longer ships. Only tagged entries are pruned, and only the retired command within them: a consumer-authored entry for the same command is left untouched, and a command you added yourself inside a tagged entry survives alongside. The prune is reported on stderr (`info: dev-agents-sync: pruned N retired hook registration(s)`, counting registrations removed) and is computed — and surfaced in the `--dry-run` result — without writing anything. `rules-injector.sh` is the first retired hook — Claude Code now loads `.claude/rules/*.md` natively, so the hook is redundant. What retires is a *command string*, so this also covers a hook whose script still ships under a changed command form (see below).
+
+Each registration invokes its script through an explicit interpreter:
+
+```json
+{
+  "matcher": "Edit|Write",
+  "hooks": [{ "type": "command", "command": "bash .claude/hooks/managed-file-guard.sh" }]
+}
+```
+
+Naming `bash` is what keeps this working on Windows. A bare `.claude/hooks/<name>.sh` command has no executable interpreter there, so the shell falls through to the `.sh` file association — which Git for Windows registers as `bash.exe --login -i "%1"`. That is an *interactive* login shell, and Windows gives it a visible console window, so a window popped up for every matched tool call. `bash` is the interpreter Claude Code already shells out to on Windows, and the hook scripts are POSIX-sh, so the same command form is correct on macOS and Linux.
+
+> **One-time re-registration.** Hooks shipped with the bare-path command form up to and including CLI **v2.2.1**. The first `update` on a newer CLI de-registers those stale entries and adds the `bash …` form, so you will see a `pruned N retired hook registration(s)` line once, alongside the usual wiring line. Nothing is duplicated and the run converges: a second `update` leaves `settings.json` byte-identical. Untagged entries you wrote yourself are never touched — if you hand-registered a hook with a bare path, it stays as-is and is yours to update.
 
 > **Carve-out.** `settings.json` is a consumer-owned configuration file, **not** a marker-managed file. The CLI never replaces it wholesale; it only merges in its own tagged hook registrations and otherwise leaves the file alone. If `settings.json` contains malformed JSON, `update` fails loud with the stable code `ESETTINGS_PARSE` and leaves the file byte-identical — it will never half-write or clobber an unparseable file.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/commands/update.mjs

@@ -152,8 +152,10 @@ export async function runUpdate(consumerCwd, opts = {}) {
     // idempotent, so running twice == once. --dry-run still writes nothing.
     let prunedRetired = [];
     if (claudeTargetActive && !noHooksWiring) {
+      // Existence is checked against `h.script` (the path on disk), not
+      // `h.command` (the `bash <path>` shell string this hook is registered as).
       const hookSpec = DEFAULT_HOOK_SCRIPTS.filter((h) =>
-        existsSync(path.join(consumerCwd, h.command)),
+        existsSync(path.join(consumerCwd, h.script)),
       );
       // Unconditional on hookSpec.length: the prune needs no spec, so a consumer
       // with no hook scripts on disk still gets retired registrations removed.

package/src/hooks.mjs

@@ -47,10 +47,14 @@ export function collectHookPaths(relKeys) {
  * Returns the settings.json hook registration spec restricted to the hook
  * scripts that were actually installed (present in `relKeys`). Each registration
  * is taken from DEFAULT_HOOK_SCRIPTS so the event/matcher stay authoritative.
+ *
+ * Matched on `h.script` — the path — because that is what `collectHookPaths`
+ * yields. `h.command` is a shell command string (`bash .claude/hooks/foo.sh`)
+ * and never equals a FileMap-derived path.
  */
 export function hookScriptsForInstalled(relKeys) {
   const installed = new Set(collectHookPaths(relKeys));
-  return DEFAULT_HOOK_SCRIPTS.filter((h) => installed.has(h.command));
+  return DEFAULT_HOOK_SCRIPTS.filter((h) => installed.has(h.script));
 }
 
 /**

package/src/settings.mjs

@@ -391,10 +391,42 @@ export function removeHookSettings(consumerCwd, opts = {}) {
   return { removed: true, dryRun: false, settingsPath: absPath };
 }
 
+/**
+ * The settings.json command string that runs a hook script at `script`.
+ *
+ * The interpreter prefix is load-bearing on Windows and is why `script` and
+ * `command` are separate fields at all. A bare `.claude/hooks/foo.sh` command
+ * has no executable interpreter on Windows, so the shell falls through to the
+ * `.sh` FILE ASSOCIATION, which Git for Windows registers as
+ * `bash.exe --login -i "%1"` — an INTERACTIVE login shell, which Windows gives
+ * a visible console window. The result was a terminal window popping up for
+ * every matched tool call. Naming `bash` explicitly means the association is
+ * never consulted, on any platform.
+ *
+ * `bash` rather than `sh`: it is the interpreter Claude Code itself shells out
+ * to on Windows (Git Bash), so it is on PATH exactly where the association
+ * fallback would otherwise fire. The hook scripts are POSIX-sh and run fine
+ * under it.
+ */
+export function hookCommandFor(script) {
+  return `bash ${script}`;
+}
+
 /**
  * The default hook registration spec — maps each installed hook script to its
  * Claude Code event. Kept here so init/update share one source of truth.
  *
+ * Each entry carries both halves of that mapping, deliberately separated:
+ *   - `script` — the consumer-relative PATH on disk (`.claude/hooks/foo.sh`).
+ *     This is the filesystem identity: what `init`/`update` install, what the
+ *     lockfile tracks, and what an existence check joins against a repo root.
+ *   - `command` — the settings.json COMMAND STRING that invokes it, derived
+ *     from `script` by `hookCommandFor`. This is the settings identity: what
+ *     the merge dedupes on and what retirement matches.
+ * They were one field until the command grew an interpreter prefix; collapsing
+ * them again would either resurrect the Windows console-window bug or make the
+ * CLI join a shell command onto a path.
+ *
  * The matcher is the tool-name filter Claude Code applies before running the
  * hook. Session-scoped events (`SessionStart`, `Stop`) take `.*`; tool-scoped
  * events name the tools they inspect, so a hook that only ever reads a Bash
@@ -405,18 +437,21 @@ export function removeHookSettings(consumerCwd, opts = {}) {
  * independent registrations keyed by command.
  */
 export const DEFAULT_HOOK_SCRIPTS = [
-  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-  { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
-  { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+  { event: 'SessionStart', matcher: '.*', script: '.claude/hooks/steering-injector.sh' },
+  // Edit|Write, not `.*`: this hook reads a written file path out of the hook
+  // payload and exits 0 silently when there is none, so on `.*` it was spawned
+  // by every tool call — every Read, every Bash — to do nothing.
+  { event: 'PostToolUse', matcher: 'Edit|Write', script: '.claude/hooks/managed-file-guard.sh' },
+  { event: 'Stop', matcher: '.*', script: '.claude/hooks/uncommitted-check.sh' },
   // Added by docs/specs/260805-hooks-wave-2/ — the toolkit's first blocking
   // hooks plus two warning hooks. Blockers deny only on a positive violation
   // match, fail open otherwise, and honor DEV_AGENTS_HOOKS_BYPASS.
-  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/force-push-guard.sh' },
-  { event: 'PreToolUse', matcher: 'Edit|Write', command: '.claude/hooks/spec-approval-gate.sh' },
-  { event: 'PreToolUse', matcher: 'Write', command: '.claude/hooks/handoff-state-guard.sh' },
-  { event: 'PostToolUse', matcher: 'Edit|Write', command: '.claude/hooks/spec-drift-warn.sh' },
-  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/pre-pr-preflight.sh' },
-];
+  { event: 'PreToolUse', matcher: 'Bash', script: '.claude/hooks/force-push-guard.sh' },
+  { event: 'PreToolUse', matcher: 'Edit|Write', script: '.claude/hooks/spec-approval-gate.sh' },
+  { event: 'PreToolUse', matcher: 'Write', script: '.claude/hooks/handoff-state-guard.sh' },
+  { event: 'PostToolUse', matcher: 'Edit|Write', script: '.claude/hooks/spec-drift-warn.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', script: '.claude/hooks/pre-pr-preflight.sh' },
+].map((h) => ({ ...h, command: hookCommandFor(h.script) }));
 
 /**
  * Hook registrations the toolkit once shipped and has since retired.
@@ -434,10 +469,35 @@ export const DEFAULT_HOOK_SCRIPTS = [
  * an older CLI reading newer content simply does not prune rather than erroring.
  * Reversing a retirement is done by moving the entry back to
  * DEFAULT_HOOK_SCRIPTS, not by silently dropping it from here.
+ *
+ * What retires is a COMMAND STRING, not necessarily a script. A hook whose
+ * script still ships but whose command form changed retires the old form here
+ * and registers the new one in DEFAULT_HOOK_SCRIPTS; merge-then-prune runs the
+ * additive pass first, so the consumer ends a single `update` with exactly one
+ * registration — the new one. Without the retirement the two forms would both
+ * be live and the hook would run twice per matched call.
+ *
+ * `event`/`matcher` are recorded for the reader; the prune matches on `command`
+ * alone and scans every event bucket, so a stale registration is removed
+ * wherever a past CLI (or a hand-edit) put it.
  */
 export const RETIRED_HOOK_SCRIPTS = [
   // Retired by docs/specs/260724-opus5-native-overlap/ (S1): Claude Code loads
   // `.claude/rules/*.md` natively as project instructions, which is strictly
   // broader than this hook's fixed injection list.
   { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/rules-injector.sh' },
+  // The bare-path command form every hook shipped with before `hookCommandFor`
+  // added the `bash` prefix. Every one of these scripts still ships; only the
+  // command form is retired, so each is registered above in its `bash …` form
+  // and the stale bare-path registration is pruned on the next `update`. This
+  // is what makes the Windows fix reach existing consumers: leaving the old
+  // registration in place would keep spawning the console window it fixes.
+  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+  { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
+  { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/force-push-guard.sh' },
+  { event: 'PreToolUse', matcher: 'Edit|Write', command: '.claude/hooks/spec-approval-gate.sh' },
+  { event: 'PreToolUse', matcher: 'Write', command: '.claude/hooks/handoff-state-guard.sh' },
+  { event: 'PostToolUse', matcher: 'Edit|Write', command: '.claude/hooks/spec-drift-warn.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/pre-pr-preflight.sh' },
 ];

package/tests/e2e/steering-hooks-flow.test.mjs

@@ -89,7 +89,7 @@ const STEERING_FILES = ['decisions.md', 'glossary.md', 'architecture.md'];
  * the 260805 wave added five hooks that a pinned list of three would not have
  * covered at all. Deriving keeps the flow honest for every future wave.
  */
-const HOOK_FILES = DEFAULT_HOOK_SCRIPTS.map((h) => path.basename(h.command));
+const HOOK_FILES = DEFAULT_HOOK_SCRIPTS.map((h) => path.basename(h.script));
 
 /**
  * Events paired with the hook script that handles each one. Used to assert
@@ -98,7 +98,7 @@ const HOOK_FILES = DEFAULT_HOOK_SCRIPTS.map((h) => path.basename(h.command));
  */
 const HOOK_EVENT_PAIRS = DEFAULT_HOOK_SCRIPTS.map((h) => ({
   event: h.event,
-  script: path.basename(h.command),
+  script: path.basename(h.script),
 }));
 
 const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
@@ -139,10 +139,10 @@ function buildFixtureFileMap(targets = ['claude']) {
   // registration. They carry the shell-comment marker (POSIX-sh, not HTML).
   // Bodies are stand-ins: this flow proves install + wiring + drift, never a
   // hook's own behavior (that lives in the content repo's tests/hooks-*.mjs).
-  for (const { event, command } of DEFAULT_HOOK_SCRIPTS) {
-    const key = command.replace(/^\.claude\//, 'claude/');
+  for (const { event, script } of DEFAULT_HOOK_SCRIPTS) {
+    const key = script.replace(/^\.claude\//, 'claude/');
     map[key] =
-      `#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# ${event}: fixture stand-in for ${path.basename(command)}.\nexit 0\n`;
+      `#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# ${event}: fixture stand-in for ${path.basename(script)}.\nexit 0\n`;
   }
 
   return map;

package/tests/hook-retirement.test.mjs

@@ -94,6 +94,20 @@ async function importSettings() {
 
 const RETIRED_COMMAND = '.claude/hooks/rules-injector.sh';
 
+/**
+ * Command strings for the three hooks that SURVIVE the rules-injector prune.
+ *
+ * The `bash ` prefix is the current registration form (see `hookCommandFor`).
+ * It matters here because the bare-path form these same scripts once shipped
+ * with is itself on RETIRED_HOOK_SCRIPTS: seeding a survivor in the old form
+ * would make the prune legitimately remove it, and these tests would then be
+ * asserting the wrong thing about a mechanism that works. A survivor must be
+ * spelled the way the CLI registers it today.
+ */
+const SURVIVOR_STEERING = 'bash .claude/hooks/steering-injector.sh';
+const SURVIVOR_GUARD = 'bash .claude/hooks/managed-file-guard.sh';
+const SURVIVOR_UNCOMMITTED = 'bash .claude/hooks/uncommitted-check.sh';
+
 /**
  * The intended POST-S1 caller-supplied hookScripts list — i.e. what a fixed
  * DEFAULT_HOOK_SCRIPTS should look like once rules-injector.sh is removed
@@ -103,9 +117,9 @@ const RETIRED_COMMAND = '.claude/hooks/rules-injector.sh';
  * edit to DEFAULT_HOOK_SCRIPTS itself.
  */
 const FUTURE_HOOK_SCRIPTS = [
-  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-  { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
-  { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+  { event: 'SessionStart', matcher: '.*', command: SURVIVOR_STEERING },
+  { event: 'PostToolUse', matcher: 'Edit|Write', command: SURVIVOR_GUARD },
+  { event: 'Stop', matcher: '.*', command: SURVIVOR_UNCOMMITTED },
 ];
 
 function makeTmpDir() {
@@ -313,9 +327,9 @@ describe('S1 P3 — no retired entry present means no change', () => {
     // add, and the prune pass has nothing to remove.
     writeSettings(consumerDir, {
       hooks: {
-        SessionStart: [taggedEntry('.*', '.claude/hooks/steering-injector.sh')],
-        PostToolUse: [taggedEntry('.*', '.claude/hooks/managed-file-guard.sh')],
-        Stop: [taggedEntry('.*', '.claude/hooks/uncommitted-check.sh')],
+        SessionStart: [taggedEntry('.*', SURVIVOR_STEERING)],
+        PostToolUse: [taggedEntry('Edit|Write', SURVIVOR_GUARD)],
+        Stop: [taggedEntry('.*', SURVIVOR_UNCOMMITTED)],
       },
     });
     const before = readSettingsRaw(consumerDir);
@@ -508,7 +522,7 @@ describe('S1 H1 — prune is hook-granular, not entry-granular (a consumer comma
     const steeringRegistered = sessionStart.some(
       (e) =>
         Array.isArray(e.hooks) &&
-        e.hooks.some((h) => h.command === '.claude/hooks/steering-injector.sh'),
+        e.hooks.some((h) => h.command === SURVIVOR_STEERING),
     );
     assert.ok(
       steeringRegistered,
@@ -525,7 +539,7 @@ describe('S1 H1 — prune is hook-granular, not entry-granular (a consumer comma
     // surviving managed hook vanishes with nothing left to re-register it —
     // an un-registration deliver-validate flagged as a real regression risk,
     // not just a data-loss risk.
-    const SURVIVING_COMMAND = '.claude/hooks/steering-injector.sh';
+    const SURVIVING_COMMAND = SURVIVOR_STEERING;
     const mixedEntry = {
       [HOOK_TAG]: true,
       matcher: '.*',
@@ -644,9 +658,9 @@ describe('S1 P6 — the other three managed hooks survive the prune unchanged',
   });
 
   it('P6: steering-injector.sh, managed-file-guard.sh, and uncommitted-check.sh entries are byte-identical after the prune', async () => {
-    const steering = taggedEntry('.*', '.claude/hooks/steering-injector.sh');
-    const guard = taggedEntry('.*', '.claude/hooks/managed-file-guard.sh');
-    const uncommitted = taggedEntry('.*', '.claude/hooks/uncommitted-check.sh');
+    const steering = taggedEntry('.*', SURVIVOR_STEERING);
+    const guard = taggedEntry('Edit|Write', SURVIVOR_GUARD);
+    const uncommitted = taggedEntry('.*', SURVIVOR_UNCOMMITTED);
     const retired = taggedEntry('.*', RETIRED_COMMAND);
 
     writeSettings(consumerDir, {

package/tests/hooks-cli-install.test.mjs

@@ -39,9 +39,9 @@
  *     - hookScripts: { event: string, matcher: string, command: string }[]
  *         Each element describes one hook to wire in settings.json.
  *         Example: [
- *           { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
- *           { event: 'PostToolUse',  matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
- *           { event: 'Stop',         matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+ *           { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
+ *           { event: 'PostToolUse',  matcher: '.*', command: 'bash .claude/hooks/managed-file-guard.sh' },
+ *           { event: 'Stop',         matcher: '.*', command: 'bash .claude/hooks/uncommitted-check.sh' },
  *         ]
  *     - opts.dryRun: boolean — when true, computes plan but writes nothing
  *     Returns: { merged: boolean, dryRun: boolean } (or equivalent plan object in dry-run)
@@ -665,9 +665,9 @@ describe('S4 H6 — settings merge is additive and idempotent', () => {
     await mergeHookSettings(
       consumerDir,
       [
-        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-        { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
-        { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+        { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
+        { event: 'PostToolUse', matcher: '.*', command: 'bash .claude/hooks/managed-file-guard.sh' },
+        { event: 'Stop', matcher: '.*', command: 'bash .claude/hooks/uncommitted-check.sh' },
       ],
     );
 
@@ -726,9 +726,9 @@ describe('S4 H6 — settings merge is additive and idempotent', () => {
     await mergeHookSettings(
       consumerDir,
       [
-        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-        { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
-        { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+        { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
+        { event: 'PostToolUse', matcher: '.*', command: 'bash .claude/hooks/managed-file-guard.sh' },
+        { event: 'Stop', matcher: '.*', command: 'bash .claude/hooks/uncommitted-check.sh' },
       ],
     );
 
@@ -762,9 +762,9 @@ describe('S4 H6 — settings merge is additive and idempotent', () => {
     writeFileSync(settingsPath, JSON.stringify({}, null, 2), 'utf8');
 
     const hookSpec = [
-      { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-      { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
-      { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+      { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
+      { event: 'PostToolUse', matcher: '.*', command: 'bash .claude/hooks/managed-file-guard.sh' },
+      { event: 'Stop', matcher: '.*', command: 'bash .claude/hooks/uncommitted-check.sh' },
     ];
 
     await mergeHookSettings(consumerDir, hookSpec);
@@ -804,7 +804,7 @@ describe('S4 H6 — settings merge is additive and idempotent', () => {
     await mergeHookSettings(
       consumerDir,
       [
-        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+        { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
       ],
     );
 
@@ -837,7 +837,7 @@ describe('S4 H7 — injected hook entries are tagged (identifiable and removable
     writeFileSync(settingsPath, JSON.stringify({}, null, 2), 'utf8');
 
     await mergeHookSettings(consumerDir, [
-      { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+      { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
     ]);
 
     const raw = readFileSync(settingsPath, 'utf8');
@@ -875,7 +875,7 @@ describe('S4 H7 — injected hook entries are tagged (identifiable and removable
     );
 
     await mergeHookSettings(consumerDir, [
-      { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+      { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
     ]);
 
     const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
@@ -1174,7 +1174,7 @@ describe('S4 H10 — malformed settings.json triggers ESETTINGS_PARSE (no write)
     let thrownError = null;
     try {
       await mergeHookSettings(consumerDir, [
-        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+        { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
       ]);
     } catch (err) {
       thrownError = err;
@@ -1197,7 +1197,7 @@ describe('S4 H10 — malformed settings.json triggers ESETTINGS_PARSE (no write)
 
     try {
       await mergeHookSettings(consumerDir, [
-        { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+        { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
       ]);
     } catch {
       // expected
@@ -1377,7 +1377,7 @@ describe('S4 L5 — wrong-shape hooks field fails loud (ESETTINGS_PARSE, no writ
   });
 
   const HOOK_SPEC = [
-    { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
+    { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
   ];
 
   // Each case: a syntactically valid JSON object whose `hooks` sub-tree is the
@@ -1495,9 +1495,9 @@ describe('S4 L4 — consumer hook on a managed event survives merge then remove'
 
     // Merge the managed registrations (steering-injector is also SessionStart).
     await mergeHookSettings(consumerDir, [
-      { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-      { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
-      { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+      { event: 'SessionStart', matcher: '.*', command: 'bash .claude/hooks/steering-injector.sh' },
+      { event: 'PostToolUse', matcher: '.*', command: 'bash .claude/hooks/managed-file-guard.sh' },
+      { event: 'Stop', matcher: '.*', command: 'bash .claude/hooks/uncommitted-check.sh' },
     ]);
 
     // After merge: SessionStart has BOTH the consumer entry and the managed one.

package/tests/hooks-command-form.test.mjs

@@ -0,0 +1,435 @@
+/**
+ * tests/hooks-command-form.test.mjs
+ *
+ * The settings.json COMMAND FORM of a hook registration, and the migration off
+ * the form the toolkit shipped before it.
+ *
+ * Why this file exists: every hook was registered as a bare relative path
+ * (`.claude/hooks/managed-file-guard.sh`). On Linux/macOS the shebang makes
+ * that executable, so nothing in the suite noticed that Windows has no shebang
+ * handling — there, the bare `.sh` resolves through the `.sh` FILE ASSOCIATION,
+ * which Git for Windows registers as `bash.exe --login -i "%1"`. That `-i` is
+ * an interactive shell, so Windows gives it a visible console window: one
+ * window per matched tool call, for the life of the session. Naming the
+ * interpreter in the command keeps the association out of it.
+ *
+ * The regression is invisible on the platforms CI runs on, which is exactly why
+ * the contract is asserted on the table rather than on observed behavior.
+ *
+ * Behavior anchors:
+ *
+ *  C1. No registered command is a bare `.sh` path; each names an interpreter
+ *      and points at its `script`.
+ *  C2. `script` and `command` stay consistent: one row per shipped script, and
+ *      the command is derived from the path rather than typed twice.
+ *  C3. The pre-fix bare-path form of every shipped script is retired, so a
+ *      consumer's stale registration is de-registered rather than left live
+ *      alongside the new one.
+ *  C4. End to end: a consumer whose settings.json carries the old registrations
+ *      ends a single `update` with exactly one registration per hook, in the new
+ *      form. This is the anchor that would fail if C3 were dropped — the hook
+ *      would be registered twice and the console window would survive the fix.
+ *  C5. `managed-file-guard` is registered on `Edit|Write`, not `.*`. It reads a
+ *      written file path out of the payload and exits 0 when there is none, so
+ *      on `.*` every unrelated tool call spawned it to do nothing.
+ *
+ * Test runner: `node --test packages/dev-agents-sync/tests/hooks-command-form.test.mjs`
+ * i18n/accessibility: N/A — CLI-only, no UI surface and no translated strings.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runUpdate } from '../src/commands/update.mjs';
+import { DEFAULT_HOOK_SCRIPTS, RETIRED_HOOK_SCRIPTS, HOOK_TAG } from '../src/settings.mjs';
+
+// ---------------------------------------------------------------------------
+// Paths / fixtures
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+const LOCKFILE_NAME = '.dev-agents-sync.json';
+
+/**
+ * The expected command form, spelled out rather than imported from
+ * `hookCommandFor`. Importing the producer would assert it equals itself; the
+ * literal prefix IS the contract, since it is what keeps the Windows `.sh`
+ * association — and its interactive console window — out of the path.
+ */
+const INTERPRETER = 'bash';
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(baseDir, full, map, prefix);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[`${prefix}/${rel}`] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+/** A fetched FileMap carrying one hook script per registration. */
+function buildFixtureFileMap() {
+  const map = {};
+  const targetDir = path.join(FIXTURE_DIR, 'claude');
+  if (existsSync(targetDir)) collectFiles(targetDir, targetDir, map, 'claude');
+  for (const { event, script } of DEFAULT_HOOK_SCRIPTS) {
+    map[script.replace(/^\.claude\//, 'claude/')] =
+      `#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# ${event} hook fixture: ${path.basename(script)}.\nexit 0\n`;
+  }
+  return map;
+}
+
+function makeFixtureFetcher() {
+  return async () => buildFixtureFileMap();
+}
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-hook-command-form-'));
+}
+
+function settingsPathIn(consumerDir) {
+  return path.join(consumerDir, '.claude', 'settings.json');
+}
+
+/**
+ * Seeds a consumer synced by a PRE-FIX CLI: a lockfile plus a settings.json
+ * whose managed registrations all carry the bare-path command form, on the
+ * events and matchers that CLI used (`managed-file-guard` on `.*`).
+ */
+function setupPreFixRepo(consumerDir) {
+  const raw =
+    JSON.stringify(
+      {
+        $schema:
+          'https://raw.githubusercontent.com/dalzoubi/dev-agents/v1/schema/lockfile.schema.json',
+        source: 'github:dalzoubi/dev-agents',
+        range: '^1',
+        resolvedVersion: '1.0.0',
+        targets: ['claude'],
+        lastUpdated: '2026-08-05T00:00:00Z',
+        hooks: DEFAULT_HOOK_SCRIPTS.map((h) => h.script),
+      },
+      null,
+      2,
+    ) + '\n';
+  writeFileSync(path.join(consumerDir, LOCKFILE_NAME), raw, 'utf8');
+
+  const agentsDir = path.join(consumerDir, '.claude', 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  writeFileSync(
+    path.join(agentsDir, 'define.md'),
+    readFileSync(path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'), 'utf8'),
+    'utf8',
+  );
+
+  // The pre-fix wiring: bare-path commands, one tagged entry per hook, grouped
+  // into the event buckets the old table used.
+  const hooks = {};
+  for (const { event, matcher, script } of DEFAULT_HOOK_SCRIPTS) {
+    const oldMatcher = script.endsWith('managed-file-guard.sh') ? '.*' : matcher;
+    hooks[event] ??= [];
+    hooks[event].push({
+      [HOOK_TAG]: true,
+      matcher: oldMatcher,
+      hooks: [{ type: 'command', command: script }],
+    });
+  }
+  writeFileSync(
+    settingsPathIn(consumerDir),
+    JSON.stringify({ hooks }, null, 2) + '\n',
+    'utf8',
+  );
+}
+
+/** Every CLI-managed registration in settings.json, flattened. */
+function managedRegistrations(consumerDir) {
+  const settingsPath = settingsPathIn(consumerDir);
+  if (!existsSync(settingsPath)) return [];
+  const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  const out = [];
+  for (const [event, entries] of Object.entries(settings.hooks ?? {})) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry?.[HOOK_TAG] !== true) continue;
+      for (const h of entry.hooks ?? []) {
+        if (typeof h.command === 'string') {
+          out.push({ event, matcher: entry.matcher, command: h.command });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// C1 — no registered command is a bare .sh path
+// ---------------------------------------------------------------------------
+
+describe('C1 — every registered command names an interpreter', () => {
+  for (const { script, command } of DEFAULT_HOOK_SCRIPTS) {
+    it(`C1: ${path.basename(script)} is registered as "${INTERPRETER} <path>", not a bare .sh path`, () => {
+      assert.equal(
+        command,
+        `${INTERPRETER} ${script}`,
+        `A bare "${script}" command has no interpreter on Windows, so the shell falls ` +
+          `through to the .sh file association (Git for Windows: bash --login -i "%1") and ` +
+          `each matched tool call opens a console window. Register it as ` +
+          `"${INTERPRETER} ${script}".`,
+      );
+    });
+  }
+
+  it('C1: no command in the table ends in .sh (the shape that triggers the association)', () => {
+    const bare = DEFAULT_HOOK_SCRIPTS.map((h) => h.command)
+      .filter((c) => /\.sh$/.test(c) && !c.includes(' '))
+      .sort();
+    assert.deepEqual(
+      bare,
+      [],
+      `these commands are bare script paths and will resolve through the Windows .sh ` +
+        `file association: ${bare.join(', ')}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// C2 — script and command stay consistent
+// ---------------------------------------------------------------------------
+
+describe('C2 — script and command are consistent across the table', () => {
+  it('C2a: every row carries both a consumer-relative script path and a command', () => {
+    for (const row of DEFAULT_HOOK_SCRIPTS) {
+      assert.match(
+        row.script,
+        /^\.claude\/hooks\/[a-z0-9-]+\.sh$/,
+        `every row needs a consumer-relative script path; got: ${JSON.stringify(row)}`,
+      );
+      assert.ok(
+        typeof row.command === 'string' && row.command.length > 0,
+        `every row needs a command string; got: ${JSON.stringify(row)}`,
+      );
+    }
+  });
+
+  it('C2b: every command ends with the exact script path of its own row', () => {
+    // Guards the pairing itself: a copy/paste that leaves one row's command
+    // pointing at another row's script would register a hook that runs the
+    // wrong guard, on the wrong event, with nothing else noticing.
+    for (const { script, command } of DEFAULT_HOOK_SCRIPTS) {
+      assert.ok(
+        command.endsWith(` ${script}`),
+        `${command} must invoke its own row's script (${script})`,
+      );
+    }
+  });
+
+  it('C2c: each shipped script has exactly one row', () => {
+    const scripts = DEFAULT_HOOK_SCRIPTS.map((h) => h.script);
+    const duplicated = scripts.filter((s, i) => scripts.indexOf(s) !== i).sort();
+    assert.deepEqual(
+      duplicated,
+      [],
+      `a script registered twice runs twice per matched call: ${duplicated.join(', ')}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// C3 — the pre-fix command form is retired
+// ---------------------------------------------------------------------------
+
+describe('C3 — the bare-path form of every shipped hook is retired', () => {
+  it('C3a: RETIRED_HOOK_SCRIPTS names the bare-path command of every shipped script', () => {
+    // Without this, an existing consumer keeps their old registration AND gains
+    // the new one: the hook runs twice and the console window the fix removes
+    // comes straight back from the stale entry.
+    const retired = new Set(RETIRED_HOOK_SCRIPTS.map((h) => h.command));
+    const missing = DEFAULT_HOOK_SCRIPTS.map((h) => h.script)
+      .filter((s) => !retired.has(s))
+      .sort();
+    assert.deepEqual(
+      missing,
+      [],
+      `the pre-fix bare-path registration for these scripts is not retired, so it stays ` +
+        `live alongside the new one: ${missing.join(', ')}`,
+    );
+  });
+
+  it('C3b: no retired command is re-registered in the shipped table', () => {
+    // merge-then-prune would otherwise add and immediately remove it on every run.
+    const retired = new Set(RETIRED_HOOK_SCRIPTS.map((h) => h.command));
+    const reRegistered = DEFAULT_HOOK_SCRIPTS.map((h) => h.command)
+      .filter((c) => retired.has(c))
+      .sort();
+    assert.deepEqual(reRegistered, [], `re-registered retired commands: ${reRegistered.join(', ')}`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// C4 — an existing consumer migrates in one update
+// ---------------------------------------------------------------------------
+
+describe('C4 — a pre-fix consumer migrates to the new command form in one update', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('C4a: after one update, every hook is registered exactly once, in the new form', async () => {
+    setupPreFixRepo(consumerDir);
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const commands = managedRegistrations(consumerDir)
+      .map((w) => w.command)
+      .sort();
+    assert.deepEqual(
+      commands,
+      DEFAULT_HOOK_SCRIPTS.map((h) => h.command).sort(),
+      'one update must leave exactly the current registrations — no stale bare-path ' +
+        'entry surviving alongside its replacement',
+    );
+  });
+
+  it('C4b: no bare-path registration survives the update', async () => {
+    setupPreFixRepo(consumerDir);
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const stale = managedRegistrations(consumerDir)
+      .map((w) => w.command)
+      .filter((c) => DEFAULT_HOOK_SCRIPTS.some((h) => h.script === c))
+      .sort();
+    assert.deepEqual(
+      stale,
+      [],
+      `these pre-fix registrations survived and will keep opening a console window on ` +
+        `Windows: ${stale.join(', ')}`,
+    );
+  });
+
+  it('C4c: the migration is reported on stderr, not silent', async () => {
+    // De-registering entries in a consumer-owned file is a real edit (§6).
+    setupPreFixRepo(consumerDir);
+
+    const origWrite = process.stderr.write.bind(process.stderr);
+    let stderr = '';
+    process.stderr.write = (chunk) => {
+      stderr += typeof chunk === 'string' ? chunk : chunk.toString();
+      return true;
+    };
+    try {
+      await runUpdate(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } finally {
+      process.stderr.write = origWrite;
+    }
+
+    assert.match(
+      stderr,
+      /info: dev-agents-sync: pruned \d+ retired hook registration\(s\)/,
+      `the de-registration must be reported like every other edit to consumer-owned ` +
+        `state; got stderr:\n${stderr || '(empty)'}`,
+    );
+  });
+
+  it('C4d: a second update is a byte-identical no-op', async () => {
+    setupPreFixRepo(consumerDir);
+    const opts = { fetcher: makeFixtureFetcher(), availableTags: AVAILABLE_TAGS };
+
+    await runUpdate(consumerDir, opts);
+    const first = readFileSync(settingsPathIn(consumerDir), 'utf8');
+
+    await runUpdate(consumerDir, opts);
+    const second = readFileSync(settingsPathIn(consumerDir), 'utf8');
+
+    assert.equal(
+      second,
+      first,
+      'the migration must converge in one run — a second update must add nothing and ' +
+        'prune nothing (§9)',
+    );
+  });
+
+  it('C4e: a consumer-authored registration for the old command form is left alone', async () => {
+    // Retirement is scoped to CLI-managed (tagged) entries. An untagged entry
+    // naming the same script is consumer-owned: they may have written it
+    // themselves before the CLI wired hooks at all, and it is not ours to
+    // remove — even though we consider that command form retired.
+    setupPreFixRepo(consumerDir);
+    const settingsPath = settingsPathIn(consumerDir);
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    settings.hooks.SessionStart.push({
+      matcher: '.*',
+      hooks: [{ type: 'command', command: '.claude/hooks/steering-injector.sh' }],
+    });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const after = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const survives = (after.hooks?.SessionStart ?? []).some(
+      (e) =>
+        e[HOOK_TAG] !== true &&
+        (e.hooks ?? []).some((h) => h.command === '.claude/hooks/steering-injector.sh'),
+    );
+    assert.ok(
+      survives,
+      `a consumer-authored entry must survive the prune untouched; got ` +
+        `hooks.SessionStart: ${JSON.stringify(after.hooks?.SessionStart)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// C5 — managed-file-guard is scoped to the tools it inspects
+// ---------------------------------------------------------------------------
+
+describe('C5 — managed-file-guard is registered on Edit|Write, not .*', () => {
+  it('C5: the matcher names the tools whose payload the hook reads', () => {
+    const entry = DEFAULT_HOOK_SCRIPTS.find(
+      (h) => h.script === '.claude/hooks/managed-file-guard.sh',
+    );
+    assert.ok(entry, 'managed-file-guard.sh must be registered');
+    assert.equal(
+      entry.matcher,
+      'Edit|Write',
+      `managed-file-guard reads a written file path out of the hook payload and exits 0 ` +
+        `silently when there is none, so on "${entry.matcher}" it is spawned by every ` +
+        `unrelated tool call — every Read, every Bash — to do nothing`,
+    );
+  });
+});

package/tests/hooks-wave2-registration.test.mjs

@@ -76,13 +76,26 @@ const LOCKFILE_NAME = '.dev-agents-sync.json';
  * holds ONLY these five.
  */
 const WAVE2_REGISTRATIONS = [
-  { command: '.claude/hooks/force-push-guard.sh', event: 'PreToolUse', matcher: 'Bash' },
-  { command: '.claude/hooks/spec-approval-gate.sh', event: 'PreToolUse', matcher: 'Edit|Write' },
-  { command: '.claude/hooks/handoff-state-guard.sh', event: 'PreToolUse', matcher: 'Write' },
-  { command: '.claude/hooks/spec-drift-warn.sh', event: 'PostToolUse', matcher: 'Edit|Write' },
-  { command: '.claude/hooks/pre-pr-preflight.sh', event: 'PreToolUse', matcher: 'Bash' },
+  { script: '.claude/hooks/force-push-guard.sh', event: 'PreToolUse', matcher: 'Bash' },
+  { script: '.claude/hooks/spec-approval-gate.sh', event: 'PreToolUse', matcher: 'Edit|Write' },
+  { script: '.claude/hooks/handoff-state-guard.sh', event: 'PreToolUse', matcher: 'Write' },
+  { script: '.claude/hooks/spec-drift-warn.sh', event: 'PostToolUse', matcher: 'Edit|Write' },
+  { script: '.claude/hooks/pre-pr-preflight.sh', event: 'PreToolUse', matcher: 'Bash' },
 ];
 
+/**
+ * The command string a registration for `script` must carry in settings.json.
+ *
+ * Spelled out here rather than imported from `hookCommandFor`: the interpreter
+ * prefix IS the contract (a bare `.sh` command resolves through the Windows
+ * `.sh` file association to an interactive `bash --login -i`, which opens a
+ * console window per matched tool call), so importing the producer would assert
+ * it equals itself.
+ */
+function expectedCommand(script) {
+  return `bash ${script}`;
+}
+
 function collectFiles(baseDir, currentDir, map, prefix) {
   for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
     const full = path.join(currentDir, entry.name);
@@ -104,9 +117,9 @@ function buildFixtureFileMap() {
   const map = {};
   const targetDir = path.join(FIXTURE_DIR, 'claude');
   if (existsSync(targetDir)) collectFiles(targetDir, targetDir, map, 'claude');
-  for (const { event, command } of DEFAULT_HOOK_SCRIPTS) {
-    map[command.replace(/^\.claude\//, 'claude/')] =
-      `#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# ${event} hook fixture: ${path.basename(command)}.\nexit 0\n`;
+  for (const { event, script } of DEFAULT_HOOK_SCRIPTS) {
+    map[script.replace(/^\.claude\//, 'claude/')] =
+      `#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# ${event} hook fixture: ${path.basename(script)}.\nexit 0\n`;
   }
   return map;
 }
@@ -179,18 +192,18 @@ function managedRegistrations(consumerDir) {
 // ---------------------------------------------------------------------------
 
 describe('W1 — the five wave-2 hooks are registered on the specified event and matcher', () => {
-  for (const { command, event, matcher } of WAVE2_REGISTRATIONS) {
-    it(`W1: ${path.basename(command)} is registered on ${event} with matcher "${matcher}"`, () => {
-      const entries = DEFAULT_HOOK_SCRIPTS.filter((h) => h.command === command);
+  for (const { script, event, matcher } of WAVE2_REGISTRATIONS) {
+    it(`W1: ${path.basename(script)} is registered on ${event} with matcher "${matcher}"`, () => {
+      const entries = DEFAULT_HOOK_SCRIPTS.filter((h) => h.script === script);
       assert.equal(
         entries.length,
         1,
-        `${command} must have exactly one DEFAULT_HOOK_SCRIPTS entry; got ${entries.length}`,
+        `${script} must have exactly one DEFAULT_HOOK_SCRIPTS entry; got ${entries.length}`,
       );
       assert.deepEqual(
         { event: entries[0].event, matcher: entries[0].matcher },
         { event, matcher },
-        `${command} must be wired per docs/specs/260805-hooks-wave-2/plan.md. A wrong event ` +
+        `${script} must be wired per docs/specs/260805-hooks-wave-2/plan.md. A wrong event ` +
           `means the hook never sees the call it guards; a wrong matcher means it is spawned ` +
           `on unrelated tool calls (or skipped on the ones that matter).`,
       );
@@ -205,13 +218,13 @@ describe('W1 — the five wave-2 hooks are registered on the specified event and
       '.claude/hooks/spec-approval-gate.sh',
       '.claude/hooks/handoff-state-guard.sh',
     ];
-    for (const command of blockers) {
-      const entry = DEFAULT_HOOK_SCRIPTS.find((h) => h.command === command);
-      assert.ok(entry, `${command} must be registered`);
+    for (const script of blockers) {
+      const entry = DEFAULT_HOOK_SCRIPTS.find((h) => h.script === script);
+      assert.ok(entry, `${script} must be registered`);
       assert.equal(
         entry.event,
         'PreToolUse',
-        `${command} blocks by exiting 2, which only denies on PreToolUse; on ${entry.event} it ` +
+        `${script} blocks by exiting 2, which only denies on PreToolUse; on ${entry.event} it ` +
           `would be a hook that reports failure and lets the call through`,
       );
     }
@@ -240,8 +253,8 @@ describe('W2 — init and update install and wire every registered hook', () =>
       availableTags: AVAILABLE_TAGS,
     });
 
-    const missing = DEFAULT_HOOK_SCRIPTS.map((h) => h.command).filter(
-      (c) => !existsSync(path.join(consumerDir, c)),
+    const missing = DEFAULT_HOOK_SCRIPTS.map((h) => h.script).filter(
+      (s) => !existsSync(path.join(consumerDir, s)),
     );
     assert.deepEqual(missing, [], `init must install every registered hook script; missing: ${missing}`);
   });
@@ -254,7 +267,8 @@ describe('W2 — init and update install and wire every registered hook', () =>
     });
 
     const wired = managedRegistrations(consumerDir);
-    for (const { event, matcher, command } of DEFAULT_HOOK_SCRIPTS) {
+    for (const { event, matcher, script } of DEFAULT_HOOK_SCRIPTS) {
+      const command = expectedCommand(script);
       assert.ok(
         wired.some((w) => w.command === command && w.event === event && w.matcher === matcher),
         `settings.json must wire ${command} on ${event} with matcher "${matcher}"; ` +
@@ -271,7 +285,8 @@ describe('W2 — init and update install and wire every registered hook', () =>
     });
 
     const wired = managedRegistrations(consumerDir);
-    for (const { event, matcher, command } of DEFAULT_HOOK_SCRIPTS) {
+    for (const { event, matcher, script } of DEFAULT_HOOK_SCRIPTS) {
+      const command = expectedCommand(script);
       assert.ok(
         wired.some((w) => w.command === command && w.event === event && w.matcher === matcher),
         `update must wire ${command} on ${event} with matcher "${matcher}"; ` +
@@ -296,7 +311,10 @@ describe('W2 — init and update install and wire every registered hook', () =>
       .sort();
     assert.deepEqual(
       commands,
-      ['.claude/hooks/force-push-guard.sh', '.claude/hooks/pre-pr-preflight.sh'],
+      [
+        expectedCommand('.claude/hooks/force-push-guard.sh'),
+        expectedCommand('.claude/hooks/pre-pr-preflight.sh'),
+      ],
       'both PreToolUse/Bash hooks must be wired independently',
     );
   });
@@ -309,8 +327,8 @@ describe('W2 — init and update install and wire every registered hook', () =>
     });
 
     const raw = readFileSync(path.join(consumerDir, LOCKFILE_NAME), 'utf8');
-    for (const { command } of WAVE2_REGISTRATIONS) {
-      assert.ok(raw.includes(path.basename(command)), `lockfile must track ${command}`);
+    for (const { script } of WAVE2_REGISTRATIONS) {
+      assert.ok(raw.includes(path.basename(script)), `lockfile must track ${script}`);
     }
   });
 });
@@ -366,12 +384,12 @@ describe('W3 — a second update is a no-op (twice == once)', () => {
 
     await runUpdate(consumerDir, opts);
     const first = DEFAULT_HOOK_SCRIPTS.map((h) =>
-      readFileSync(path.join(consumerDir, h.command), 'utf8'),
+      readFileSync(path.join(consumerDir, h.script), 'utf8'),
     );
 
     await runUpdate(consumerDir, opts);
     const second = DEFAULT_HOOK_SCRIPTS.map((h) =>
-      readFileSync(path.join(consumerDir, h.command), 'utf8'),
+      readFileSync(path.join(consumerDir, h.script), 'utf8'),
     );
 
     assert.deepEqual(second, first, 'hook scripts must be byte-identical after a second update');
@@ -414,8 +432,8 @@ describe('W4 — a pre-wave lockfile upgrades additively', () => {
       assert.ok(raw.includes(name), `upgrade must not drop the pre-wave hook ${name}`);
     }
     // ...and the wave's hooks are added.
-    for (const { command } of WAVE2_REGISTRATIONS) {
-      assert.ok(raw.includes(path.basename(command)), `upgrade must record ${command}`);
+    for (const { script } of WAVE2_REGISTRATIONS) {
+      assert.ok(raw.includes(path.basename(script)), `upgrade must record ${script}`);
     }
   });
 

package/tests/rules-injector-registration.test.mjs

@@ -239,14 +239,20 @@ describe('S1 R1 — DEFAULT_HOOK_SCRIPTS no longer includes rules-injector.sh (r
   });
 
   it('R1c: the three pre-existing managed hooks are still registered (retirement is subtractive only, not destructive)', () => {
-    const commands = DEFAULT_HOOK_SCRIPTS.map((h) => h.command);
+    // Asserted on `script` — the SCRIPT each row registers — because that is
+    // what "still registered" means here: retiring one hook must not drop the
+    // other three from the shipped table. The `command` string is a separate,
+    // independently-versioned concern (it grew a `bash ` prefix to stop the
+    // Windows `.sh` file association from opening a console window), and its
+    // old form is itself on the retired list.
+    const scripts = DEFAULT_HOOK_SCRIPTS.map((h) => h.script);
     for (const expected of [
       '.claude/hooks/steering-injector.sh',
       '.claude/hooks/managed-file-guard.sh',
       '.claude/hooks/uncommitted-check.sh',
     ]) {
       assert.ok(
-        commands.includes(expected),
+        scripts.includes(expected),
         `retiring rules-injector.sh must not drop the existing ${expected} registration`,
       );
     }
@@ -503,8 +509,11 @@ describe('S1 H2 — update reports the retired-hook-registration prune (not sile
 
   it('H2c: no prune line is emitted when there is nothing to prune (guards against a spurious message every run)', async () => {
     setupInitializedRepo(consumerDir, { resolvedVersion: '1.0.0' });
-    // settings.json is already fully wired to the three surviving hooks, with
-    // no retired registration anywhere — nothing to prune.
+    // settings.json is already fully wired to the three surviving hooks — in
+    // the command form the CLI registers TODAY (`bash <path>`; the bare-path
+    // form is itself retired, so seeding that would give the prune real work
+    // and this test would stop testing the no-op case) — with no retired
+    // registration anywhere. Nothing to prune.
     const settingsDir = path.join(consumerDir, '.claude');
     mkdirSync(settingsDir, { recursive: true });
     writeFileSync(
@@ -516,21 +525,21 @@ describe('S1 H2 — update reports the retired-hook-registration prune (not sile
               {
                 [HOOK_TAG]: true,
                 matcher: '.*',
-                hooks: [{ type: 'command', command: '.claude/hooks/steering-injector.sh' }],
+                hooks: [{ type: 'command', command: 'bash .claude/hooks/steering-injector.sh' }],
               },
             ],
             PostToolUse: [
               {
                 [HOOK_TAG]: true,
-                matcher: '.*',
-                hooks: [{ type: 'command', command: '.claude/hooks/managed-file-guard.sh' }],
+                matcher: 'Edit|Write',
+                hooks: [{ type: 'command', command: 'bash .claude/hooks/managed-file-guard.sh' }],
               },
             ],
             Stop: [
               {
                 [HOOK_TAG]: true,
                 matcher: '.*',
-                hooks: [{ type: 'command', command: '.claude/hooks/uncommitted-check.sh' }],
+                hooks: [{ type: 'command', command: 'bash .claude/hooks/uncommitted-check.sh' }],
               },
             ],
           },

package/tests/update-uptodate-wiring.test.mjs

@@ -65,8 +65,10 @@ function noFetchFetcher() {
 function fetcherWithHooks(registrations) {
   return async () => {
     const map = {};
-    for (const { command } of registrations) {
-      map[command.replace(/^\.claude\//, 'claude/')] = hookBody(path.basename(command));
+    // Keyed off `script` (the path), not `command` (`bash <path>`): FileMap keys
+    // are paths, and a shell command string has no recognized prefix.
+    for (const { script } of registrations) {
+      map[script.replace(/^\.claude\//, 'claude/')] = hookBody(path.basename(script));
     }
     return map;
   };
@@ -98,13 +100,13 @@ function setupPinnedRepo(consumerDir, { resolvedVersion = LATEST_IN_RANGE } = {}
  * follows the table the moment a hook is added or retired.
  */
 function seedHookScripts(consumerDir, registrations) {
-  const commands = new Set(registrations.map((h) => h.command));
-  for (const command of commands) {
-    const abs = path.join(consumerDir, command);
+  const scripts = new Set(registrations.map((h) => h.script));
+  for (const script of scripts) {
+    const abs = path.join(consumerDir, script);
     mkdirSync(path.dirname(abs), { recursive: true });
-    writeFileSync(abs, hookBody(path.basename(command)), 'utf8');
+    writeFileSync(abs, hookBody(path.basename(script)), 'utf8');
   }
-  return DEFAULT_HOOK_SCRIPTS.filter((h) => commands.has(h.command)).length;
+  return DEFAULT_HOOK_SCRIPTS.filter((h) => scripts.has(h.script)).length;
 }
 
 /** Captures everything written to stderr while `fn` runs. */