auriga-cli 1.5.0 → 1.6.0

package/README.md

@@ -14,7 +14,7 @@ This repo itself is a fully configured harness project. You can clone it to see
 | **Skills** | Development process skills — brainstorming, systematic-debugging, TDD, verification, planning, playwright |
 | **Recommended Skills** | Optional utility skills (e.g. `ui-ux-pro-max`) you can add on top of the workflow skills |
 | **Plugins** | Recommended Claude Code plugins — skill-creator, claude-md-management, codex |
-| **Hooks** | Claude Code hooks: `notify` (macOS notification), `pr-create-guard` (PostToolUse body snapshot after `gh pr create`), `pr-ready-guard` (PreToolUse block on stray planning docs / unpushed commits before `gh pr ready`) |
+| **Hooks** | Claude Code hooks: `notify` (macOS notification, focus-aware sound-only when terminal is frontmost), `pr-create-guard` (PostToolUse body snapshot after `gh pr create`), `pr-ready-guard` (PreToolUse block on stray planning docs / active specs in `docs/specs/` / unpushed commits before `gh pr ready`) |
 
 ## Quick Start
 
@@ -79,9 +79,9 @@ Installs Claude Code hooks into a chosen scope. Each hook is self-contained unde
 
 | Hook | Description |
 |---|---|
-| notify | Native macOS notification when Claude needs your attention. Shows the brand mark in the small app-icon position, with click-to-activate that brings the originating terminal back to the foreground. Auto-installs `alerter` via Homebrew (`vjeantet/tap/alerter`). Customize sound and icon by editing `.claude/hooks/notify/config.json` and replacing `.claude/hooks/notify/icon.png`. macOS-only at runtime; silent no-op on other platforms. |
+| notify | Native macOS notification when Claude needs your attention. Shows the brand mark in the small app-icon position; click brings the originating terminal back to focus. **Focus-aware**: when the launching terminal is already frontmost, drops the banner and plays the sound only (toggle via `soundOnlyWhenFocused` in `config.json`). **Per-project group ID**: new notifications cleanly replace older ones in Notification Center, no process accumulation, no cross-project interference. Auto-installs `alerter` via Homebrew (`vjeantet/tap/alerter`). Customize sound and icon by editing `.claude/hooks/notify/config.json` and `.claude/hooks/notify/icon.png`. macOS-only at runtime; silent no-op on other platforms. |
 | pr-create-guard | PostToolUse hook for `gh pr create`. Queries the newly-created PR via `gh pr view` and injects a body snapshot (headings found + TODO-checkbox counts) as `additionalContext` for the Agent to self-verify against the step-10 scope / acceptance / risks / TODO contract. Never blocks — PostToolUse runs after the fact. Graceful degradation when gh is unavailable. |
-| pr-ready-guard | PreToolUse hook for `gh pr ready`. Blocks on structural signals only: stray planning docs at `findings.md` / `progress.md` / `task_plan.md` / `docs/superpowers/specs/*.md` (must be archived to `docs/worklog-<date>-<branch>/` per the `Document Conventions` in CLAUDE.md), or unpushed commits on the current branch. No text regex of PR content is ever used as a block signal. On pass, injects a PR body snapshot as `additionalContext`. |
+| pr-ready-guard | PreToolUse hook for `gh pr ready`. Blocks on structural signals only: (1) stray planning docs at `findings.md` / `progress.md` / `task_plan.md` / `docs/superpowers/specs/*.md` — must be archived to `docs/worklog/worklog-<date>-<branch>/` (or deleted) per CLAUDE.md `Document Conventions`; (2) unfinalized active specs at `docs/specs/*.md` — must be promoted to `docs/architecture/`, archived, or deleted; (3) unpushed commits on the current branch. No text regex of PR content is ever used as a block signal. On pass, injects a PR body snapshot as `additionalContext`. |
 
 Scope choices:
 

package/README.zh-CN.md

@@ -14,7 +14,7 @@
 | **Skills** | 开发流程 skills —— brainstorming、systematic-debugging、TDD、verification、planning、playwright |
 | **Recommended Skills** | 可选的工具类 skills（如 `ui-ux-pro-max`），在 workflow skills 之外按需追加 |
 | **Plugins** | 推荐的 Claude Code 插件 —— skill-creator、claude-md-management、codex |
-| **Hooks** | Claude Code hooks：`notify`（macOS 通知）、`pr-create-guard`（`gh pr create` 后注入 PR body 快照的 PostToolUse）、`pr-ready-guard`（`gh pr ready` 前按游离 planning 文档 / 未 push commits 拦截的 PreToolUse） |
+| **Hooks** | Claude Code hooks：`notify`（macOS 通知，终端在焦点时仅放声不弹横幅）、`pr-create-guard`（`gh pr create` 后注入 PR body 快照的 PostToolUse）、`pr-ready-guard`（`gh pr ready` 前按游离 planning 文档 / `docs/specs/` 内未清理的 spec / 未 push commits 拦截的 PreToolUse） |
 
 ## 快速开始
 
@@ -79,9 +79,9 @@ npx auriga-cli
 
 | Hook | 说明 |
 |---|---|
-| notify | 当 Claude 需要你关注时弹一条原生 macOS 通知。在通知小图标位显示品牌图，点击通知可把发起 Claude 的终端拉回前台。会自动通过 Homebrew 安装 `alerter`（`vjeantet/tap/alerter`）。改 `.claude/hooks/notify/config.json` 即可换提示音、替换 `.claude/hooks/notify/icon.png` 即可换图标。仅 macOS 运行时生效，其它平台静默 no-op。 |
+| notify | 当 Claude 需要你关注时弹一条原生 macOS 通知。在通知小图标位显示品牌图，点击通知可把发起 Claude 的终端拉回前台。**焦点感知**：发起 Claude 的终端正处于前台时，仅放提示音不弹横幅（通过 `config.json` 的 `soundOnlyWhenFocused` 切换）。**按项目分组**：新通知会干净地替换通知中心里的旧条目，不会进程堆积，也不会跨项目互相覆盖。会自动通过 Homebrew 安装 `alerter`（`vjeantet/tap/alerter`）。改 `.claude/hooks/notify/config.json` 即可换提示音、替换 `.claude/hooks/notify/icon.png` 即可换图标。仅 macOS 运行时生效，其它平台静默 no-op。 |
 | pr-create-guard | `gh pr create` 的 PostToolUse hook。创建成功后通过 `gh pr view` 拉真实 PR body，扫 `^##` / `^###` headings 并统计 `- [ ]` / `- [x]`，通过 `additionalContext` 注入快照让 Agent 对照 step 10 的"范围 / 验收标准 / 风险 / 剩余 TODO"四要素。不 block——PostToolUse 发生在动作之后。gh 不可用时静默降级。 |
-| pr-ready-guard | `gh pr ready` 的 PreToolUse hook。**只按结构信号**拦截：仓库根存在游离 planning 文档（`findings.md` / `progress.md` / `task_plan.md`），或 `docs/superpowers/specs/*.md` 未归档——这些必须按 CLAUDE.md 的"文档规范"迁到 `docs/worklog-<date>-<branch>/`；或者本地有未 push commits。**不做 PR 正文文本 regex 匹配**。放行时注入 PR body 快照。 |
+| pr-ready-guard | `gh pr ready` 的 PreToolUse hook。**只按结构信号**拦截：(1) 仓库根存在游离 planning 文档（`findings.md` / `progress.md` / `task_plan.md`）或 `docs/superpowers/specs/*.md` 未归档——按 CLAUDE.md 的"文档规范"迁到 `docs/worklog/worklog-<date>-<branch>/` 或删除；(2) `docs/specs/*.md` 内有未结案的活跃 spec——晋升到 `docs/architecture/`、归档或删除；(3) 本地有未 push commits。**不做 PR 正文文本 regex 匹配**。放行时注入 PR body 快照。 |
 
 作用域选择：
 

package/dist/hooks.d.ts

@@ -5,7 +5,17 @@ export interface HookDep {
 }
 export interface HookSettingsEvent {
     event: string;
+    /** Tool-name / regex filter; mapped onto the container-level
+     *  `matcher` field in settings.json. Absent → every tool fires. */
     matcher?: string;
+    /** Permission-rule-syntax filter — mapped onto the nested action-level
+     *  `if` field in settings.json. Format: `<ToolName>(<substring>)`, e.g.
+     *  `Bash(gh pr create)` — see IF_RE for the exact grammar. Lets the
+     *  Claude Code runtime skip hook dispatch when the tool input doesn't
+     *  match, avoiding a Node subprocess spawn per unrelated call.
+     *  Absent → no registry-level content filter (the hook script runs
+     *  for every invocation that passed `matcher`). */
+    if?: string;
 }
 export interface HookDef {
     name: string;
@@ -32,6 +42,10 @@ export interface SettingsHookAction {
     type: "command";
     command: string;
     _marker?: string;
+    /** Per-action permission-rule filter (Claude Code ≥ 2026-04 schema).
+     *  Format: `<ToolName>(<substring>)`. Older runtimes ignore unknown
+     *  fields, so emitting this is forward-safe. */
+    if?: string;
 }
 export interface SettingsHookGroup {
     matcher?: string;
@@ -52,12 +66,33 @@ export interface SettingsFile {
  *      and never wrote our marker. Without this fallback we would happily
  *      append a duplicate next to it and the hook would fire twice.
  *
+ * `options.matcher` writes to the container-level `matcher` (tool-name
+ * filter); `options.ifRule` writes to the action-level `if` (permission-
+ * rule substring filter, Claude Code ≥ 2026-04). Either or both may be
+ * absent.
+ *
+ * Upgrade path: if an entry with our marker already exists but its
+ * matcher / if disagrees with the desired values, we update those two
+ * fields in place (preserving everything else — command, sibling
+ * actions, the user's other groups — untouched). This is the path for
+ * a user who installed an older registry version and re-runs the
+ * installer after hooks.json changed. Pure no-op when the existing
+ * fields already match.
+ *
+ * Inputs are defense-in-depth revalidated here against IF_RE + the
+ * event-name regex even though registry callers already passed
+ * loadHooksConfig, so a direct library caller can't write malformed
+ * values into settings.json by bypassing the registry loader.
+ *
  * Throws if `settings.hooks[event]` exists but is not an array — that
  * means the user has hand-edited their settings into a shape we do not
  * recognize, and silently replacing it with an empty array would lose
  * data. Callers should catch and surface the error to the user.
  */
-export declare function addHookToSettings(settings: SettingsFile, event: string, command: string, marker: string): {
+export declare function addHookToSettings(settings: SettingsFile, event: string, command: string, marker: string, options?: {
+    matcher?: string;
+    ifRule?: string;
+}): {
     settings: SettingsFile;
     mutated: boolean;
 };

package/dist/hooks.js

@@ -32,6 +32,29 @@ const EVENT_NAME_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
 // the form requires a code change here, intentionally — see the security
 // review trail in PR #7 for context.
 const COMMAND_RE = /^(node|python3|bash) "\$HOOK_DIR\/[A-Za-z0-9_-]+\.[A-Za-z0-9]+"$/;
+// Claude Code permission-rule syntax for the `if` field:
+//   <ToolName>(<substring>)
+// Tool name: EVENT_NAME-shape identifier, bounded to 64 chars so a
+// malicious registry can't inflate settings.json with a gigantic prefix.
+// Substring body: 1-200 printable-ASCII chars, with parens, backslash,
+// and backtick explicitly excluded so the anchored `\(...\)` wrapper
+// actually delimits a well-formed outer parenthesis pair.
+//
+// The safety argument is NOT that IF_RE strips shell metacharacters —
+// `$ " ' ; | & < > *` are all inside the allowed byte range and left
+// intact. The defense is that this string never reaches a shell: it's
+// written verbatim into settings.json as a JSON string and read by
+// Claude Code's in-process permission-rule matcher. A registry
+// compromise can widen or misdirect the match pattern (causing the hook
+// to fire on unintended inputs or not fire at all) but cannot pivot
+// into command execution from this field.
+//
+// Body range decomposition (what the char class actually covers):
+//   0x20-0x27  space through single-quote       (excludes nothing)
+//   0x2A-0x5B  asterisk through left-bracket    (excludes `(` 0x28, `)` 0x29)
+//   0x5D-0x5F  right-bracket through underscore (excludes `\` 0x5C)
+//   0x61-0x7E  lowercase through tilde          (excludes `` ` `` 0x60)
+const IF_RE = /^[A-Z][A-Za-z0-9_-]{0,63}\([\x20-\x27\x2A-\x5B\x5D-\x5F\x61-\x7E]{1,200}\)$/;
 function isSafeRelativePath(file) {
     if (typeof file !== "string" || file.length === 0)
         return false;
@@ -104,6 +127,10 @@ function validateHookEntry(hook, idx) {
         if (matcher !== undefined && (typeof matcher !== "string" || !EVENT_NAME_RE.test(matcher))) {
             throw new Error(`hooks.json: hooks[${idx}].settingsEvents.matcher must match ${EVENT_NAME_RE} (got ${JSON.stringify(matcher)})`);
         }
+        const ifRule = evt.if;
+        if (ifRule !== undefined && (typeof ifRule !== "string" || !IF_RE.test(ifRule))) {
+            throw new Error(`hooks.json: hooks[${idx}].settingsEvents.if must match ${IF_RE} (got ${JSON.stringify(ifRule)})`);
+        }
     }
     if (typeof h.command !== "string" || !COMMAND_RE.test(h.command)) {
         throw new Error(`hooks.json: hooks[${idx}].command must match the safe template ${COMMAND_RE} (got ${JSON.stringify(h.command)})`);
@@ -133,12 +160,40 @@ function validateHookEntry(hook, idx) {
  *      and never wrote our marker. Without this fallback we would happily
  *      append a duplicate next to it and the hook would fire twice.
  *
+ * `options.matcher` writes to the container-level `matcher` (tool-name
+ * filter); `options.ifRule` writes to the action-level `if` (permission-
+ * rule substring filter, Claude Code ≥ 2026-04). Either or both may be
+ * absent.
+ *
+ * Upgrade path: if an entry with our marker already exists but its
+ * matcher / if disagrees with the desired values, we update those two
+ * fields in place (preserving everything else — command, sibling
+ * actions, the user's other groups — untouched). This is the path for
+ * a user who installed an older registry version and re-runs the
+ * installer after hooks.json changed. Pure no-op when the existing
+ * fields already match.
+ *
+ * Inputs are defense-in-depth revalidated here against IF_RE + the
+ * event-name regex even though registry callers already passed
+ * loadHooksConfig, so a direct library caller can't write malformed
+ * values into settings.json by bypassing the registry loader.
+ *
  * Throws if `settings.hooks[event]` exists but is not an array — that
  * means the user has hand-edited their settings into a shape we do not
  * recognize, and silently replacing it with an empty array would lose
  * data. Callers should catch and surface the error to the user.
  */
-export function addHookToSettings(settings, event, command, marker) {
+export function addHookToSettings(settings, event, command, marker, options = {}) {
+    // Defense-in-depth: registry callers pre-validate via loadHooksConfig,
+    // but a direct programmatic caller could bypass that. Refuse values
+    // that wouldn't have cleared the registry validator, so settings.json
+    // can never receive a malformed string through this function.
+    if (options.matcher !== undefined && !EVENT_NAME_RE.test(options.matcher)) {
+        throw new Error(`addHookToSettings: options.matcher must match ${EVENT_NAME_RE} (got ${JSON.stringify(options.matcher)})`);
+    }
+    if (options.ifRule !== undefined && !IF_RE.test(options.ifRule)) {
+        throw new Error(`addHookToSettings: options.ifRule must match ${IF_RE} (got ${JSON.stringify(options.ifRule)})`);
+    }
     const next = JSON.parse(JSON.stringify(settings ?? {}));
     if (next.hooks !== undefined && (typeof next.hooks !== "object" || Array.isArray(next.hooks))) {
         throw new Error(`settings.hooks exists but is not an object; refusing to clobber it`);
@@ -157,8 +212,21 @@ export function addHookToSettings(settings, event, command, marker) {
             if (!action)
                 continue;
             if (action._marker === marker) {
+                // Our entry already exists. Upgrade matcher / if in place if
+                // they drifted from the desired values; leave command + other
+                // fields alone (users may have hand-tweaked; we only own the
+                // two fields registry declares).
+                let drifted = false;
+                if (options.matcher !== undefined && group.matcher !== options.matcher) {
+                    group.matcher = options.matcher;
+                    drifted = true;
+                }
+                if (options.ifRule !== undefined && action.if !== options.ifRule) {
+                    action.if = options.ifRule;
+                    drifted = true;
+                }
                 next.hooks[event] = list;
-                return { settings: next, mutated: false };
+                return { settings: next, mutated: drifted };
             }
             if (action.type === "command" && action.command === command) {
                 // A pre-existing entry (manual or from another tool) already
@@ -170,9 +238,13 @@ export function addHookToSettings(settings, event, command, marker) {
             }
         }
     }
-    list.push({
-        hooks: [{ type: "command", command, _marker: marker }],
-    });
+    const action = { type: "command", command, _marker: marker };
+    if (options.ifRule !== undefined)
+        action.if = options.ifRule;
+    const group = { hooks: [action] };
+    if (options.matcher !== undefined)
+        group.matcher = options.matcher;
+    list.push(group);
     next.hooks[event] = list;
     return { settings: next, mutated: true };
 }
@@ -434,7 +506,10 @@ function writeMergedSettings(resolved, hook, parsed) {
     let next = parsed;
     for (const evt of hook.settingsEvents) {
         const cmd = hook.command.replace(/\$HOOK_DIR/g, resolved.commandHookDir);
-        const result = addHookToSettings(next, evt.event, cmd, hook.marker);
+        const result = addHookToSettings(next, evt.event, cmd, hook.marker, {
+            matcher: evt.matcher,
+            ifRule: evt.if,
+        });
         if (result.mutated)
             mutated = true;
         next = result.settings;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins, Hooks)",
   "type": "module",
   "bin": {