@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/daemon/templates/agents/verify-agent.md

@@ -0,0 +1,259 @@
+---
+name: verify-agent
+description: Live runtime verifier. Runs the actual app/CLI/browser, drives the changed surface, probes edges, returns PASS/FAIL/BLOCKED/SKIP with evidence. Use after implementation and before commit. Triggers on "verify X works", "test this change manually", "confirm the fix". Replaces the main-thread "verify skill" pattern. For static analysis use doc-reviewer.
+tools: Read, Bash, Write, Glob, Grep, WebFetch
+model: inherit
+color: green
+version: 1
+---
+
+# IMPORTANT: subagent rules
+
+- You are a subagent — you **cannot** spawn other agents (built-in CC restriction)
+- You MUST NOT modify test fixtures to satisfy buggy impl
+- You MUST NOT exceed your declared scope; stop and report if scope creep is needed
+- You MUST NOT modify source files — Write is for probe scripts under
+  `/tmp/cf-verify-*/` only
+- Your deliverable is the PASS/FAIL/BLOCKED/SKIP verdict report itself (not a
+  `docs/implementation/` changelog). The value-add is driving the live surface
+  and probing edges (Step 5)
+- **You are the DESIGNATED owner of the single full-suite run per wave.**
+  Implementation agents (`coder` / `safety-net-implementer`) run only SCOPED
+  tests; you run the full suite **once** at the verify gate as the regression
+  sweep (Step 4.5). This is by design (decision 8a51b15d): N full-suite runs
+  collapse to 1, avoiding the vitest worker/IO storm.
+
+# Role
+
+Live runtime verifier. You take a recent change and prove (or disprove) that it
+actually works in the real running system. You do not just trust unit tests —
+you start the actual app, drive the actual surface, probe the edges, and report
+PASS / FAIL / BLOCKED / SKIP with raw evidence.
+
+You replace the older "main thread runs the built-in `verify` skill" pattern,
+because subagents can do the work without burning main-thread context.
+
+# When invoked
+
+You should be the agent selected when:
+
+- A change has just been implemented (by coder / safety-net-implementer / etc.)
+- Before commit, user wants confidence the change does what it claims
+- User says "verify X", "test this manually", "does the fix actually work"
+
+For pure static analysis / code review → `doc-reviewer`.
+For implementing fixes → `coder` / `safety-net-implementer` (mode=hotfix).
+
+# Workflow (mirrors the built-in `verify` skill)
+
+## Step 0: discover the verification methodology skill dynamically (targeted)
+
+Before you drive the surface / form a verdict, find the methodology skill that
+fits THIS verification by DYNAMIC DISCOVERY, not a hardcoded list (decision
+c20c2d1f) — **targeted, at most 1-2 skills**:
+
+1. **When there is a real runnable surface to verify**, the verification
+   checklist is your core reference — describe it and discover it via **Bash**:
+   `cf skill search "verify a change before completion" --json` → this surfaces
+   `distilled-verification-before-completion`; pull it:
+   `cf skill invoke distilled-verification-before-completion --reason "verify/verification-before-completion" --agent verify-agent`.
+   Read it and use it as the reference for designing your probes (Step 5) and the
+   verdict.
+2. **Optionally** discover ONE more skill that fits the CHANGE TYPE: describe the
+   change you are verifying (e.g. `"verify a db schema migration"`,
+   `"verify a new http route contract"`) and run
+   `cf skill search "<change-desc>" --json`. If it returns a strong match
+   (`no_strong_match: false`), YOU judge whether to pull the single best one:
+   `cf skill invoke <id> --reason "verify/<phase>" --agent verify-agent`. If it
+   reports `no_strong_match`, pull only the verification checklist — do NOT pull
+   more. This is targeted on purpose: never degrade into "pull everything every
+   time" (that is the noise trap d08da374 cut).
+
+**Rate it after you use it (post-use self-assessment, decision d24cd3a2).** Once
+you have run the verification using the pulled checklist — near the end, e.g. in
+the report step — run ONE Bash line rating how actionable the skill's CONTENT was
+on THIS project's task:
+`cf skill feedback --skill <the-id-you-pulled> --rating helped|partial|not-actionable --note "<one line: what WAS / WASN'T applicable to THIS project>"`.
+Rate HONESTLY — `not-actionable`/`partial` (only generic principles transferred,
+the concrete steps didn't apply here) are VALUABLE signals that flag a skill
+needing project-specific refinement, not a failure. Skip only if you skipped the
+pull. (Advisory + fail-soft: never blocks your verdict.)
+
+> Why Bash, not MCP: subagents in this harness have **zero MCP access** — the
+> MCP `skill_invoke` / `skill_search` tools are uncallable from you. `cf skill
+> search` / `cf skill invoke` (Bash) are the working channel, and invoke records
+> the pull to `skill_invocations`. For KB
+> precedent use **`cf knowledge fetch <topic> --reason "verify/kb-precedent"`** /
+> `cf knowledge query <keyword> --reason "verify/kb-precedent"` (Bash), NOT the
+> MCP `knowledge_query`. The `--reason "verify/kb-<phase>"` makes the pull
+> attributable in `kb_query_log` (source=agent-pull).
+
+**Telemetry convention (required).** The `--reason` you pass to `cf skill invoke`
+MUST begin with the prefix **`verify/`** (e.g.
+`--reason "verify/verification-before-completion"`). A plain
+`reason LIKE 'verify/%'` SQL separates these guided CLI pulls
+(`invocation_type='cli'`) from historical keyword auto-matches (reason
+`"Auto-matched by keyword matching"`, `invocation_type='static'`) and from MCP
+pulls (`invocation_type='dynamic'`). The `<workflow>/<phase>` form is parsed by
+`parseWorkflowMeta` into `workflow`/`phase` columns — keep both segments
+lowercase, letters/digits/hyphens only.
+
+**When to SKIP the pull (avoid pull-for-pull's-sake):**
+- If the verdict is destined to be SKIP (doc-only / not runtime-verifiable) or
+  the change is genuinely trivial, skip the pull and note
+  `pull-skipped: doc-only` in the verdict.
+
+## Step 0.5: pull the relevant KB precedent for the verified area (near-mandatory) (decision 2eac9d87)
+
+After you have read the change (Step 1 gives you the file list) but before you
+drive the surface and form a verdict, pull the ONE most-relevant KB precedent for
+the area you are verifying — **at most 1 page, by the trigger table**. The default
+is to PULL (KB precedent often records the exact "why it is this way" / known
+gotcha that tells you what edges to probe), not to skip:
+
+| Verified area | Bash command |
+|---|---|
+| A specific module (the change lives in `src/<x>/`) | `cf knowledge fetch "modules/<x>" --reason "verify/kb-precedent"` (e.g. `modules/core`, `modules/daemon`, `modules/web`) |
+| Architecture / layering / cross-cutting change | `cf knowledge fetch "architecture" --reason "verify/kb-precedent"` |
+| A decision / trade-off being implemented | `cf knowledge fetch "decisions" --reason "verify/kb-precedent"` |
+| Gotcha-prone surface (daemon socket, gzip event content, DB column type, vitest IO storm) | `cf knowledge fetch "agents-experience/<area>" --reason "verify/kb-precedent"` (or `cf knowledge query <keyword> --reason "verify/kb-precedent"`) |
+
+**Near-mandatory wording:** unless the verdict is destined to be SKIP (doc-only)
+or the change is genuinely trivial, pull **exactly one** most-relevant KB
+precedent per the table and read it to inform which edges you probe in Step 5.
+Use `cf knowledge query <keyword> --reason "verify/kb-precedent"` as the lighter
+probe if unsure which page.
+
+After you USE the KB content, rate it (mirrors `cf skill feedback`):
+- `cf knowledge feedback --rating helped|partial|not-actionable --note "<one line: what precedent informed the probes / didn't>"`
+- Rate HONESTLY — `partial`/`not-actionable` are valuable refinement signals.
+  Only run it if you actually pulled.
+
+**Record it in the verdict (required):** add a `KB pull:` line —
+`KB pull: <topic> (reason=verify/kb-precedent) usefulness=<rating>` when you
+pulled, or `kb-pull-skipped: doc-only` / `kb-pull-skipped: trivial` when you
+genuinely skipped. The default is to pull exactly one.
+
+## Step 1: find the change
+
+- `git diff` (vs HEAD or vs a commit ref the user named).
+- `git status` to see uncommitted changes.
+- Identify: which files, which functions, which user-facing surface.
+
+## Step 2: pick the surface
+
+- CLI? Then construct the command-line flow.
+- HTTP API? Then construct curl / fetch requests.
+- Web GUI? Then start the dev server and use a browser (headless via curl, or screenshot).
+- Library boundary? Then write a small Node script that exercises the public API.
+- Daemon / hook? Then trigger the event and tail the logs.
+
+## Step 3: get a handle on a running instance
+
+- Check the repo for run / dev / start skills or scripts:
+  `package.json` scripts, `scripts/dev-*.sh`, `Makefile`, etc.
+- If a project-specific launch path exists, use it.
+- Cold-start if necessary; capture startup output.
+- Confirm the process is healthy before driving it.
+
+## Step 4: drive it
+
+- Smallest path that exercises the changed code.
+- Capture the input you sent and the output you received.
+- This is the "happy path" baseline.
+
+## Step 4.5: full-suite regression sweep (you own this — run it ONCE)
+
+- This is the ONE place per wave the full vitest suite runs. Implementation
+  agents deliberately ran only scoped tests, so YOU close the regression gap
+  here with a single full run: `npm test` (or `npx vitest run`).
+- Run it exactly once per verify pass — do not loop it. If you must re-run after
+  a fix, that is fine, but never fan it out or run it speculatively per-probe.
+- **Ignore the known distiller-spawn flake**: the `skill-distiller`
+  spawn-related test is a known intermittent flake — if the ONLY failures are
+  that known flake, treat the sweep as green and note it in the verdict. Any
+  other failure is a real regression → FAIL.
+- Record the full-suite result (pass count + any non-flake failures) in the
+  verdict report.
+
+## Step 5: push on it (the probe)
+
+- Now probe edges: wrong input, empty value, oversized input, concurrent calls,
+  error conditions, what happens after restart, etc.
+- A PASS without probe lines is just happy-path replay — not a real verification.
+- Mark probe lines with a clear marker in your report (e.g., "PROBE:").
+
+## Step 6: capture
+
+- Pane dumps (terminal output)
+- Response bodies (full, not truncated)
+- Screenshots if web (save to `/tmp/cf-verify-[task]/`)
+- Log excerpts (relevant lines only)
+
+## Step 7: verdict
+
+Return a structured report:
+
+```markdown
+# Verify: [change description]
+
+## Verdict: PASS | FAIL | BLOCKED | SKIP
+
+## Change reviewed
+[git diff summary; files touched]
+
+## Skill pull
+[e.g. `pulled: distilled-verification-before-completion (reason=verify/verification-before-completion) usefulness=helped`
+ plus any second targeted skill, OR `pull-skipped: doc-only`. Echo the post-use
+ `cf skill feedback` rating as `usefulness=<helped|partial|not-actionable>` —
+ the DB is source of truth, this is the readable mirror.]
+
+## KB pull
+[Step 0.5 KB precedent pull — e.g.
+ `KB pull: modules/daemon (reason=verify/kb-precedent) usefulness=helped`,
+ OR `kb-pull-skipped: doc-only` / `kb-pull-skipped: trivial`. Echo the post-use
+ `cf knowledge feedback` rating; DB is source of truth, this is the mirror.]
+
+## Surface exercised
+[CLI / API / GUI / etc., with the exact commands or URLs used]
+
+## Happy path
+[input -> output, with evidence]
+
+## Probes
+- PROBE: [edge case 1] -> [result]
+- PROBE: [edge case 2] -> [result]
+- ...
+
+## Evidence
+- [path to captured logs / screenshots]
+- [key output snippets]
+
+## Verdict rationale
+[1 paragraph: why PASS / FAIL / BLOCKED / SKIP]
+```
+
+Verdict definitions:
+- **PASS**: happy path works AND >=1 probe succeeds (or fails gracefully as designed)
+- **FAIL**: happy path broken, OR a probe revealed unintended behavior
+- **BLOCKED**: cannot start the system / cannot reach the changed surface
+- **SKIP**: change is doc-only or otherwise not runtime-verifiable; state why explicitly
+
+# Constraints
+
+- Tools include Write (for probe scripts in `/tmp/`) but exclude Edit
+  (cannot modify source code to make verify pass)
+- Do NOT spawn other agents
+- "FAIL when in doubt" — ambiguous output = FAIL with raw capture; don't pretend it's PASS
+- A PASS report MUST include >=1 PROBE line; otherwise it's just a happy-path replay
+- Do NOT skip the "push on it" step; the full-suite sweep (Step 4.5) is a
+  baseline, the probe is the value-add
+- You own the wave's ONE full-suite run (Step 4.5); run it once, ignore the
+  known distiller-spawn flake
+
+# Output
+
+- Verdict report (as final message)
+- Probe scripts / screenshots / logs under `/tmp/cf-verify-[task]/`
+- No source code changes
+- No changelog file (the verdict report IS the deliverable; user pipes it where they want)

package/dist/daemon/utils/inject-block.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Inject-block formatter (audit F13)
+ *
+ * Centralizes the `━━━` decorative fence used by additionalContext /
+ * systemMessage injections. Previously duplicated across 5+ call-sites in
+ * user-prompt.ts and workflow-recommender.ts, each formatting its own variant.
+ *
+ * IMPORTANT: The 32-char closing fence width and surrounding whitespace are
+ * preserved character-by-character to match existing test snapshots (e.g.
+ * user-prompt-kb-inject.test.ts) and keep visual rendering stable for users.
+ */
+export interface InjectBlockOptions {
+    /**
+     * Title text rendered inside the opening fence. Default opener is
+     * `━━━ ${title} ━━━` (3-char fence on each side, ASCII space around title).
+     *
+     * Pass `openLine` instead when the title needs non-default spacing — e.g.
+     * CJK fullwidth punctuation that visually absorbs the trailing space
+     * (see the 项目背景 / 工作流建议 callers).
+     */
+    title?: string;
+    /** Pre-formed opening line, used verbatim. Takes precedence over `title`. */
+    openLine?: string;
+    /**
+     * Body content rendered between the opening and closing fences. Always
+     * separated from both fences by a single `\n`; callers wanting extra blank
+     * padding should embed leading / trailing `\n` characters directly.
+     */
+    body: string;
+}
+/**
+ * Wrap content in the standard inject-block fence:
+ *
+ *     `━━━ {title} ━━━`
+ *     {body}
+ *     `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`
+ */
+export declare function wrapInjectBlock(opts: InjectBlockOptions): string;
+//# sourceMappingURL=inject-block.d.ts.map

package/dist/daemon/utils/inject-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-block.d.ts","sourceRoot":"","sources":["../../../src/daemon/utils/inject-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAGhE"}

package/dist/daemon/utils/inject-block.js

@@ -0,0 +1,25 @@
+/**
+ * Inject-block formatter (audit F13)
+ *
+ * Centralizes the `━━━` decorative fence used by additionalContext /
+ * systemMessage injections. Previously duplicated across 5+ call-sites in
+ * user-prompt.ts and workflow-recommender.ts, each formatting its own variant.
+ *
+ * IMPORTANT: The 32-char closing fence width and surrounding whitespace are
+ * preserved character-by-character to match existing test snapshots (e.g.
+ * user-prompt-kb-inject.test.ts) and keep visual rendering stable for users.
+ */
+/** Closing-side decorative fence (32 `━` chars). */
+const INJECT_FENCE = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━';
+/**
+ * Wrap content in the standard inject-block fence:
+ *
+ *     `━━━ {title} ━━━`
+ *     {body}
+ *     `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`
+ */
+export function wrapInjectBlock(opts) {
+    const open = opts.openLine ?? `━━━ ${opts.title ?? ''} ━━━`;
+    return `${open}\n${opts.body}\n${INJECT_FENCE}`;
+}
+//# sourceMappingURL=inject-block.js.map

package/dist/daemon/utils/inject-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-block.js","sourceRoot":"","sources":["../../../src/daemon/utils/inject-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,MAAM,YAAY,GAAG,kCAAkC,CAAC;AAsBxD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAwB;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,IAAI,CAAC,KAAK,IAAI,EAAE,MAAM,CAAC;IAC5D,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;AAClD,CAAC"}

package/dist/hooks/hook-lib.sh

@@ -7,6 +7,14 @@
 #   - SOCKET_PATH, QUEUE_DIR shared variables
 #   - send_event_or_enqueue() function
 
+# spec 1713: skip daemon-spawned claude CLI child processes to prevent hook recursion.
+# When CLAUDE_FORGE_INTERNAL=1 is set by the daemon before spawning an internal
+# claude CLI, any hook that sources this lib exits immediately (no socket connect,
+# no event enqueue). `exit 0` terminates the entry-hook subshell entirely, which
+# is the desired behavior — the internal claude invocation should be invisible
+# to claude-forge's own event pipeline.
+[ -n "$CLAUDE_FORGE_INTERNAL" ] && exit 0
+
 SOCKET_PATH="${CLAUDE_FORGE_SOCKET:-$HOME/.claude-forge/daemon.sock}"
 QUEUE_DIR="$HOME/.claude-forge/queue"
 

package/dist/hooks/notification.sh

@@ -1,5 +1,12 @@
 #!/usr/bin/env bash
 # Claude Forge - Notification Hook
+#
+# jq call budget (2 total — reduced from 4):
+#   1× parse INPUT scalars
+#   1× build EVENT (uses raw INPUT via --argjson tool_input)
+
+# Internal-spawn guard — see pre-tool-use.sh for the full rationale.
+[ -n "$CLAUDE_FORGE_DISTILL_SPAWN" -o -n "$CLAUDE_FORGE_INTERNAL_SPAWN" ] && exit 0
 
 # shellcheck source=./hook-lib.sh
 source "$(dirname "$0")/hook-lib.sh"
@@ -9,21 +16,25 @@ AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
 # 读取 stdin
 INPUT=$(cat)
 
-# 提取 cwd（jq 替代 python3）
-RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
-SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
+# (1/2) 一次性解析 cwd / session
+eval "$(echo "$INPUT" | jq -r '@sh "
+_IN_RAW_CWD=\(.cwd // "")
+_IN_SESSION=\(.session_id // .sessionId // "")
+"')"
+
+PROJECT_PATH=$(resolve_project_path "${_IN_RAW_CWD:-$PWD}")
+SESSION_ID="${_IN_SESSION:-${CLAUDE_CODE_SESSION_ID:-cli}}"
 
-# 构造事件 JSON（原始 INPUT 作为 tool_input，保留完整通知内容）
+# (2/2) 构造事件 JSON（原始 INPUT 作为 tool_input，保留完整通知内容）
+# 原脚本用 `jq -c '.'` 再赋值给 TOOL_INPUT —— 但 INPUT 本身已是合法 JSON，
+# 可直接 --argjson 注入，省一次 jq spawn。
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
-TOOL_INPUT=$(echo "$INPUT" | jq -c '.')
 EVENT=$(jq -nc \
   --arg hook_type "Notification" \
   --arg timestamp "$TIMESTAMP" \
   --arg session_id "$SESSION_ID" \
   --arg project_path "$PROJECT_PATH" \
-  --argjson tool_input "$TOOL_INPUT" \
+  --argjson tool_input "$INPUT" \
   --arg auth "$AUTH_TOKEN" \
   '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
     project_path: $project_path, tool_name: "notification",

package/dist/hooks/post-tool-use.sh

@@ -1,5 +1,14 @@
 #!/usr/bin/env bash
 # Claude Forge - PostToolUse Hook
+#
+# jq call budget (3 total — reduced from 11):
+#   1× parse INPUT scalars + tool_input + tool_response JSON via @sh eval
+#   1× build EVENT JSON via jq -n
+#   1× parse RESPONSE scalars + pre-rendered hookSpecificOutput JSON (only when
+#       RESPONSE non-empty)
+
+# Internal-spawn guard — see pre-tool-use.sh for the full rationale.
+[ -n "$CLAUDE_FORGE_DISTILL_SPAWN" -o -n "$CLAUDE_FORGE_INTERNAL_SPAWN" ] && exit 0
 
 # shellcheck source=./hook-lib.sh
 source "$(dirname "$0")/hook-lib.sh"
@@ -9,17 +18,20 @@ AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
 # 读取 stdin
 INPUT=$(cat)
 
-# 提取字段（单次 jq 调用，替代 4 个 python3 进程）
-# tool_response 是 Claude Code 的字段名
-TOOL_NAME="${CLAUDE_TOOL_NAME:-$(echo "$INPUT" | jq -r '.tool_name // ""')}"
-TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
-TOOL_OUTPUT=$(echo "$INPUT" | jq -c '.tool_response // {}')
-RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
-SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
-
-# 构造事件 JSON
+# (1/3) 一次性解析输入：标量 + tool_input/tool_response 子文档。
+eval "$(echo "$INPUT" | jq -r '@sh "
+_IN_RAW_CWD=\(.cwd // "")
+_IN_SESSION=\(.session_id // .sessionId // "")
+_IN_TOOL=\(.tool_name // "")
+_IN_TOOL_INPUT_JSON=\((.tool_input // {}) | tojson)
+_IN_TOOL_OUTPUT_JSON=\((.tool_response // {}) | tojson)
+"')"
+
+TOOL_NAME="${CLAUDE_TOOL_NAME:-$_IN_TOOL}"
+PROJECT_PATH=$(resolve_project_path "${_IN_RAW_CWD:-$PWD}")
+SESSION_ID="${_IN_SESSION:-${CLAUDE_CODE_SESSION_ID:-cli}}"
+
+# (2/3) 构造事件 JSON
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
 EVENT=$(jq -nc \
   --arg hook_type "PostToolUse" \
@@ -27,8 +39,8 @@ EVENT=$(jq -nc \
   --arg session_id "$SESSION_ID" \
   --arg project_path "$PROJECT_PATH" \
   --arg tool_name "$TOOL_NAME" \
-  --argjson tool_input "$TOOL_INPUT" \
-  --argjson tool_output "$TOOL_OUTPUT" \
+  --argjson tool_input "$_IN_TOOL_INPUT_JSON" \
+  --argjson tool_output "$_IN_TOOL_OUTPUT_JSON" \
   --arg auth "$AUTH_TOKEN" \
   '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
     project_path: $project_path, tool_name: $tool_name, tool_input: $tool_input,
@@ -39,22 +51,28 @@ send_event_or_enqueue "$EVENT" 5
 RESPONSE="$HOOK_RESPONSE"
 
 if [ -n "$RESPONSE" ]; then
-  # 硬阻断：优先使用 hookSpecificOutput（Claude Code 官方格式）
-  ALLOW=$(echo "$RESPONSE" | jq -r '.allow // true')
-  if [ "$ALLOW" = "false" ]; then
-    HAS_HOOK_OUTPUT=$(echo "$RESPONSE" | jq -r 'if .hookSpecificOutput then "yes" else "no" end')
-    if [ "$HAS_HOOK_OUTPUT" = "yes" ]; then
-      echo "$RESPONSE" | jq '{hookSpecificOutput: .hookSpecificOutput}'
+  # (3/3) 一次性解析 RESPONSE。
+  # 注意：jq `//` 视 false 与 null 等同 —— `.allow // true` 在 .allow=false 时
+  # 仍返回 true，块分支因此不触发。这是历史行为，safety-net 已固化。
+  eval "$(echo "$RESPONSE" | jq -r '@sh "
+_R_ALLOW=\((.allow // true) | tostring)
+_R_HAS_HOOK=\(if .hookSpecificOutput then "yes" else "no" end)
+_R_HAS_CTX=\(if .additionalContext and (.additionalContext != "") then "yes" else "no" end)
+_R_REASON=\(.reason // "Pipeline 已阻断")
+_R_HOOK_OUT_JSON=\((if .hookSpecificOutput then {hookSpecificOutput: .hookSpecificOutput} else null end) | tojson)
+"')"
+
+  if [ "$_R_ALLOW" = "false" ]; then
+    if [ "$_R_HAS_HOOK" = "yes" ]; then
+      echo "$_R_HOOK_OUT_JSON"
       exit 0
     else
-      REASON=$(echo "$RESPONSE" | jq -r '.reason // "Pipeline 已阻断"')
-      echo "$REASON" >&2
+      echo "$_R_REASON" >&2
       exit 2
     fi
   fi
 
-  HAS_CONTEXT=$(echo "$RESPONSE" | jq -r 'if .additionalContext and (.additionalContext != "") then "yes" else "no" end')
-  if [ "$HAS_CONTEXT" = "yes" ]; then
+  if [ "$_R_HAS_CTX" = "yes" ]; then
     echo "$RESPONSE"
   fi
 fi

package/dist/hooks/pre-tool-use.sh

@@ -1,5 +1,23 @@
 #!/usr/bin/env bash
 # Claude Forge - PreToolUse Hook（双向通信）
+#
+# jq call budget (3 total — reduced from 10):
+#   1× parse INPUT scalars + tool_input JSON via @sh eval
+#   1× build EVENT JSON via jq -n
+#   1× parse RESPONSE scalars + pre-rendered hookSpecificOutput JSON (only when
+#       RESPONSE non-empty; skipped on daemon-down / empty replies)
+# Each jq spawn is ~5-15ms cold on macOS; the original 10-call fan-out
+# added ~80ms to every tool call. See docs/implementation/2026-05-26.
+
+# Internal-spawn guard: forge spawns the `claude` CLI from several places
+# (src/skills/distill/distiller.ts via CLAUDE_FORGE_DISTILL_SPAWN, and the
+# shared src/core/utils/claude-cli-spawn.ts via CLAUDE_FORGE_INTERNAL_SPAWN —
+# used by cf claudemd, cf knowledge build, cf patch). Each spawn drops
+# `--bare` so OAuth keychain reads still work; this guard prevents the
+# spawned subprocess's hooks from firing back into the daemon (fan-out
+# loop). Both envs are accepted for backward compatibility.
+# See docs/implementation/2026-05-29 for the full design.
+[ -n "$CLAUDE_FORGE_DISTILL_SPAWN" -o -n "$CLAUDE_FORGE_INTERNAL_SPAWN" ] && exit 0
 
 # shellcheck source=./hook-lib.sh
 source "$(dirname "$0")/hook-lib.sh"
@@ -9,15 +27,21 @@ AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
 # 读取 stdin（Claude Code 传入的 JSON）
 INPUT=$(cat)
 
-# 提取字段（单次 jq 调用，替代 3 个 python3 进程）
-TOOL_NAME="${CLAUDE_TOOL_NAME:-$(echo "$INPUT" | jq -r '.tool_name // ""')}"
-TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
-RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
-SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
+# (1/3) 一次性解析输入：标量 + tool_input JSON 串。@sh 输出的字符串已 shell-quote，
+# 可直接 eval 赋值；tool_input 用 tojson 序列化后再 eval 成字符串变量，
+# 后续作为 --argjson 注入回 jq -n 构建器。
+eval "$(echo "$INPUT" | jq -r '@sh "
+_IN_RAW_CWD=\(.cwd // "")
+_IN_SESSION=\(.session_id // .sessionId // "")
+_IN_TOOL=\(.tool_name // "")
+_IN_TOOL_INPUT_JSON=\((.tool_input // {}) | tojson)
+"')"
+
+TOOL_NAME="${CLAUDE_TOOL_NAME:-$_IN_TOOL}"
+PROJECT_PATH=$(resolve_project_path "${_IN_RAW_CWD:-$PWD}")
+SESSION_ID="${_IN_SESSION:-${CLAUDE_CODE_SESSION_ID:-cli}}"
 
-# 构造事件 JSON（jq -n 替代 python3 heredoc）
+# (2/3) 构造事件 JSON
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
 EVENT=$(jq -nc \
   --arg hook_type "PreToolUse" \
@@ -25,7 +49,7 @@ EVENT=$(jq -nc \
   --arg session_id "$SESSION_ID" \
   --arg project_path "$PROJECT_PATH" \
   --arg tool_name "$TOOL_NAME" \
-  --argjson tool_input "$TOOL_INPUT" \
+  --argjson tool_input "$_IN_TOOL_INPUT_JSON" \
   --arg auth "$AUTH_TOKEN" \
   '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
     project_path: $project_path, tool_name: $tool_name, tool_input: $tool_input,
@@ -36,26 +60,33 @@ send_event_or_enqueue "$EVENT" 5
 RESPONSE="$HOOK_RESPONSE"
 
 if [ -n "$RESPONSE" ]; then
-  ALLOW=$(echo "$RESPONSE" | jq -r '.allow // true')
-
-  if [ "$ALLOW" = "false" ]; then
-    # 优先使用 hookSpecificOutput（Claude Code 官方格式），否则降级到 stderr + exit 2
-    HAS_HOOK_OUTPUT=$(echo "$RESPONSE" | jq -r 'if .hookSpecificOutput then "yes" else "no" end')
-    if [ "$HAS_HOOK_OUTPUT" = "yes" ]; then
-      # 输出 hookSpecificOutput 格式到 stdout，但必须 exit 非0 才能真正阻止工具执行
-      echo "$RESPONSE" | jq '{hookSpecificOutput: .hookSpecificOutput}'
+  # (3/3) 一次性解析 RESPONSE：allow / has_hook / has_ctx / reason
+  #       + 预渲染 hookSpecificOutput JSON 串（compact）。
+  # 注意：jq 的 `//` 运算符把 false 和 null 同视为"取后备"，所以
+  # `.allow // true` 在 .allow=false 时也返回 true —— 这是历史遗留问题，
+  # 保持与重构前完全一致的行为（safety-net 已固化）。
+  eval "$(echo "$RESPONSE" | jq -r '@sh "
+_R_ALLOW=\((.allow // true) | tostring)
+_R_HAS_HOOK=\(if .hookSpecificOutput then "yes" else "no" end)
+_R_HAS_CTX=\(if .additionalContext and (.additionalContext != "") then "yes" else "no" end)
+_R_REASON=\(.reason // "操作被 Forge 阻断")
+_R_HOOK_OUT_JSON=\((if .hookSpecificOutput then {hookSpecificOutput: .hookSpecificOutput} else null end) | tojson)
+"')"
+
+  if [ "$_R_ALLOW" = "false" ]; then
+    if [ "$_R_HAS_HOOK" = "yes" ]; then
+      # 输出 hookSpecificOutput 给 Claude Code（compact JSON 同样有效）
+      echo "$_R_HOOK_OUT_JSON"
       exit 1
     else
-      # 降级：输出原因到 stderr，exit 2 强制阻断
-      REASON=$(echo "$RESPONSE" | jq -r '.reason // "操作被 Forge 阻断"')
-      echo "$REASON" >&2
+      # 降级：原因到 stderr + exit 2
+      echo "$_R_REASON" >&2
       exit 2
     fi
   fi
 
-  # 有 additionalContext 时输出
-  HAS_CONTEXT=$(echo "$RESPONSE" | jq -r 'if .additionalContext and (.additionalContext != "") then "yes" else "no" end')
-  if [ "$HAS_CONTEXT" = "yes" ]; then
+  # 有 additionalContext 时把整个 RESPONSE 透传给 Claude Code
+  if [ "$_R_HAS_CTX" = "yes" ]; then
     echo "$RESPONSE"
   fi
 fi