fix(#1634): honor capability hook matcher and node-prefix command (#1638)

* fix(#1634): honor capability hook matcher and node-prefix command

Capability hook install (applyCapabilitySharedEdits) wrote each settings.json
hook entry with no `matcher`, so a tool-scoped hook fired on every tool (a
fail-closed guard could then block the whole session), and emitted a bare
single-quoted script path so a .js-family hook from a git/tarball source
without +x failed with Permission denied on every matching call.

- Pass through an optional declared `matcher` (entry-level sibling of `hooks`);
  absent => omitted (match-all), so existing shipped capabilities are unchanged.
- Validate `matcher` in the declaration (non-empty string, no control chars).
- Emit `node <quoted-path>` for .js/.cjs/.mjs hooks (mirrors first-party);
  .sh and others keep the bare quoted path (unchanged).

Root cause: the manifest hook schema (validator rule C4) was {event, script}
only with no matcher, and applyCapabilitySharedEdits never read or wrote one;
the command used shellSingleQuote(absScript) with no node prefix.

Regression tests fail-first on both defects (matcher dropped; bare path) and
pass after the fix; #1460 command assertions updated for the node prefix.

* chore(#1634): backfill changeset pr:1638

* fix(#1634): resolve lint and windows CI failures

- validator: replace the control-character range regex with a char-code loop.
  The literal /[\x00-\x1f\x7f]/ tripped ESLint's no-control-regex rule; char
  codes are equally precise and lint-clean. Behavior unchanged (still rejects
  matchers containing ASCII control characters incl. DEL).
- test: gate the executable-bit precondition on POSIX. Windows fs does not
  honor POSIX write modes (a 0o644 write reads back as 0o666), so the
  precondition is meaningless there and failed the windows-latest lane. The
  node-prefix assertion — the actual fix — is platform-independent and still
  runs everywhere.

* docs(#1634): amend ADR-894 for optional lifecycle hook matcher

The `role: "feature"` `hooks[]` entry now carries an optional `matcher`
(settings.json tool-scoping pattern: exact/pipe/wildcard/regex). Document
the field in the §2 schema table and record a Grilling-amendments entry:
the install path projects a declared matcher onto the emitted settings.json
hook entry (absent = match-all, so shipped capabilities are unchanged), and
per-runtime matcher projection (ADR-857 D8) stays a separate concern. This
amendment ships with the fix that introduced the field rather than as a
follow-up.

* docs(#1634): record WINDOWS-POSIX-MODE-BIT-ASSERT defect in CONTEXT.md

Capture the CI failure pattern from #1634/PR #1638 so it is not repeated: a
test that writes a file with a POSIX mode and then asserts statSync().mode
& 0o777 === <octal> passes on macOS/Linux but fails on windows-latest
(Windows fs does not honor POSIX write modes — reads back 0o666). Added as a
machine-greppable DEFECT predicate (symptom/examples/detect/fix-forward/
prevention) next to DEFECT.WINDOWS-TEST-PORTABILITY, with the fix-forward:
gate the mode-bit precondition on process.platform !== 'win32' and keep the
platform-independent behavioral assertion running everywhere.

src/capability-lifecycle.cts

@@ -414,6 +414,21 @@ function shellSingleQuote(value: string): string {
   return "'" + value.replace(/'/g, "'\\''") + "'";
 }
 
+/**
+ * #1634: build the emitted hook `command` for an ABSOLUTE confined script path. For `.js`-family
+ * hooks (`.js`/`.cjs`/`.mjs`) prefix with `node` so the hook runs regardless of the source's
+ * executable bit — a `git`/tarball source that lost `+x` would otherwise yield
+ * `/bin/sh: Permission denied` on every matching call (defect #2). This mirrors first-party hooks
+ * (`node "${CLAUDE_PLUGIN_ROOT}/hooks/x.js"`). The path stays POSIX single-quoted (#1460 (R) HIGH)
+ * so a space-containing install prefix cannot word-split or inject. Non-JS scripts (e.g. `.sh`)
+ * keep the bare single-quoted absolute path (unchanged) — they remain responsible for their own
+ * executability, exactly as before; per-runtime command projection is a separate concern (ADR-857 D8).
+ */
+const JS_HOOK_EXT_RE = /\.(?:js|cjs|mjs)$/;
+function runnableHookCommand(absScript: string): string {
+  return JS_HOOK_EXT_RE.test(absScript) ? 'node ' + shellSingleQuote(absScript) : shellSingleQuote(absScript);
+}
+
 /**
  * #1460 CONF-1: resolve a hook `script` (declared RELATIVE to the bundle) against the capability's
  * own install dir and CONFINE it via realpath, returning the ABSOLUTE confined path or null when it
@@ -609,6 +624,11 @@ function applyCapabilitySharedEdits(args: {
         const event = typeof rec['event'] === 'string' ? rec['event'] : '';
         const script = typeof rec['script'] === 'string' ? rec['script'] : '';
         if (!event || !script || isUnsafeKey(event)) continue;
+        // #1634: optional tool-scoping `matcher` (a settings.json concept — entry-level sibling of
+        // `hooks`). Absent => match-all (field OMITTED so the existing shipped capabilities' wiring
+        // is byte-for-byte unchanged, Hyrum's Law). The validator gates this to a non-empty string.
+        const matcherRaw = rec['matcher'];
+        const matcher = typeof matcherRaw === 'string' && matcherRaw.length > 0 ? matcherRaw : null;
         // #1460 CONF-1: resolve the declared (relative) script against the capability's OWN install
         // dir and CONFINE via realpath, then write the ABSOLUTE confined path as the hook command —
         // never the raw relative path (which would resolve against the CWD at hook-exec time and could
@@ -616,14 +636,17 @@ function applyCapabilitySharedEdits(args: {
         // through a symlinked subdir) return null and are SKIPPED, exactly as before.
         const absScript = confinedBundleScript(capDir(runtimeDir, capId), script);
         if (absScript === null) continue;
-        // #1460 (R) HIGH: the hook `command` is consumed by a shell (first-party hooks emit
-        // `node "${CLAUDE_PLUGIN_ROOT}/hooks/x.js"`). The absolute path begins with the
-        // (non-manifest) install-prefix, which commonly contains spaces — emit it POSIX
-        // single-quoted so the prefix cannot word-split or inject. The script BASENAME is
-        // already restricted to a shell-safe allowlist by isSafeHookScriptPath above.
-        const command = shellSingleQuote(absScript);
+        // #1460 (R) HIGH + #1634: the hook `command` is consumed by a shell. `runnableHookCommand`
+        // emits a `node`-prefixed POSIX-single-quoted absolute path for `.js`-family hooks (runs
+        // without `+x`; mirrors first-party) and a bare single-quoted path otherwise. Single-quoting
+        // keeps a space-containing install prefix as one shell token (cannot word-split or inject).
+        const command = runnableHookCommand(absScript);
         const arr = Array.isArray(hooksObj[event]) ? (hooksObj[event] as unknown[]) : [];
-        arr.push({ [CAP_MARKER]: capId, hooks: [{ type: 'command', command }] });
+        // #1634: stamp the marker so the entry is surgically strippable, and carry the declared
+        // `matcher` (entry-level sibling of `hooks`) only when the author declared one.
+        const entry: Record<string, unknown> = { [CAP_MARKER]: capId, hooks: [{ type: 'command', command }] };
+        if (matcher !== null) entry['matcher'] = matcher;
+        arr.push(entry);
         hooksObj[event] = arr;
         touched = true;
       }