@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/daemon/rules/defaults.js

@@ -0,0 +1,779 @@
+/**
+ * Default tool_intercept rules (v9.x Phase 1, D1 strict mode).
+ *
+ * 5 deny + 1 warn — see master-roadmap D1 decision (2026-05-22) for the
+ * rationale on each. Hints follow the spec §4.2 design:
+ *   1. Specific fix command (spawn X with prompt Y)
+ *   2. CLAUDE.md anchor for the rule narrative
+ *   3. Bypass mechanism made explicit
+ *
+ * Adding a new rule: keep `match` purely on `ToolInputFields` + `RuleContext`;
+ * if a rule needs DB lookup, pre-compute the signal in PreToolUseHandler and
+ * expose it on `RuleContext` (so rules stay synchronous + cheap).
+ */
+import { isQuestionPrompt, hasDirectFixOverride, scoreKeywordBuckets, } from './workflow-defaults.js';
+// ── Helpers ────────────────────────────────────────────────────────────────
+/** Token-aware command splitter that respects single/double quotes. */
+function splitCommand(cmd) {
+    const tokens = [];
+    let buf = '';
+    let inSingle = false;
+    let inDouble = false;
+    for (const ch of cmd) {
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            buf += ch;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            buf += ch;
+            continue;
+        }
+        if (/\s/.test(ch) && !inSingle && !inDouble) {
+            if (buf) {
+                tokens.push(buf);
+                buf = '';
+            }
+            continue;
+        }
+        buf += ch;
+    }
+    if (buf)
+        tokens.push(buf);
+    return tokens;
+}
+/**
+ * Does the command target multiple files / a directory rather than a single
+ * named file? Used by Bash grep / find rules so that the trivial single-file
+ * use-case (`grep foo bar.ts`) is NOT intercepted.
+ *
+ * Heuristics (intentionally conservative — false negatives are OK, false
+ * positives are not):
+ *   • -r / -R / --recursive present                → multi-file
+ *   • final positional arg ends with '/'           → directory
+ *   • a positional arg is exactly 'src' / 'tests'  → directory
+ *   • glob characters ('*' / '?' / brace) in args  → multi-file
+ *   • file extension wildcards (`*.ts`, `*.js`)    → multi-file
+ */
+function looksMultiFile(tokens) {
+    const args = tokens.slice(1); // drop the command name itself
+    for (const a of args) {
+        if (a === '-r' || a === '-R' || a === '--recursive')
+            return true;
+    }
+    // Positional args (skip flags). We only inspect non-flag args because a
+    // grep PATTERN like '-foo' would otherwise be misread as a flag.
+    const positionals = args.filter((a) => !a.startsWith('-'));
+    // Skip the very first positional (it's usually the search pattern).
+    const fileArgs = positionals.slice(1);
+    for (const a of fileArgs) {
+        if (a.endsWith('/'))
+            return true;
+        if (a === 'src' || a === 'tests' || a === 'lib' || a === 'app')
+            return true;
+        if (a.includes('*') || a.includes('?') || a.includes('{'))
+            return true;
+    }
+    // No file arg at all (e.g. `grep -r foo` with no positional dir) — treat as multi-file
+    // because grep defaults to cwd in recursive mode.
+    if (fileArgs.length === 0 && args.some((a) => a === '-r' || a === '-R'))
+        return true;
+    return false;
+}
+/**
+ * Recognised search-tool head commands for `bash-grep-multi-file`.
+ *
+ * Live-data triage (2026-05-26) found the rule firing on `cp -r ... && grep`,
+ * `rm -rf ... | grep Health`, `chmod ... && bash` etc. where the user intent
+ * is clearly the leading mutation command and grep is just a post-verification
+ * filter. Narrowing to "first token must be a search tool" eliminates those
+ * false positives while preserving real exploratory grep/rg/ag/git-grep cases.
+ *
+ * NOTE: `find` is handled by the separate `bash-find-source` rule and is NOT
+ * included here.
+ */
+const GREP_HEAD_TOOLS = new Set([
+    'grep',
+    'rg',
+    'ripgrep',
+    'ack',
+    'ag',
+]);
+/**
+ * True if the FIRST shell command of the line is a recognised search tool.
+ *
+ * "First command" = before any of `&&`, `||`, `;`, `|`, `&` (the connectors
+ * that introduce a *new* command). Leading `time` / env-prefix etc. are NOT
+ * stripped (rare in practice; keeping the matcher simple).
+ *
+ * Special-case `git grep` — when first token is `git` and second is `grep`,
+ * still counts as a grep head.
+ */
+function isGrepHeadCommand(cmd) {
+    // Take everything up to the first shell connector.
+    // Order matters: && before & so we split on the longer token first.
+    let head = cmd;
+    for (const sep of ['&&', '||', ';', '|', '&']) {
+        const idx = head.indexOf(sep);
+        if (idx !== -1)
+            head = head.slice(0, idx);
+    }
+    head = head.trim();
+    if (!head)
+        return false;
+    const firstTokens = splitCommand(head);
+    if (firstTokens.length === 0)
+        return false;
+    const first = firstTokens[0];
+    if (GREP_HEAD_TOOLS.has(first))
+        return true;
+    // `git grep` form: first=git, second=grep.
+    if (first === 'git' && firstTokens.length >= 2 && firstTokens[1] === 'grep')
+        return true;
+    return false;
+}
+/** Detect a single-file `git log` / `git diff` use (i.e. `-- <file>` is present). */
+function gitHasFileSelector(tokens) {
+    // Look for the `--` separator followed by at least one positional arg.
+    const dashDash = tokens.indexOf('--');
+    if (dashDash === -1)
+        return false;
+    const after = tokens.slice(dashDash + 1).filter((t) => t && !t.startsWith('-'));
+    return after.length >= 1;
+}
+/**
+ * P0-3 fix (2026-05-27): whitelist for `git log` / `git diff` flag forms that
+ * are part of normal workflows (CLAUDE.md commit checklist requires
+ * `git log --oneline -N` to mimic commit message style; PR review needs
+ * `git diff --stat` / `--name-only`). Returns true when the command is one
+ * of these structured forms and the rule should bypass.
+ *
+ * Patterns covered (only fires when `\\bgit\\s+(log|diff)` is also present):
+ *   • git log --oneline / --pretty / --graph (history summary)
+ *   • git log -n N / -N (numeric line cap)
+ *   • git log --format / --since / --author / --grep (filtered queries)
+ *   • git diff --stat / --name-only / --shortstat (summary forms)
+ */
+function isGitLogDiffWorkflowForm(cmd) {
+    // git log --oneline / --pretty / --graph
+    if (/\bgit\s+log\s+(--oneline|--pretty|--graph)/.test(cmd))
+        return true;
+    // git log -n N / -N (e.g. `git log -30` / `git log -n 30`)
+    if (/\bgit\s+log\s+-(n\s+\d+|\d+)\b/.test(cmd))
+        return true;
+    // git log --format / --since / --author / --grep (filtered queries)
+    if (/\bgit\s+log\s+--(format|since|author|grep)/.test(cmd))
+        return true;
+    // git diff --stat / --name-only / --shortstat (review summary forms)
+    if (/\bgit\s+diff\s+(--stat|--name-only|--shortstat)/.test(cmd))
+        return true;
+    return false;
+}
+/**
+ * P0-2 fix (2026-05-27): "filter-then-mutate" pattern detection.
+ *
+ * When a command starts with a grep/rg/etc. AND chains through `&&` to a
+ * mutation verb (git add / cp / mv / rm / chmod / bash), the user intent is
+ * "filter some files then act on them" — not exploratory cross-file search.
+ * The bash-grep-multi-file rule should bypass these.
+ *
+ * VERIFY-B1 sample analysis (386 dry_run rows / 7d): most false-positives are
+ * already covered by `recent_agent_spawn` once F6 is fixed; this guard catches
+ * the residual cases where a main-thread filter+mutate pipeline survives.
+ *
+ * Conservative regex — only fires when ALL of: head is search tool, `&&`
+ * present, and the part after `&&` starts with one of the mutation verbs.
+ */
+const MUTATION_VERBS = ['git add', 'cp ', 'mv ', 'rm ', 'chmod ', 'bash '];
+function looksFilterContext(cmd) {
+    // Need at least one `&&` for the filter→mutate pattern.
+    if (!cmd.includes('&&'))
+        return false;
+    const parts = cmd.split('&&').map((p) => p.trim()).filter(Boolean);
+    // Iterate parts AFTER the first; if any begins with a mutation verb, treat
+    // the whole line as filter context.
+    for (let i = 1; i < parts.length; i++) {
+        const p = parts[i].toLowerCase();
+        if (MUTATION_VERBS.some((v) => p.startsWith(v)))
+            return true;
+    }
+    return false;
+}
+/** True if the prompt explicitly declares hook-protocol repair intent. */
+function isHookRepairIntent(prompt) {
+    if (!prompt)
+        return false;
+    const lower = prompt.toLowerCase();
+    return /(hook.{0,8}(protocol|协议|契约))/i.test(prompt)
+        || /修复.*hook/.test(prompt)
+        || lower.includes('fix hook')
+        || lower.includes('repair hook');
+}
+/**
+ * f47c2c90 (2026-06-17): 元任务文件白名单 — these inline single-file changes are
+ * legitimate "main thread does it itself" operations, NOT the kind of
+ * substantive change that should spawn an agent. Matching any clause here makes
+ * the `inline-edit-no-spawn` / `inline-write-no-spawn` warn rules放行 (return
+ * false / no match). Judged purely on the `file_path` string (basename / path
+ * fragment), case-insensitive for basenames — never reads gzip event content.
+ *
+ * Whitelist clauses (match ANY → meta-task,放行):
+ *   • basename ∈ { CLAUDE.md, README.md, CHANGELOG.md, package.json,
+ *     package-lock.json, tsconfig.json, .gitignore, VERSION }
+ *   • path contains `/docs/`, `/.forge-knowledge/`, or `/.claude/`
+ *     (docs / KB live-docs / agent templates & config)
+ *   • basename ends with `.md` AND path contains `/docs/` or `/.forge-knowledge/`
+ *   • version files: basename === `version.ts` OR matches `version.<ext>`
+ *
+ * NOTE: `scripts/*.sh` is intentionally NOT whitelisted — hook scripts already
+ * have the dedicated `edit-hook-script-from-main` deny rule, and other script
+ * changes are usually substantive. Revisit if gray-rollout shows high FPs (Q2).
+ */
+const META_TASK_BASENAMES = new Set([
+    'claude.md',
+    'readme.md',
+    'changelog.md',
+    'package.json',
+    'package-lock.json',
+    'tsconfig.json',
+    '.gitignore',
+    'version',
+    'version.ts',
+]);
+function isMetaTaskFile(filePath) {
+    const fp = filePath.trim();
+    if (!fp)
+        return false;
+    // Normalise separators + extract basename (last path segment).
+    const norm = fp.replace(/\\/g, '/');
+    const basename = norm.slice(norm.lastIndexOf('/') + 1);
+    const lowerBase = basename.toLowerCase();
+    // (1) exact basename whitelist (case-insensitive).
+    if (META_TASK_BASENAMES.has(lowerBase))
+        return true;
+    // (2) version files: `version.*` (e.g. version.json / version.txt).
+    if (/^version\.[^/]+$/i.test(basename))
+        return true;
+    // (3) path-fragment whitelist: docs / KB live-docs / agent templates+config.
+    if (norm.includes('/docs/') || norm.includes('/.forge-knowledge/') || norm.includes('/.claude/')) {
+        return true;
+    }
+    // (4) markdown docs anywhere under docs / KB trees (redundant with (3) but
+    //     kept explicit for泛文档 intent + future收窄 — see spec open question Q2).
+    if (lowerBase.endsWith('.md') && (norm.includes('/docs/') || norm.includes('/.forge-knowledge/'))) {
+        return true;
+    }
+    return false;
+}
+// ── Rule definitions ───────────────────────────────────────────────────────
+const BYPASS_SUFFIX = '\n\n如确认需要继续，请在命令末尾追加 `# forge:bypass=<原因>`（或 Edit/Write 内容里加 `// forge:bypass=<原因>` 注释）。';
+const RULE_BASH_GREP_MULTI_FILE = {
+    id: 'bash-grep-multi-file',
+    kind: 'tool_intercept',
+    description: 'Bash 跨多文件 grep / git grep 应 spawn Explore agent',
+    claudemdRef: 'CLAUDE.md:112 强制 spawn 的场景 → 查/找/看/列出',
+    tool: 'Bash',
+    decision: 'deny',
+    match: (input, ctx) => {
+        const cmd = (input.command ?? '').trim();
+        if (!cmd)
+            return false;
+        // C4 hotfix (2026-05-26): head-command gate. Only fire when the FIRST
+        // shell command is a recognised search tool (grep/rg/ripgrep/ack/ag/
+        // `git grep`). Eliminates false positives where mutation commands
+        // (`cp`, `rm`, `mkdir`, `chmod`, `cat`, `ls`) have a trailing grep used
+        // for post-verification. See triage in
+        // docs/implementation/2026-05-26/HHMM-c4-obey-ratio-fix-changelog.md.
+        if (!isGrepHeadCommand(cmd))
+            return false;
+        // Recent agent spawn relaxes the rule (we're likely inside an Explore agent).
+        if (ctx.recent_agent_spawn)
+            return false;
+        // P0-2 fix (2026-05-27): filter-then-mutate guard — `grep ... && git add ...`
+        // is a workflow pattern (filter files, then act on the result), not a
+        // cross-file exploratory grep. Skip these.
+        if (looksFilterContext(cmd))
+            return false;
+        const tokens = splitCommand(cmd);
+        return looksMultiFile(tokens);
+    },
+    hint: (input) => {
+        const cmd = (input.command ?? '').slice(0, 120);
+        return [
+            `跨文件 grep / git grep 属于探索任务（CLAUDE.md:104 「查/找/看/列出 → Explore agent」）。`,
+            `命令：${cmd}`,
+            ``,
+            `请改用 Task tool spawn subagent_type='general-purpose' 并在 prompt 里写：`,
+            `  「find <pattern> in <path>，列出 file:line 与匹配上下文」`,
+            ``,
+            `这样能让 sub-agent 处理大量文件 IO，主线程上下文保持干净。`,
+        ].join('\n') + BYPASS_SUFFIX;
+    },
+};
+const RULE_BASH_FIND_SOURCE = {
+    id: 'bash-find-source',
+    kind: 'tool_intercept',
+    description: 'Bash find 源码文件应 spawn Explore agent',
+    claudemdRef: 'CLAUDE.md:112 强制 spawn 的场景 → 查/找/看/列出',
+    tool: 'Bash',
+    decision: 'deny',
+    match: (input, ctx) => {
+        const cmd = (input.command ?? '').trim();
+        if (!cmd)
+            return false;
+        if (!/\bfind\b/.test(cmd))
+            return false;
+        if (ctx.recent_agent_spawn)
+            return false;
+        // P1-4 fix (2026-05-27): whitelist build artifacts / 3rd-party deps /
+        // test fixtures / scratch dirs — scanning these is operational (rg dist
+        // for stale builds, find node_modules for orphan vendor files, etc.),
+        // not source-code exploration.
+        if (/\b(dist|node_modules|tests?|tmp|build|\.next|coverage|test-results)\b/.test(cmd)) {
+            return false;
+        }
+        // Look for -name "*.ext" with a code/text extension.
+        // Cover common source extensions; intentionally NOT exhaustive.
+        return /-name\s+["']?\*\.(ts|tsx|js|jsx|mjs|cjs|py|rs|go|java|kt|swift|c|cc|cpp|h|hpp|rb|php|sh|md|json|yaml|yml|toml)['"]?/.test(cmd);
+    },
+    hint: (input) => {
+        const cmd = (input.command ?? '').slice(0, 120);
+        return [
+            `find ... -name "*.ext" 跨源码搜索属于探索任务（CLAUDE.md:104）。`,
+            `命令：${cmd}`,
+            ``,
+            `请改用 Task tool spawn subagent_type='general-purpose'，在 prompt 里写：`,
+            `  「locate files matching <pattern> in <path>」`,
+        ].join('\n') + BYPASS_SUFFIX;
+    },
+};
+const RULE_EDIT_MULTI_FILE_HARD = {
+    id: 'edit-multi-file-hard',
+    kind: 'tool_intercept',
+    description: '同 session ≥3 文件 Edit/Write 必须 spawn agent',
+    claudemdRef: 'CLAUDE.md:8 自检 #1 修改 ≥2 个文件应 spawn Agent；硬阈值 3',
+    tool: 'Edit',
+    decision: 'deny',
+    match: (input, ctx) => {
+        if (ctx.recent_agent_spawn)
+            return false;
+        // Audit #4 fix (2026-06-09): agent-depth exemption. Claude Code sub-agents
+        // SHARE the main thread's session_id, so a spawned `coder` editing 3+ files
+        // (its legitimate job) trips this session-level threshold even though the
+        // main thread never touched a file. When ≥1 sub-agent is in-flight
+        // (active_agent_depth ≥ 1), the multi-file work is the authorized agent's —
+        // exempt it. This is a RELAXATION of a known false positive (all 6 audited
+        // deny rows were this class), NOT a new hard constraint.
+        if ((ctx.active_agent_depth ?? 0) >= 1)
+            return false;
+        const currentFile = (input.file_path ?? '').trim();
+        // P0-1 fix (2026-05-27): drop files edited BEFORE the most recent agent
+        // spawn — those are sub-agent edits, not main-thread accumulation. Only
+        // count files the main thread has touched POST-spawn (plus the current
+        // file). When `last_spawn_ts` is null OR the timestamped data is missing,
+        // fall back to the legacy behaviour (count the whole `edited_files` set).
+        let postSpawnFiles;
+        if (ctx.last_spawn_ts && ctx.edited_files_with_ts && ctx.edited_files_with_ts.length > 0) {
+            postSpawnFiles = new Set();
+            for (const { path, ts } of ctx.edited_files_with_ts) {
+                if (ts > ctx.last_spawn_ts)
+                    postSpawnFiles.add(path);
+            }
+        }
+        else {
+            postSpawnFiles = new Set(ctx.edited_files);
+        }
+        // The handler computes edited_files BEFORE evaluating rules; the current
+        // event has not yet been logged. We count distinct files INCLUDING the
+        // current one to trigger at "this would become the 3rd distinct file".
+        if (currentFile)
+            postSpawnFiles.add(currentFile);
+        return postSpawnFiles.size >= 3;
+    },
+    hint: (input, ctx) => {
+        const cnt = ctx.edited_files.size + ((input.file_path && !ctx.edited_files.has(input.file_path)) ? 1 : 0);
+        return [
+            `本 session 已经触及 ${cnt} 个文件（硬阈值 3）。CLAUDE.md:13 「自检 #1」要求 spawn agent。`,
+            ``,
+            `请改用 Task tool spawn subagent_type='general-purpose' 或更专门的 coder / safety-net-implementer，把后续改动委托给 sub-agent；主线程只协调与汇总。`,
+        ].join('\n') + BYPASS_SUFFIX;
+    },
+};
+// Edit 与 Write 共用阈值规则 — 用同一个 match/hint，仅 tool 字段不同。
+const RULE_WRITE_MULTI_FILE_HARD = {
+    ...RULE_EDIT_MULTI_FILE_HARD,
+    id: 'write-multi-file-hard',
+    tool: 'Write',
+};
+const RULE_BASH_GIT_LOG_DIFF_NO_FILE = {
+    id: 'bash-git-log-diff-no-file',
+    kind: 'tool_intercept',
+    description: 'git log / git diff 未限定文件多半为探索查询',
+    claudemdRef: 'CLAUDE.md:112 强制 spawn 的场景 (D1 策略升级 warn → deny)',
+    tool: 'Bash',
+    decision: 'deny',
+    match: (input, ctx) => {
+        const cmd = (input.command ?? '').trim();
+        if (!cmd)
+            return false;
+        // Only match git log / git diff (not git status / git show etc.).
+        if (!/\bgit\s+(log|diff)\b/.test(cmd))
+            return false;
+        if (ctx.recent_agent_spawn)
+            return false;
+        // P0-3 fix (2026-05-27): bypass structured workflow forms that
+        // CLAUDE.md itself requires (commit-mimic `git log --oneline -N`,
+        // PR-review `git diff --stat`, etc.). See `isGitLogDiffWorkflowForm`.
+        if (isGitLogDiffWorkflowForm(cmd))
+            return false;
+        const tokens = splitCommand(cmd);
+        return !gitHasFileSelector(tokens);
+    },
+    hint: (input) => {
+        const cmd = (input.command ?? '').slice(0, 120);
+        return [
+            `git log / git diff 未带 \`-- <file>\` 限定，多半是探索性查询（CLAUDE.md:104）。`,
+            `命令：${cmd}`,
+            ``,
+            `请二选一：`,
+            `  1) spawn Explore agent: Task tool subagent_type='general-purpose' with prompt`,
+            `     「summarize recent commits / diffs in <path>」`,
+            `  2) 只是 commit 前 self-review → 加 \`-- <file>\` 限定到具体文件`,
+        ].join('\n') + BYPASS_SUFFIX;
+    },
+};
+const RULE_EDIT_HOOK_SCRIPT = {
+    id: 'edit-hook-script-from-main',
+    kind: 'tool_intercept',
+    description: 'src/hooks/*.sh 是 daemon 通信契约，主线程禁止直接 Edit/Write',
+    claudemdRef: 'CLAUDE.md:170 项目模块覆盖现状 hooks/*.sh 0 测试 必走 Hybrid',
+    tool: 'Edit',
+    decision: 'deny',
+    match: (input, ctx) => {
+        const fp = (input.file_path ?? '').trim();
+        if (!fp)
+            return false;
+        if (ctx.recent_agent_spawn)
+            return false;
+        return /(^|\/)src\/hooks\/[^/]+\.sh$/.test(fp);
+    },
+    hint: (input, ctx) => {
+        const fp = input.file_path ?? '';
+        const intentNote = isHookRepairIntent(ctx.recent_prompt)
+            ? '（已识别到 prompt 含 hook 协议修复意图 — 仍建议 spawn agent 以确保有 safety-net）'
+            : '';
+        return [
+            `${fp} 是 daemon ↔ Claude Code 的通信契约，主线程直接改极易引入协议错误。`,
+            ``,
+            `请 spawn Task tool subagent_type='general-purpose'（或 safety-net-implementer mode=hybrid-feature），在 prompt 里写：`,
+            `  「修改 ${fp}，需求：<...>；先跑 daemon roundtrip 验证再改」`,
+            intentNote,
+        ].filter(Boolean).join('\n') + BYPASS_SUFFIX;
+    },
+};
+const RULE_WRITE_HOOK_SCRIPT = {
+    ...RULE_EDIT_HOOK_SCRIPT,
+    id: 'write-hook-script-from-main',
+    tool: 'Write',
+};
+// ── Warn-level rule ────────────────────────────────────────────────────────
+const RULE_EDIT_MULTI_FILE_NO_AGENT = {
+    id: 'edit-multi-file-no-agent',
+    kind: 'tool_intercept',
+    description: '同 session ≥2 文件 Edit/Write 且无 Agent spawn → 建议 spawn',
+    claudemdRef: 'CLAUDE.md:8 自检 #1 软提醒（硬阈值 3 由 edit-multi-file-hard 处理）',
+    tool: 'Edit',
+    decision: 'warn',
+    match: (input, ctx) => {
+        if (ctx.recent_agent_spawn)
+            return false;
+        const projected = new Set(ctx.edited_files);
+        const fp = (input.file_path ?? '').trim();
+        if (fp)
+            projected.add(fp);
+        // 2-file: warn; ≥3: handed off to the hard rule (which has higher precedence
+        // because we list it BEFORE this one in `defaultRules`).
+        return projected.size === 2;
+    },
+    hint: (_input, ctx) => {
+        return [
+            `本 session 已修改 ${Math.max(2, ctx.edited_files.size + 1)} 个文件。`,
+            `CLAUDE.md:13 「自检 #1」建议 ≥2 文件改动 spawn Agent 委托；继续手改将在第 3 个文件被硬拦截。`,
+            ``,
+            `若继续手改是有意为之，可加 \`// forge:bypass=<原因>\` 注释。`,
+        ].join('\n');
+    },
+};
+const RULE_WRITE_MULTI_FILE_NO_AGENT = {
+    ...RULE_EDIT_MULTI_FILE_NO_AGENT,
+    id: 'write-multi-file-no-agent',
+    tool: 'Write',
+};
+// ── f47c2c90 (2026-06-17): inline single-file no-spawn warn ──────────────────
+//
+// Spec: docs/design/2026-06-17/1042-spec-inline-no-spawn-violation.md
+//
+// Covers the口径 blind spot: the main thread "should spawn but edits ONE file
+// inline" — the most common, quietest violation form, which trips NEITHER the
+// hard rule (≥3) NOR the no-agent rule (==2). This pair handles the ==1 segment
+// ONLY, so the three rules (1 / 2 / ≥3) are mutually exclusive and don't overlap.
+//
+// Fires (warn) when ALL hold:
+//   (0) flag `inline_edit_no_spawn.enabled` is ON (default OFF — gray rollout)
+//   (1) NO recent agent spawn in the 5-min window (main thread未委托)
+//   (2) active_agent_depth < 1 (no sub-agent in flight — not the agent's work)
+//   (3) file_path is non-empty AND not a meta-task file (whitelist)
+//   (4) projected.size === 1 (the ==1 segment)
+//
+// warn-level ONLY — NEVER deny (CLAUDE.md mechanical-block layer removed,
+// decision 7c924678; daemon only records, never hard-blocks the main thread).
+// Behind a +24h observation_until so even when the flag is flipped ON the rows
+// ride along as dry_run for the first 24h (dry_run is EXCLUDED by
+// collectViolations Source 3 — pure observation, no list pollution).
+const RULE_INLINE_EDIT_NO_SPAWN = {
+    id: 'inline-edit-no-spawn',
+    kind: 'tool_intercept',
+    description: '主线程单文件 inline Edit/Write 且无 agent spawn → 建议 spawn',
+    claudemdRef: 'CLAUDE.md DECISION HINT 协议契约 §3 实施 → spawn coder',
+    tool: 'Edit',
+    decision: 'warn',
+    // Gray-rollout observation window: deploy day +24h. Even with the flag ON,
+    // rows persist as dry_run until this instant (pure observation). Bumped by a
+    // future spec if needed.
+    observation_until: '2026-06-18T12:00:00Z',
+    match: (input, ctx) => {
+        // (0) flag gate — default OFF; when OFF, no row at all (mirrors
+        // question_default_bmad_enforce). 灰度关时连 dry_run 都不写。
+        if (!ctx.inline_edit_no_spawn_enabled)
+            return false;
+        // (1) recent agent spawn → main thread already delegated,放行.
+        if (ctx.recent_agent_spawn)
+            return false;
+        // (2) sub-agent in flight (depth≥1) → this is the agent's legitimate work.
+        if ((ctx.active_agent_depth ?? 0) >= 1)
+            return false;
+        // (3) meta-task whitelist /空 file_path →放行.
+        const fp = (input.file_path ?? '').trim();
+        if (!fp)
+            return false;
+        if (isMetaTaskFile(fp))
+            return false;
+        // (4) segment guard — this rule owns the ==1 case ONLY. 2 → no-agent (warn),
+        //     ≥3 → hard (deny). Three rules分段互斥, no overlap.
+        const projected = new Set(ctx.edited_files);
+        projected.add(fp);
+        return projected.size === 1;
+    },
+    hint: (input, _ctx) => {
+        const fp = (input.file_path ?? '<file>').trim() || '<file>';
+        return [
+            `本 session 主线程正在 inline 改动 ${fp}，且最近 5min 无 agent spawn。`,
+            `CLAUDE.md DECISION HINT §3：实质改动应 spawn coder / safety-net-implementer，`,
+            `主线程只编排。`,
+            ``,
+            `若这是元任务（改 CLAUDE.md / changelog / 版本 / 文档）或确为有意 inline，`,
+            `可加 \`// forge:bypass=<原因>\` 注释忽略本提示。`,
+        ].join('\n');
+    },
+};
+const RULE_INLINE_WRITE_NO_SPAWN = {
+    ...RULE_INLINE_EDIT_NO_SPAWN,
+    id: 'inline-write-no-spawn',
+    tool: 'Write',
+};
+// ── Retired: RULE_TASK_WORKFLOW_MISMATCH (Phase 5 / D4) ──────────────────
+// Removed 2026-06-10 (decision fe6f98cd). Producers of the
+// `workflow_recommendations` table were deleted with spec 1200 (2026-05-28),
+// so the pending-row lookup always returned null and the rule never fired.
+// ── v9.x Phase 2 (2026-05-26): user-question default BMAD gate ────────────
+//
+// Spec: docs/design/2026-05-26/1707-user-question-default-bmad-spec.md
+//
+// Fires when:
+//   • tool = Task
+//   • subagent_type ∈ implementation agents (coder / harness-* / hybrid /
+//     safety-net-implementer) — NOT planner / Explore / doc-reviewer / verify
+//   • ctx.recent_prompt is question-style (see isQuestionPrompt)
+//   • prompt does NOT contain DIRECT_FIX_OVERRIDE escape hatch
+//   • feature flag `question_default_bmad.enforce` is true (default false
+//     during 7-day dry_run starting 2026-05-26 → reassess 2026-06-02)
+//   • we are not already inside a sub-agent spawn (recent_agent_spawn=false)
+//
+// Hint guides user to either re-spawn as `planner` or add `直接修` (natural
+// language) or `forge:bypass=...` (token) to skip the gate. The deny row in
+// `tool_intercepts` is tagged `rule_id='task-question-needs-bmad'` so the C4
+// KPI can split obey ratio per-rule.
+const IMPL_AGENT_TYPES = new Set([
+    'coder',
+    'safety-net-implementer',
+    'harness-debug-full',
+    // Legacy names retained read-only (R2 merge, decision 7c881393): the three
+    // agents below were merged into safety-net-implementer. Stale spawns using
+    // the old names should still trip this question-gate.
+    'harness-hotfix',
+    'hybrid-feature-with-safety',
+    'refactor-specialist',
+]);
+const RULE_TASK_QUESTION_NEEDS_BMAD = {
+    id: 'task-question-needs-bmad',
+    kind: 'tool_intercept',
+    description: '用户疑问句 spawn 实现 agent — 应先走 BMAD spec gate',
+    // External docs ref — Phase 9 lint skips non-CLAUDE.md refs, but the link
+    // is still discoverable in code search.
+    claudemdRef: 'docs/design/2026-05-26/1707-user-question-default-bmad-spec.md',
+    tool: 'Task',
+    decision: 'deny',
+    match: (input, ctx) => {
+        // Feature-flag gate — dry_run by default; only fires when explicitly
+        // opted in via `cf config set question_default_bmad.enforce true`.
+        if (!ctx.question_default_bmad_enforce)
+            return false;
+        // Sub-agent context relaxation — we're already inside a spawn flow.
+        if (ctx.recent_agent_spawn)
+            return false;
+        const sub = typeof input.subagent_type === 'string' ? input.subagent_type : '';
+        if (!IMPL_AGENT_TYPES.has(sub))
+            return false;
+        const prompt = ctx.recent_prompt ?? '';
+        if (!isQuestionPrompt(prompt))
+            return false;
+        // Escape hatch — natural-language override.
+        if (hasDirectFixOverride(prompt))
+            return false;
+        return true;
+    },
+    hint: (input, _ctx) => {
+        const sub = typeof input.subagent_type === 'string' ? input.subagent_type : '<missing>';
+        return [
+            `检测到最近一条 user prompt 是疑问句，但你 spawn 了 '${sub}'（实现/修复类 agent）。`,
+            `CLAUDE.md 自检 #0 + spec docs/design/2026-05-26/1707-user-question-default-bmad-spec.md`,
+            `要求：用户疑问句默认先走 BMAD — spawn 'planner' 出 spec → 等用户批准 → 才进入实现。`,
+            ``,
+            `请三选一：`,
+            `  1) 重新 spawn Task subagent_type='planner'，按 BMAD 走 spec → 用户审批 → 实现`,
+            `  2) 在用户 prompt 里加 "直接修" / "just fix" / "skip spec" — 自然语言逃逸 (R7 边界锚定)`,
+            `  3) 在 Task description / prompt 末尾追加 \`# forge:bypass=<原因>\` token`,
+        ].join('\n') + BYPASS_SUFFIX;
+    },
+};
+// ── v9.x 8-in-1 Phase C (2026-05-27): general-purpose misuse gate ────────
+//
+// Spec: docs/design/2026-05-27/1006-intercept-enforcement-fix-spec.md §C step 11
+//
+// Fires when:
+//   • tool = Task
+//   • subagent_type === 'general-purpose'
+//   • last user prompt scores ≥2 hits against one of the IMPL workflow buckets
+//     (harness-hotfix / harness-debug / refactor / hybrid)
+//   • prompt does NOT contain the escape hatch ("general-purpose" mention /
+//     "用 general" / forge:bypass=)
+//   • we are not already inside a sub-agent spawn (recent_agent_spawn=false)
+//
+// Lives behind a 24h `observation_until` window — see SPEC § R-5 (24h dry_run
+// before hard deny). Lets us measure misuse rate without breaking legitimate
+// general-purpose calls (Explore-style 文件 IO).
+const IMPL_BUCKET_TYPES = new Set([
+    'harness-hotfix',
+    'harness-debug',
+    'refactor',
+    'hybrid',
+]);
+const MISUSE_MIN_BUCKET_HITS = 2;
+// Escape hatch — boundary-anchored mention of the literal "general-purpose"
+// agent name, or natural-language "用 general" / "use general" phrasing.
+const MISUSE_ESCAPE_PATTERN = /(\bgeneral[-_ ]purpose\b|用\s*general|use\s+general|forge:bypass=)/i;
+// 24h observation window: today + 24h. Hard-coded ISO to keep the rule
+// deterministic across daemon restarts; bumped by a future spec if needed.
+const MISUSE_OBSERVATION_UNTIL = '2026-05-28T02:30:00Z';
+/** Default agent recommendation per IMPL bucket — surfaced in the hint. */
+const MISUSE_BUCKET_AGENT_HINT = Object.freeze({
+    // R2 merge (decision 7c881393): hotfix / refactor / hybrid buckets all
+    // route to safety-net-implementer; the bucket name doubles as the mode hint.
+    'harness-hotfix': 'safety-net-implementer',
+    'harness-debug': 'harness-debug-full',
+    'refactor': 'safety-net-implementer',
+    'hybrid': 'safety-net-implementer',
+});
+const RULE_TASK_SPAWN_GENERAL_PURPOSE_MISUSE = {
+    id: 'task-spawn-general-purpose-misuse',
+    kind: 'tool_intercept',
+    description: 'Task spawn general-purpose 但任务匹配专门 agent — 应改用 specialist',
+    claudemdRef: 'docs/architecture/governance.md §6 可用 subagent_type 清单 + 自查触发条件',
+    tool: 'Task',
+    decision: 'deny',
+    observation_until: MISUSE_OBSERVATION_UNTIL,
+    match: (input, ctx) => {
+        const sub = typeof input.subagent_type === 'string' ? input.subagent_type : '';
+        if (sub !== 'general-purpose')
+            return false;
+        if (ctx.recent_agent_spawn)
+            return false;
+        const prompt = ctx.recent_prompt ?? '';
+        if (!prompt)
+            return false;
+        // Escape hatch — user explicitly asked for general-purpose or used the
+        // bypass token.
+        if (MISUSE_ESCAPE_PATTERN.test(prompt))
+            return false;
+        const scored = scoreKeywordBuckets(prompt);
+        if (!scored)
+            return false;
+        if (!IMPL_BUCKET_TYPES.has(scored.workflow_type))
+            return false;
+        if (scored.matched.length < MISUSE_MIN_BUCKET_HITS)
+            return false;
+        return true;
+    },
+    hint: (_input, ctx) => {
+        const prompt = ctx.recent_prompt ?? '';
+        const scored = scoreKeywordBuckets(prompt);
+        const bucket = scored?.workflow_type ?? '(未识别)';
+        const recommended = MISUSE_BUCKET_AGENT_HINT[bucket] ?? '(对应 specialist)';
+        const matchedList = scored?.matched.join(', ') ?? '(无)';
+        return [
+            `检测到你 spawn 了 'general-purpose'，但 prompt 匹配 '${bucket}' 工作流`,
+            `（命中关键词：${matchedList}）。`,
+            ``,
+            `CLAUDE.md L175-197「可用 subagent_type 清单」要求：`,
+            `  ${bucket} 类任务 → spawn '${recommended}'（自带 safety-net / spec-gate / verify-gate）。`,
+            ``,
+            `general-purpose 是兜底，专门 agent 的工作流约束在 general-purpose 下不生效。`,
+            ``,
+            `请二选一：`,
+            `  1) 重新调 Task tool subagent_type='${recommended}'`,
+            `  2) 如确认要用 general-purpose（如批量文件 IO），在 prompt 里加 "用 general" 或追加 \`# forge:bypass=<原因>\``,
+        ].join('\n') + BYPASS_SUFFIX;
+    },
+};
+// ── Registry export ────────────────────────────────────────────────────────
+/**
+ * Order matters: PreToolUseHandler matches the FIRST rule that fires.
+ * Put `deny` rules before `warn` rules so a 3-file Edit is denied (not warned).
+ */
+export const defaultRules = [
+    // Bash deny rules
+    RULE_BASH_GREP_MULTI_FILE,
+    RULE_BASH_FIND_SOURCE,
+    RULE_BASH_GIT_LOG_DIFF_NO_FILE,
+    // Edit/Write hook protection (deny)
+    RULE_EDIT_HOOK_SCRIPT,
+    RULE_WRITE_HOOK_SCRIPT,
+    // Edit/Write hard threshold (deny)
+    RULE_EDIT_MULTI_FILE_HARD,
+    RULE_WRITE_MULTI_FILE_HARD,
+    // 8-in-1 Phase C (2026-05-27): general-purpose misuse gate (deny, 24h
+    // observation window) — the keyword-bucket fallback gate for Task spawns.
+    RULE_TASK_SPAWN_GENERAL_PURPOSE_MISUSE,
+    // v9.x Phase 2 (2026-05-26): user-question default BMAD gate (deny).
+    RULE_TASK_QUESTION_NEEDS_BMAD,
+    // Edit/Write soft threshold (warn) — must come AFTER the hard variant.
+    RULE_EDIT_MULTI_FILE_NO_AGENT,
+    RULE_WRITE_MULTI_FILE_NO_AGENT,
+    // f47c2c90 (2026-06-17): inline single-file no-spawn (warn) — LAST / weakest.
+    // Only fires on the ==1 segment, mutually exclusive with the ==2 no-agent and
+    // ≥3 hard rules above, so registry findFirstMatch ordering is safe.
+    RULE_INLINE_EDIT_NO_SPAWN,
+    RULE_INLINE_WRITE_NO_SPAWN,
+];
+//# sourceMappingURL=defaults.js.map