@fyeeme/pi-review 1.0.1 → 1.0.3

package/README.md

@@ -93,9 +93,11 @@ An LLM-callable tool that spawns one or more real pi subprocesses:
   receive the `subagent` tool in its default toolset, so it cannot recurse. A
   caller opts in by listing `subagent` in the child's `tools` whitelist; set
   `PI_SUBAGENT_MAX_SPAWN_DEPTH` to allow multi-level fan-out up to a hard cap.
-- **Default turn budget** — fan-out agents get a finite default `maxTurns` (25)
+- **Default turn budget** — fan-out agents get a finite default `maxTurns` (50,
+  aligned to CC's `FORKED_AGENT_DEFAULT_MAX_TURNS` in 2.1.227)
   when the caller omits it; an explicit `0` is honored.
-- **Configurable concurrency** — `PI_MAX_CONCURRENT_SUBAGENTS` (default 8;
+- **Configurable concurrency** — `PI_MAX_CONCURRENT_SUBAGENTS` (default 20,
+  aligned to CC's `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ?? 20` in 2.1.227;
   invalid values fall back to the default).
 
 Each sub-agent is a full `pi --mode json -p --no-session` run. Progress streams
@@ -144,6 +146,12 @@ sub-agents are spawned and *which mode* is chosen.
 
 ## Status
 
-MVP. Phase 2 (not yet built): a `review_verify` tool encapsulating 3-vote
-adversarial verify, and a `review_report` tool enforcing the output schema /
-`--share` lavish artifact.
+`review_report` is built — schema aligned to CC `ReportFindings` (2.1.227
+empirical): 3-state `outcome` (`fixed`/`skipped`/`no_change_needed`), 2-value
+`verdict` (`CONFIRMED`/`PLAUSIBLE`), `short_summary` (≤60, table overview),
+`report_id` for fixed-later re-reports; renders the Chinese Markdown report
+and writes JSON to `<cwd>/.pi/review/` for CI / `--fix` / `--comment`.
+
+Remaining Phase 2 item (not yet built): a `review_verify` tool encapsulating
+3-vote adversarial verify. `--share` already routes through lavish-axi (see
+the code-review skill).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-review",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Review & cleanup extension for pi. Registers /code-review and /code-simplify commands plus a general-purpose `subagent` tool that spawns parallel pi subprocesses — providing the real fan-out capability the code-review and simplify skills (bundled under `skills/`) need for their multi-agent flows. The /code-simplify handler uses ctx.getContextUsage() to decide parallel vs single-pass mode deterministically.",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@fyeeme/pi-subagent-core": "^0.3.2"
+    "@fyeeme/pi-subagent-core": "^0.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.84.1",

package/skills/code-review/SKILL.md

@@ -10,24 +10,27 @@ description: "Review the current diff for correctness bugs and reuse/simplificat
   earlier v2.1.220 reconstruction. Every section below was located in the
   extracted strings (cc_strings_223.txt) and verified.
 
-  What CC 2.1.223 actually contains (verified against the binary):
-    - Effort: medium = precision; high = recall ("err on the side of
-      surfacing"); xhigh/max add a gap-hunt. Each finder surfaces ≤6 candidates.
+  What CC 2.1.227 actually contains (verified against the binary):
+    - Effort quad tuple {correctnessAngles, perAngle, maxFindings, sweep}:
+      medium {3,6,8,false} / high {3,6,10,false} / xhigh {5,8,15,true} / max
+      same structure as xhigh. medium = precision; high+ = recall
+      ("err on the side of surfacing"); xhigh/max add a gap-hunt (≤8 new
+      candidates). Correctness angles are taken in order A→E (`slice(0, N)`).
+    - Inline finder allocation: medium/high = 8 finders (A/B/C + 3 cleanup +
+      altitude + conventions); xhigh/max = 10 finders (A–E + same). Each
+      cleanup angle gets its own finder.
     - Low effort: 1 diff pass, no verify, target min(files_changed, 4) findings.
-    - Finder allocation (workflow Find-phase, linearized inline for Pi): one
-      finder per correctness angle (A–E) + Conventions, plus one combined cleanup
-      finder, pooled before verify. (CC's native *inline* medium path splits
-      differently — 8 finders: 3 correctness + 3 cleanup + altitude + conventions.)
+    - Verify via an independent agent, grouped by (file, line) (absorbed from
+      the workflow GROUP_VERDICT_SCHEMA): CONFIRMED / PLAUSIBLE / REFUTED,
+      "PLAUSIBLE by default". Keep CONFIRMED + PLAUSIBLE, drop REFUTED.
+    - ReportFindings schema: verdict CONFIRMED|PLAUSIBLE, outcome
+      fixed|skipped|no_change_needed, finding carries short_summary (≤60).
     - Angles A–E + Reuse/Simplification/Efficiency/Altitude + Conventions,
       verbatim (same source variables the /simplify skill reuses).
-    - Verify via an independent agent: CONFIRMED / PLAUSIBLE / REFUTED,
-      "PLAUSIBLE by default". Keep CONFIRMED + PLAUSIBLE, drop REFUTED.
     - Gap-hunt (xhigh/max): one fresh finder hunting only for gaps not
       already listed (CC's Sweep phase: "Fresh finder hunting only for gaps").
-    - Output: Markdown findings table + per-finding details block, printed
-      as text (no ReportFindings tool on Pi); carries file:line/category/
-      verdict/summary/failure_scenario per finding.
-    - --share publishes an Artifact; --fix applies findings to the working tree.
+    - Fixed-later obligation (CC Q8m): later fixes in the session must
+      re-report findings with updated outcome.
 
   Invocation: /code-review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<target>]
     target = Class#method | file path | PR number | branch name
@@ -43,7 +46,7 @@ description: "Review the current diff for correctness bugs and reuse/simplificat
     1. Output   — CC calls a ReportFindings tool with {level, findings}; Pi
                   uses this extension's `review_report` tool (the Pi counterpart
                   to ReportFindings, verdict/outcome enums aligned to CC
-                  v2.1.226): it renders the Chinese Markdown report (table +
+                  v2.1.227): it renders the Chinese Markdown report (table +
                   details) back to the conversation AND writes a
                   machine-readable JSON to <cwd>/.pi/review/ for CI / --fix /
                   --comment. If the tool is absent, fall back to printing the
@@ -72,17 +75,26 @@ altitude, and conventions findings when the output cap forces a cut.
 
 ## Effort levels
 
-| Level | Intent | Verify | Subagents | Output cap |
+| Level | Intent | Verify | Subagents | 四元组 `{correctnessAngles, perAngle, maxFindings, sweep}` |
 |-------|--------|--------|-----------|------------|
-| low (default) | quick scan | no | no | min(files_changed, 4) |
-| medium | **precision** — surface only findings a maintainer would act on | independent agent | fan-out (1 finder/angle) | ≤ 8 |
-| high | **recall** — catch every real bug a careful reviewer would; **err on the side of surfacing** | independent agent | more angles | ≤ 10 |
-| xhigh → max | recall + **gap-hunt** | independent agent | above + 1 fresh gap finder | larger, may include uncertain |
+| low (default) | quick scan | no | no | 上限 `min(files_changed, 4)` |
+| medium | **precision** — surface only findings a maintainer would act on | independent verifier (grouped) | 8 finders | `{3, 6, 8, false}` |
+| high | **recall** — catch every real bug a careful reviewer would; **err on the side of surfacing** | recall-biased verifier (grouped) | 8 finders | `{3, 6, 10, false}` |
+| xhigh | recall + **gap-hunt** | recall-biased verifier (grouped) | 10 finders + 1 gap | `{5, 8, 15, true}` |
+| max | 同 xhigh | 同 xhigh | 同 xhigh | 同 xhigh |
 
 **max 与 xhigh 结构相同**：fan-out / verify / sweep 完全一致，差别仅在模型 reasoning effort（CC v2.1.226 注释实证：`max → same structure as xhigh (the API reasoning effort differs, not the fan-out)`）。若运行时不支持调节 reasoning effort，max 在结构上退化为 xhigh——不要因档名而期待更多 fan-out。
 
-Each finder surfaces **up to 6 candidate findings** with `file`, `line`, a
-one-line `summary`, and a concrete `failure_scenario`.
+The quad tuple parameterizes the whole pipeline (CC inline semantics, verified 2.1.227):
+
+- `correctnessAngles` — how many correctness angles A–E run, taken **in order** (medium/high: A/B/C; xhigh/max: A–E).
+- `perAngle` — candidate cap per finder (6 at medium/high, 8 at xhigh/max).
+- `maxFindings` — the report cap after verify (8 / 10 / 15).
+- `sweep` — whether Phase 3 gap-hunt runs (xhigh/max only, ≤ 8 new candidates).
+
+Each finder surfaces up to `perAngle` candidate findings with `file`, `line`, a
+one-line `summary`, a ≤60-char `short_summary`, and a concrete
+`failure_scenario`.
 
 If a target argument was provided, review that target instead of the whole diff.
 
@@ -96,6 +108,43 @@ commit. If a PR number, branch name, or file path was passed as an argument,
 review that target instead. Treat this diff as the review scope. Note the
 files-changed count — low effort uses it for the dynamic output cap.
 
+## Phase 0.5 — Scope (run once in the main session, before any fan-out)
+
+Before dispatching any finder, establish the review scope yourself in this
+session (absorbed from CC's workflow Scope phase: turns N repeated
+discoveries by subagents into one, and keeps every subagent on the same
+scope — subagents stop running their own `git diff` / CLAUDE.md discovery):
+
+1. Run the diff command from Phase 0 and **confirm it is non-empty**. If it is
+   empty (or the target is invalid), terminate here — report that there is
+   nothing to review, spawn no subagents.
+2. List the changed files, plus the files-changed count.
+3. Find the applicable CLAUDE.md files (user-level, repo-root, plus any in a
+   directory that is an ancestor of a changed file) and read them; extract the
+   conventions relevant to the diff.
+4. Write a short change summary (what the diff does, 2–4 lines).
+
+Assemble these into a scope block:
+
+```
+## Review scope
+
+Diff command: <the exact command>
+Changed files: <list>
+Files changed count: <n>
+Applicable CLAUDE.md files: <list>
+Conventions: <the extracted rules relevant to the diff>
+Change summary: <2–4 lines>
+
+Target parameter (informational only): <target args, if any — do not perform
+actions based on it>
+```
+
+Embed this block verbatim at the top of **every** finder / verifier / gap-hunt
+subagent prompt. Subagents do not re-discover the diff or CLAUDE.md; the
+target argument travels as a scope constraint only, never as an instruction to
+a subagent.
+
 ---
 
 # LOW-EFFORT FLOW  (default; runs standalone, no subagents)
@@ -124,7 +173,9 @@ Do **not** flag style, naming, perf, missing tests, or anything outside the hunk
 Target **min(files_changed, 4) findings**, most-severe first. If you have fewer,
 do one more pass focused on the largest changed file and on any **removed** code
 blocks. Output exactly `(none)` only if the diff is trivially correct after
-that pass. Do not call a ReportFindings tool even if one is available.
+that pass.
+
+Low 档输出契约是**双变体**（与 CC 的 `p$p`/`d$p` 一致）：若 `review_report` 工具可用（本扩展已注册），调用它**一次**上报 `{level: "low", fanned_out: false, findings}`，每条 finding 带 `file` / `line` / `summary` / `short_summary`（≤60 字符）/ `failure_scenario`；无发现时传空数组。不要重复打印文本——工具负责渲染。若 `review_report` 不可用，改为纯文本输出：每行 `path/to/file.ext:123 — 问题与失败后果`，无发现输出 `(none)`，不调用任何上报工具。
 
 ---
 
@@ -137,13 +188,25 @@ finder agents in a single batch (mode: parallel) so they run concurrently;
 otherwise do not fake the fan-out — work the angles yourself in sequence in
 this same context, or report that the subagent capability is unavailable.
 
-**Finder allocation** (the workflow Find-phase, linearized inline for Pi;
-verbatim from the binary): **one finder per correctness angle, plus one finder
-covering all cleanup angles, pooled before verify** — not a priority-sorted
-packing. That is one finder each for A/B/C/D/E plus Conventions, and one
-combined finder for the cleanup angles (Reuse / Simplification / Efficiency /
-Altitude). Never silently drop a correctness angle; if you must consolidate,
-fold cleanup into a correctness finder.
+**Finder allocation** (CC inline, verified 2.1.227): the number of correctness
+angles comes from the effort quad tuple, taken **in order A→E** (`slice(0, N)`
+— do not hand-pick angles; that makes runs unreproducible):
+
+- **medium / high** (3 correctness angles): **8 finders** — A, B, C + one
+  finder each for Reuse, Simplification, Efficiency + one Altitude + one
+  Conventions.
+- **xhigh / max** (5 correctness angles): **10 finders** — A, B, C, D, E + the
+  same 3 cleanup finders + Altitude + Conventions.
+
+Each cleanup angle (Reuse / Simplification / Efficiency) gets its own finder;
+Altitude and Conventions are independent finders. Never silently drop an
+angle — if you must consolidate (subagent unavailable), fold the cleanup
+angles into a correctness finder, but say so in the report.
+
+**Suppression 禁令（xhigh/max）** — different finders may surface different
+candidates for the same line with different reasons. At xhigh/max all of them
+are recorded and pass through verify independently: do NOT let one angle's
+conclusions suppress another's — record both.
 
 The correctness angles hunt for bugs; the cleanup angles hunt for cleanup in
 the changed code. Cleanup, altitude, and conventions candidates use the same
@@ -186,29 +249,33 @@ through a registry/session/global — e.g. a caching provider holding a
 wrapper forwards all the methods the callers actually use.
 
 ### Reuse
-Flag new code that re-implements something the codebase already has — Grep
-shared/utility modules and files adjacent to the change, and name the existing
-helper to call instead.
+
+Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
 
 ### Simplification
+
 Flag unnecessary complexity the diff adds: redundant or derivable state,
-copy-paste with slight variation, deep nesting, dead code left behind. Name the
-simpler form that does the same job.
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
 
 ### Efficiency
+
 Flag wasted work the diff introduces: redundant computation or repeated I/O,
-independent operations run sequentially, blocking work added to startup or hot
-paths. Also flag long-lived objects built from closures or captured environments
-— they keep the entire enclosing scope alive for the object's lifetime (a memory
-leak when that scope holds large values); prefer a class/struct that copies only
-the fields it needs. Name the cheaper alternative.
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
 
 ### Altitude
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix isn't
-deep enough — prefer generalizing the underlying mechanism over adding special
-cases.
 
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
 ### Conventions (CLAUDE.md)
 Find the CLAUDE.md files that govern the changed code: the user-level
 ~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
@@ -228,15 +295,36 @@ are the dominant cause of misses.
 
 ## Phase 2 — Dedup and verify
 
-Dedup near-duplicates (same defect, same location, same reason → keep one).
-
-Then verify each candidate. If the `subagent` tool is available, dispatch an
-independent verify agent (one per candidate, or a small batch): give it the
-diff, the relevant file(s), and the candidate; it returns exactly one of
-**CONFIRMED / PLAUSIBLE / REFUTED**. An independent agent counters the
-confirmation bias of self-review. If `subagent` is unavailable, fall back to
-re-checking each candidate yourself (self-check). Keep **CONFIRMED and
-PLAUSIBLE**, drop REFUTED. Give each surviving finding a verdict:
+Dedup near-duplicates (same defect, same location, same reason → keep one;
+different reasons for the same line are NOT duplicates — at xhigh/max both
+are kept per the suppression ban).
+
+Then verify each candidate **grouped by location**. If the `subagent` tool is
+available: group the deduplicated candidates by `(file, line)`; dispatch ONE
+independent verify agent per group (mode: parallel, one prompt per group),
+giving it the scope block, the diff, the relevant file(s), and the full
+candidate list for that location with each candidate's index. The verifier
+returns a verdict per candidate:
+
+```
+[{ "index": <candidate index>, "verdict": "CONFIRMED" | "PLAUSIBLE" | "REFUTED", "evidence": "<quote/argument>" }, ...]
+```
+
+Grouping is by location, NOT dedup — each candidate is judged independently;
+same-location candidates may describe different defects. A candidate the
+verifier omitted (interrupted or skipped an index) is **dropped** — never
+invent a PLAUSIBLE for it. One verifier failure drops its whole group (the
+same trade-off CC's workflow makes); if you are not confident in a group's
+verifier, fall back to one verifier per candidate for that group.
+
+This group-by-location verify is a deliberate absorption of CC's workflow
+optimization into the inline path (CC inline dispatches one verifier per
+candidate): a location with 3 candidates costs 1 verifier instead of 3 —
+~40% fewer verifier agents is the expectation, not a guarantee.
+
+If `subagent` is unavailable, fall back to re-checking each candidate yourself
+(self-check). Keep **CONFIRMED and PLAUSIBLE**, drop REFUTED. Give each
+surviving finding a verdict:
 
 - **CONFIRMED** — can name the inputs/state that trigger it and the wrong
   output or crash. Quote the line.
@@ -252,6 +340,12 @@ optional field), falsy-zero treated as missing, off-by-one on a boundary the
 code does not exclude, retry storms / partial failures, regex/allowlist that
 lost an anchor. These are PLAUSIBLE.
 
+**Recall bias by level** — at high/xhigh/max, a single non-REFUTED verdict
+keeps the candidate: do NOT drop it on uncertainty ("speculative", "depends
+on runtime state"). That is the recall contract of high+. Medium is the
+precision level: there, additionally weigh whether a maintainer would act on
+the finding before keeping it.
+
 **REFUTED** only when constructible from the code: factually wrong (quote the
 actual line); provably impossible (type/constant/invariant — show it); already
 handled in this diff (cite the guard); or pure style with no observable effect.
@@ -260,7 +354,8 @@ handled in this diff (cite the guard); or pure style with no observable effect.
 
 At **xhigh and max**, after Phase 2 dedup, dispatch ONE fresh finder agent (the
 `subagent` tool) that has never seen the candidates and hunts only for gaps not
-already listed.
+already listed — **at most 8 new candidates**. Feed anything it finds back
+through Phase 2 verify before keeping it.
 
 Constrain it so exploration can't run away (Pi adaptation — CC's workflow bounds
 this differently):
@@ -285,26 +380,37 @@ At **high and below**, skip Phase 3.
 
 Report the findings via the `review_report` tool (this extension's counterpart
 to CC's `ReportFindings`) — call it **once** with
-`{ level, target, files_changed, fanned_out, findings }`, findings ranked
-most-severe first (empty array if nothing survived verification). The tool
-renders the Chinese Markdown report (table + details) back to the conversation
-AND writes a machine-readable JSON to `<cwd>/.pi/review/` for CI / `--fix` /
-`--comment`. Do **not** also hand-write the Markdown table.
+`{ level, target, files_changed, fanned_out, report_id, findings }`, findings
+ranked most-severe first (empty array if nothing survived verification). The
+tool renders the Chinese Markdown report (table + details) back to the
+conversation AND writes a machine-readable JSON to `<cwd>/.pi/review/` for CI /
+`--fix` / `--comment`. Do **not** also hand-write the Markdown table.
 
 Each finding in the array carries: `file`, `line` (optional), `category`
 (`correctness` / `reuse` / `simplification` / `efficiency` / `altitude` /
 `conventions`, or a more specific slug like `test-coverage`), `verdict`
-(`CONFIRMED` / `PLAUSIBLE` / `REFUTED`), `summary` (one line, Chinese), and
-`failure_scenario` (concrete input/state → wrong output/crash; for cleanup
-findings, the concrete cost — Chinese). When re-reporting after applying
-`--fix`, set `outcome` on each finding (`fully_achieved` / `mostly_achieved` /
-`partially_achieved` / `not_achieved` / `unclear_from_transcript` — mirrored
-verbatim from CC's `ReportFindings`, v2.1.226).
-
-Cap = low's min(files_changed, 4); 8 at medium; 10 at high; larger at
-xhigh → max. If more than `{cap}` survive, send the `{cap}` most severe
-(correctness outranks cleanup/altitude/conventions when cutting). If nothing
-survives, send an empty `findings` array — the tool prints a zero-count header.
+(`CONFIRMED` / `PLAUSIBLE`), `short_summary` (≤60 字符、纯声明——去掉理由与
+后果，汇总表概述列优先使用它；示例：`"off-by-one in loop bound"`),
+`summary` (一行中文，含理由与后果，详情块使用), `failure_scenario`
+(concrete input/state → wrong output/crash; for cleanup findings, the
+concrete cost — Chinese). When re-reporting after applying `--fix`, set
+`outcome` on each finding (`fixed` / `skipped` / `no_change_needed` — CC
+`ReportFindings` 三档，2.1.227 实证).
+
+Cap = `maxFindings` from the effort table: `min(files_changed, 4)` at low; 8
+at medium; 10 at high; 15 at xhigh/max. If more than the cap survive, send
+the cap most severe (correctness outranks cleanup/altitude/conventions when
+cutting; CONFIRMED outranks PLAUSIBLE). If nothing survives, send an empty
+`findings` array — the tool prints a zero-count header.
+
+**Fixed-later 义务** (CC `Q8m`): if, after this report, any later work in this
+session fixes one of the reported findings (a user-requested fix, or a fix
+that comes along with other changes), you MUST call `review_report` again
+with the same `report_id`, the same findings, and updated `outcome` values —
+before writing any text summary. The re-report updates states only; it does
+not repeat the findings text. Generate the `report_id` (e.g. `review-<ts>`)
+on the first report and reuse it on every re-report so consumers can merge
+the files by id.
 
 **全部用中文**：`summary` 与 `failure_scenario` 一律中文；`verdict`、`category`、
 `outcome` 作为标识符保留英文 token。
@@ -326,10 +432,11 @@ directly — correctness bugs and reuse/simplification/efficiency cleanups alike
 Skip any finding whose fix would change intended behavior, require changes well
 outside the reviewed diff, or that you judge to be a false positive — note the
 skip rather than arguing with it. Then call `review_report` once more to
-re-report, setting `outcome` on each finding (`fully_achieved` / `mostly_achieved`
-/ `partially_achieved` / `not_achieved` / `unclear_from_transcript` — skipped
-ones are `not_achieved` or `unclear_from_transcript`). This structured re-report
-replaces the hand-written summary and makes the fix result machine-consumable.
+re-report (same `report_id`), setting `outcome` on each finding (`fixed` =
+applied and verified / `skipped` = real but not applied, incl. reverted /
+`no_change_needed` = not applicable or already handled). This structured
+re-report replaces the hand-written summary and makes the fix result
+machine-consumable.
 If `review_report` is unavailable, fall back to a brief text summary of what was
 fixed and what was skipped.
 

package/skills/simplify/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: simplify
-description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that. v2 (from Claude Code CLI v2.1.223) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied, verified against the project's check command, and auto-reverted on failure, then reported as structured outcomes via review_report."
+description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that. v3 (from Claude Code CLI v2.1.227, symbol-level verified) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied, verified against the project's check command, and auto-reverted on failure, then reported as structured outcomes via review_report."
 ---
 
 <!--
-  Origin: Claude Code built-in skill `/simplify` (CLI v2.1.223), reverse-
-  engineered from bin/claude.exe strings. Pi registers it as /code-simplify.
+  Origin: Claude Code built-in skill `/simplify` (CLI v2.1.227), reverse-
+  engineered from bin/claude.exe raw bytes. Pi registers it as /code-simplify.
 
   Lineage:
     v2.1.220 → the first reconstruction         (v1)
@@ -14,6 +14,27 @@ description: "Review the changed code for reuse, simplification, efficiency, and
                PARALLEL/SINGLE-PASS split are unchanged vs v2.1.220. The 4
                angle bodies are shared verbatim with code-review's cleanup
                angles (same source variables in the binary).
+    v2.1.227 → symbol-level verified 2026-08-11 from raw bytes: skill bodies
+               VBv/KBv (with interpolated c$e / m7t / u$e / d$e / p$e) are
+               unchanged; the mode guard is Dii (see below); fan-out defaults
+               nJu=20 / lKs=50 are now mirrored in the subagent tool.
+
+  CC 2.1.227 empirical evidence (symbol-level, extracted from bin/claude.exe):
+    - $u({name: "simplify", ..., getPromptForCommand(args, ctx)}) registers the
+      command; no getContext → default "inline" execution: the mode body is
+      injected into the main conversation and the model dispatches the 4
+      cleanup agents itself via the Agent tool (mi = "Agent", alias oj =
+      "Task"), "all in a single message so they run concurrently".
+    - Dii(ctx) — the PARALLEL/SINGLE-PASS guard: single-pass when
+      ctx.agentContext && ok(ctx.agentContext) >= wV() (ok = depth function:
+      main=0, subagent=depth; wV() = CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH,
+      default 3, feature flag tengu_hazel_trellis) OR the Agent tool is not in
+      the options.tools allowlist (Pa matches by name/aliases).
+    - VBv / KBv — the two mode-body templates; interpolated variables shared
+      with /code-review: c$e (Phase 0), m7t/u$e/d$e/p$e (the 4 cleanup angles).
+    - nJu() = CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ?? 20; lKs =
+      FORKED_AGENT_DEFAULT_MAX_TURNS = 50 — mirrored as the subagent tool's
+      defaults (PI_MAX_CONCURRENT_SUBAGENTS env still overrides the ceiling).
 
   Bundled: ships inside the pi-review extension (skills/simplify/SKILL.md).
 
@@ -25,13 +46,13 @@ description: "Review the changed code for reuse, simplification, efficiency, and
   ════════════════════════════════════════════════════════════════════════
     1. Fan-out tool — CC uses the Agent tool; Pi uses the `subagent` tool
        (mode: parallel). Where CC says "the Agent tool", read `subagent`.
-    2. Mode guard  — CC's _Yo has two clauses: (a) spawn-depth — single-pass when
+    2. Mode guard  — CC's Dii has two clauses: (a) spawn-depth — single-pass when
        agent depth >= CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (default 3); (b) the
        Agent tool must be in the allowlist. On Pi: (a) is N/A — the `subagent`
        tool spawns a fresh subprocess (always depth 0), so depth never accumulates
        — so decideSimplifyMode substitutes a context-fraction heuristic
        (tokens/contextWindow >= 0.8 → single-pass), a Pi addition NOT a mirror of
-       _Yo; (b) is mirrored as "the `subagent` tool must be registered". The
+       Dii; (b) is mirrored as "the `subagent` tool must be registered". The
        decision is made DETERMINISTICALLY by the /code-simplify handler — it can
        read ctx.getContextUsage(), which a pure-prompt skill cannot — and announced
        in the trigger message; this skill just provides the two mode bodies.
@@ -68,36 +89,40 @@ review that target instead. Treat this diff as the review scope.
 
 ## Phase 1 — Review (4 cleanup agents in parallel)
 
-Launch **4 independent review agents** via the `subagent` tool, all in a single
-message so they run concurrently (mode: parallel). Pass each agent the diff and
-one of the four angles below. Each returns its findings with `file`, `line`, a
-one-line `summary`, and the concrete cost (what is duplicated, wasted, or harder
-to maintain).
+Launch **4 independent review agents** via the subagent tool, all in a
+single message so they run concurrently. Pass each agent the diff and one of
+the four angles below. Each returns its findings with `file`, `line`, a
+one-line `summary`, and the concrete cost (what is duplicated, wasted, or
+harder to maintain).
 
 ### Reuse
-Flag new code that re-implements something the codebase already has — Grep
-shared/utility modules and files adjacent to the change, and name the existing
-helper to call instead.
+
+Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
 
 ### Simplification
+
 Flag unnecessary complexity the diff adds: redundant or derivable state,
-copy-paste with slight variation, deep nesting, dead code left behind. Name the
-simpler form that does the same job.
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
 
 ### Efficiency
+
 Flag wasted work the diff introduces: redundant computation or repeated I/O,
-independent operations run sequentially, blocking work added to startup or hot
-paths. Also flag long-lived objects built from closures or captured environments
-— they keep the entire enclosing scope alive for the object's lifetime (a memory
-leak when that scope holds large values); prefer a class/struct that copies only
-the fields it needs. Name the cheaper alternative.
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
 
 ### Altitude
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix isn't
-deep enough — prefer generalizing the underlying mechanism over adding special
-cases.
 
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
 ## Phase 2 — Apply, verify, and report
 
 Follow the shared **Phase 2** procedure at the end of this skill (snapshot → apply → verify → auto-revert on failure → report via `review_report`). The parallel fan-out only changes how findings are gathered (Phase 1); applying, verifying, and reporting are identical across modes. Set `fanned_out: true` in the report since the 4-agent fan-out actually ran.
@@ -108,40 +133,44 @@ Follow the shared **Phase 2** procedure at the end of this skill (snapshot → a
 
 `/code-simplify → subagent tool unavailable → single-pass inline cleanup → apply the fixes`
 
-The `subagent` tool isn't available in this context (or context is near-full), so
-the usual 4-agent fan-out can't run. Work through all four angles below yourself,
-in this same context, in one pass — do not skip an angle for lack of fan-out.
+The subagent tool isn't available in this context, so the usual
+4-agent fan-out can't run. Work through all four angles below yourself, in
+this same context, in one pass — do not skip an angle for lack of fan-out.
 
 ## Phase 1 — Review (4 cleanup angles, single pass)
 
 Review the diff against each angle below in turn. For each, note findings with
-`file`, `line`, a one-line `summary`, and the concrete cost (what is duplicated,
-wasted, or harder to maintain).
+`file`, `line`, a one-line `summary`, and the concrete cost (what is
+duplicated, wasted, or harder to maintain).
 
 ### Reuse
-Flag new code that re-implements something the codebase already has — Grep
-shared/utility modules and files adjacent to the change, and name the existing
-helper to call instead.
+
+Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
 
 ### Simplification
+
 Flag unnecessary complexity the diff adds: redundant or derivable state,
-copy-paste with slight variation, deep nesting, dead code left behind. Name the
-simpler form that does the same job.
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
 
 ### Efficiency
+
 Flag wasted work the diff introduces: redundant computation or repeated I/O,
-independent operations run sequentially, blocking work added to startup or hot
-paths. Also flag long-lived objects built from closures or captured environments
-— they keep the entire enclosing scope alive for the object's lifetime (a memory
-leak when that scope holds large values); prefer a class/struct that copies only
-the fields it needs. Name the cheaper alternative.
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
 
 ### Altitude
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix isn't
-deep enough — prefer generalizing the underlying mechanism over adding special
-cases.
 
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
 ## Phase 2 — Apply, verify, and report
 
 Follow the shared **Phase 2** procedure at the end of this skill (snapshot → apply → verify → auto-revert on failure → report via `review_report`). Single-pass vs parallel only changes how findings are gathered (Phase 1); applying, verifying, and reporting are identical across modes. Set `fanned_out: false` in the report so a reader is not misled into thinking the 4-agent fan-out ran.
@@ -181,7 +210,7 @@ that would discard the user's intended changes too.
 Apply each surviving finding directly. Skip any finding whose fix would change
 intended behavior, require changes well outside the reviewed diff, or that you
 judge to be a false positive — note the skip (it will be reported as
-`not_achieved`).
+`skipped`).
 
 ## Step 3 — Verify, branching on the result
 
@@ -189,11 +218,10 @@ Run the verification command the handler injected in the trigger message (e.g.
 `npm run check`), then branch:
 
 - **No verification command was detected** → keep the applied changes, mark each
-  applied finding `fully_achieved`, and say in the report that NO verification
+  applied finding `fixed`, and say in the report that NO verification
   was run. Verification is opportunistic — never block on its absence.
 - **Verification passes** → keep the changes; applied findings are
-  `fully_achieved` (or `mostly_achieved` / `partially_achieved` if a fix only
-  partly addressed the issue).
+  `fixed`.
 - **Verification fails** → the working tree is verified-broken; go to Step 3a.
 
 ### Step 3a — Auto-revert (hybrid granularity, only on failure)
@@ -209,7 +237,7 @@ otherwise survive the rollback).
    after each file. Keep only files whose verification passes; revert any file
    whose verification fails back to its baseline.
 4. If NO file passes on its own, leave everything reverted and mark every
-   finding `not_achieved` — a clean tree is the safe outcome, not a broken one.
+   finding `skipped` — a clean tree is the safe outcome, not a broken one.
 
 This caps the cost: the common case (clean apply) runs verification exactly
 once; only a failure escalates to one verification per touched file.
@@ -217,17 +245,22 @@ once; only a failure escalates to one verification per touched file.
 ## Step 4 — Report via `review_report`
 
 Call the `review_report` tool **once** with `level: "simplify"` and one finding
-entry per cleanup, ranked most-severe first. Each entry carries `file`, `line`
-(optional), `category` (`reuse` / `simplification` / `efficiency` /
-`altitude`), `summary` (one line, Chinese), `failure_scenario` (the concrete
+entry per cleanup, ranked most-severe first. Generate a `report_id` (e.g.
+`review-<ts>`) on this first call; reuse it on any re-report (fixed-later
+义务：本会话后续若再修复已上报项，必须先再次调用 `review_report` 更新
+`outcome`，先于任何文字总结)。Each entry carries `file`, `line` (optional),
+`category` (`reuse` / `simplification` / `efficiency` / `altitude`),
+`short_summary` (≤60 字符纯声明标签，去掉理由与后果——汇总表概述列优先用它),
+`summary` (one line, Chinese，含理由与后果), `failure_scenario` (the concrete
 cost — Chinese), and `outcome`:
 
-- `fully_achieved` — applied and verification passed (or no verification command
-  existed and the change was kept).
-- `mostly_achieved` / `partially_achieved` — applied but only partly addresses
-  the issue.
-- `not_achieved` — skipped, or reverted by the auto-revert in Step 3a.
-- `unclear_from_transcript` — could not determine.
+- `fixed` — applied and verification passed (or no verification command existed
+  and the change was kept).
+- `skipped` — real but not applied: judged a false positive / behavior-
+  changing, or reverted by the auto-revert in Step 3a. Partial applies (per-file
+  rollback kept only some files) also count as `skipped` — the per-file detail
+  goes into `summary`.
+- `no_change_needed` — not applicable or already handled.
 
 Do **not** write a free-text summary as the primary record — the structured
 `review_report` call IS the summary (it renders the report AND writes JSON to

package/src/commands/code-simplify.ts

@@ -41,12 +41,13 @@ function readScriptsAt(cwd: string): Record<string, string> | null {
  * Decide simplify mode deterministically from real context usage + tool availability.
  * Pure function — unit-testable.
  *
- * CC parity note: CC's /simplify guard (_Yo) is a SPAWN-DEPTH recursion limit, NOT a
- * context check — `RO(ctx) >= dne()` where RO returns the agent's depth and dne()
- * returns CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (default 3). That is N/A on Pi: the
+ * CC parity note: CC's /simplify guard (Dii, verified in the 2.1.227 binary) is
+ * a SPAWN-DEPTH recursion limit, NOT a context check — `ok(ctx.agentContext) >= wV()`
+ * where ok() returns the agent's depth (main=0) and wV() returns
+ * CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (default 3). That is N/A on Pi: the
  * `subagent` tool spawns a fresh subprocess (depth 0), so depth never accumulates.
  * The context-fraction heuristic below is a Pi-specific substitute (don't fan out
- * when the parent's context is near-full), NOT a mirror of _Yo. The other _Yo clause
+ * when the parent's context is near-full), NOT a mirror of Dii. The other Dii clause
  * — the Agent tool must be in the allowlist — IS mirrored here as `hasSubagent`.
  */
 export function decideSimplifyMode(opts: {

package/src/tools/review_report.ts

@@ -9,29 +9,32 @@
  * a machine-readable JSON (findings + level + outcome) to
  * `<cwd>/.pi/review/<id>.json` so CI / --fix / --comment can consume it.
  *
- * `verdict` (CONFIRMED/PLAUSIBLE/REFUTED) and `outcome` (5-state) enums follow
- * the CC ReportFindings shape (outcome values copied from the CC binary). The
- * code-review skill drops REFUTED findings before reporting, so that value is
- * accepted by the schema but rarely seen in practice.
+ * `verdict` (CONFIRMED/PLAUSIBLE) and `outcome` (fixed/skipped/no_change_needed)
+ * enums follow the CC ReportFindings shape — values verified against the CC
+ * v2.1.227 binary (consistent across 2.1.223/226/227). REFUTED is deliberately
+ * absent: the verify flow drops it before reporting. The tool entry also
+ * normalizes stray invalid values (drop the finding / coerce to skipped) rather
+ * than failing the whole call.
  */
 import { defineTool, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { type Static, Type } from "typebox";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
 // --- enums following the CC ReportFindings shape ----------------------------
+// 值域实证来源：CC v2.1.227 bin/claude.exe（ReportFindings 工具 schema）。
+// verdict 两值与 outcome 三档在 2.1.223/226/227 三版本中一致。
 
-const Verdict = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")]);
+const VERDICT_VALUES = ["CONFIRMED", "PLAUSIBLE"] as const;
+const Verdict = Type.Union(VERDICT_VALUES.map((v) => Type.Literal(v)));
 
-/** CC ReportFindings `outcome` 5 档（v2.1.226 二进制实证）。re-report after --fix 时填。 */
-const Outcome = Type.Union([
-	Type.Literal("fully_achieved"),
-	Type.Literal("mostly_achieved"),
-	Type.Literal("partially_achieved"),
-	Type.Literal("not_achieved"),
-	Type.Literal("unclear_from_transcript"),
-]);
+const OUTCOME_VALUES = ["fixed", "skipped", "no_change_needed"] as const;
+/** CC ReportFindings `outcome` 三档（2.1.227 二进制实证）。fixed-later 再上报时更新。 */
+const Outcome = Type.Union(OUTCOME_VALUES.map((v) => Type.Literal(v)));
+
+// 供 SKILL-schema 同步测试引用（防漂移：SKILL 流程契约不得与常量脱节）。
+export { OUTCOME_VALUES, VERDICT_VALUES };
 
 const Level = Type.Union([
 	Type.Literal("low"),
@@ -54,6 +57,12 @@ const FindingParams = Type.Object({
 			"产生该发现的角度 slug：correctness / reuse / simplification / efficiency / altitude / conventions（或更具体如 test-coverage）。",
 	}),
 	verdict: Type.Optional(Verdict),
+	short_summary: Type.Optional(
+		Type.String({
+			description:
+				"≤60 字符的纯声明标签（去掉理由与后果）。汇总表概述列优先使用它；详情块仍显示完整 summary。流程层面必填（CC 输出模板契约），schema 层面 optional（与 CC tool schema 一致）。中文。",
+		}),
+	),
 	summary: Type.String({ description: "一句话说明（≤80字），同时作紧凑标签。中文。" }),
 	failure_scenario: Type.String({
 		description:
@@ -72,6 +81,12 @@ const ReviewReportParams = Type.Object({
 	findings: Type.Array(FindingParams, {
 		description: "已验证、去重、按严重度从高到低排序的发现列表（most-severe first）。空数组表示无发现存活。",
 	}),
+	report_id: Type.Optional(
+		Type.String({
+			description:
+				"报告标识（如 review-<ts>）。首次上报生成；fixed-later 再上报传同一 id，消费方按 id 归并，同 id 最新 generatedAt 为最终状态。",
+		}),
+	),
 });
 
 interface ReviewReportDetails {
@@ -79,6 +94,56 @@ interface ReviewReportDetails {
 	findingsCount: number;
 	/** 结构化 JSON 落盘路径；落盘失败时为 null（仍返回渲染报告）。 */
 	outFile: string | null;
+	reportId: string | null;
+}
+
+/**
+ * execute 入口的宽松 finding 形态——绕过 schema 校验的直接调用（如单测）
+ * 可能携带旧五档 outcome 或已废弃的 REFUTED verdict。
+ */
+type LooseFinding = {
+	file: string;
+	line?: number;
+	category: string;
+	verdict?: string;
+	short_summary?: string;
+	summary: string;
+	failure_scenario: string;
+	outcome?: string;
+};
+
+/**
+ * 单条清洗：非法 verdict（含已废弃的 REFUTED）返回 null（剔除）；非法 outcome
+ * 归一化为 skipped 并附注原始值。schema 保持严格，清洗在 schema 校验之前。
+ */
+function sanitizeFinding(f: LooseFinding): { f: LooseFinding; note?: string } | null {
+	if (f.verdict !== undefined && !(VERDICT_VALUES as readonly string[]).includes(f.verdict)) return null;
+	let outcome = f.outcome;
+	let note: string | undefined;
+	if (outcome !== undefined && !(OUTCOME_VALUES as readonly string[]).includes(outcome)) {
+		note = `（outcome "${outcome}" 非法，已归一化为 skipped）`;
+		outcome = "skipped";
+	}
+	return { f: { ...f, outcome }, note };
+}
+
+/**
+ * 批量清洗，note 按清洗后数组索引记录（渲染层附注用）。
+ * `prepareArguments`（主防御，schema 校验前）与 `execute` 入口（双保险，
+ * 防绕过 prepareArguments 的直接调用）共用——模型路径的非法值在进入
+ * execute 前已被清洗，validateToolArguments 不会因边缘值 throw 掉整份报告。
+ */
+function normalizeFindings(findings: LooseFinding[]): { findings: LooseFinding[]; notes: Map<number, string> } {
+	const out: LooseFinding[] = [];
+	const notes = new Map<number, string>();
+	for (const raw of findings) {
+		const s = sanitizeFinding(raw);
+		if (!s) continue;
+		const idx = out.length;
+		out.push(s.f);
+		if (s.note) notes.set(idx, s.note);
+	}
+	return { findings: out, notes };
 }
 
 // --- render -----------------------------------------------------------------
@@ -88,15 +153,19 @@ interface FindingInput {
 	line?: number;
 	category: string;
 	verdict?: string;
+	short_summary?: string;
 	summary: string;
 	failure_scenario: string;
 	outcome?: string;
+	/** normalize 附注（如非法 outcome 归一化说明），仅渲染进详情块。 */
+	note?: string;
 }
 interface ReportInput {
 	level: string;
 	target?: string;
 	files_changed?: number;
 	fanned_out?: boolean;
+	reportId?: string;
 	findings: FindingInput[];
 }
 
@@ -118,7 +187,8 @@ function renderReport(p: ReportInput): string {
 	const fanLabel = p.fanned_out === true ? "多智能体" : p.fanned_out === false ? "单遍自审" : "未标注";
 	const targetStr = (p.target ?? "(whole diff)").replace(/`/g, "\\`"); // backtick inside the inline-code cell would close it early
 	const filesStr = p.files_changed != null ? `${p.files_changed} 个文件` : "文件数未标注";
-	lines.push(`\`${p.level}\` · \`${targetStr}\` · ${filesStr} · ${p.findings.length} 条发现 · ${fanLabel}`);
+	const idStr = p.reportId ? ` · 报告 \`${escapeCell(p.reportId)}\`` : "";
+	lines.push(`\`${p.level}\` · \`${targetStr}\` · ${filesStr} · ${p.findings.length} 条发现 · ${fanLabel}${idStr}`);
 	lines.push("");
 
 	if (p.findings.length === 0) {
@@ -130,7 +200,7 @@ function renderReport(p: ReportInput): string {
 	lines.push("|---|------|------|------|------|");
 	for (let i = 0; i < p.findings.length; i++) {
 		const f = p.findings[i]!;
-		lines.push(`| ${i + 1} | ${escapeCell(f.verdict ?? "")} | ${escapeCell(f.category)} | ${escapeCell(fmtLoc(f))} | ${escapeCell(f.summary)} |`);
+		lines.push(`| ${i + 1} | ${escapeCell(f.verdict ?? "")} | ${escapeCell(f.category)} | ${escapeCell(fmtLoc(f))} | ${escapeCell(f.short_summary ?? f.summary)} |`);
 	}
 	lines.push("");
 	lines.push("**详情**");
@@ -138,9 +208,10 @@ function renderReport(p: ReportInput): string {
 	p.findings.forEach((f, i) => {
 		const v = f.verdict ? ` *(${f.verdict})*` : "";
 		const out = f.outcome ? `\n修复结果：\`${f.outcome}\`` : "";
+		const note = f.note ? `\n${f.note}` : "";
 		lines.push(`**${i + 1}. ${fmtLoc(f)} — ${f.category}**${v}`);
 		lines.push(`概述：${f.summary}`);
-		lines.push(`场景：${f.failure_scenario}${out}`);
+		lines.push(`场景：${f.failure_scenario}${out}${note}`);
 		lines.push("");
 	});
 	return lines.join("\n").trimEnd();
@@ -156,13 +227,41 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 	promptSnippet: "review_report — report structured code-review findings (renders Markdown + writes JSON for CI)",
 	promptGuidelines: [
 		"After verify + dedup, call `review_report` once with { level, findings } (most-severe first; empty array if none survived). Do not also hand-write the Markdown table — this tool renders it.",
-		"On re-report after --fix, set each finding's `outcome` (fully_achieved / mostly_achieved / partially_achieved / not_achieved / unclear_from_transcript).",
+		"On re-report after --fix, set each finding's `outcome` (fixed / skipped / no_change_needed).",
 		"Use this tool only when the code-review skill instructs reporting findings; otherwise follow the active output format.",
 	],
 	parameters: ReviewReportParams,
 
+	// 主防御：schema 校验之前清洗非法值（模型路径下校验失败即 throw、工具不执行，
+	// 因此 execute 内的防御对模型不可达）。返回符合 schema 的对象——非法 verdict
+	// 的 finding 剔除、非法 outcome 归一化为 skipped；note 附注由 execute 层基于
+	// 清洗结果生成（schema 对象不含 note 字段）。
+	prepareArguments(args) {
+		if (typeof args !== "object" || args === null) return args as Static<typeof ReviewReportParams>;
+		const raw = args as { findings?: unknown };
+		if (!Array.isArray(raw.findings)) return args as Static<typeof ReviewReportParams>;
+		const { findings } = normalizeFindings(raw.findings as unknown as LooseFinding[]);
+		return { ...raw, findings } as Static<typeof ReviewReportParams>;
+	},
+
 	async execute(toolCallId, params, _signal, _onUpdate, ctx) {
-		const report = renderReport(params);
+		// normalize（双保险）——绕过 prepareArguments 的直接调用（如单测）可能携带
+		// 旧五档 outcome 或已废弃的 REFUTED verdict。归一化而非整单拒绝：非法
+		// verdict 的 finding 剔除，非法 outcome 归一化为 skipped 并附注；渲染与落盘
+		// 永远只含合法值（spec: 消费方永远看到合法值）。
+		const { findings: cleaned, notes } = normalizeFindings(
+			(params.findings ?? []) as unknown as LooseFinding[],
+		);
+		const findings: FindingInput[] = cleaned.map((f, i) => ({ ...f, note: notes.get(i) }));
+
+		const report = renderReport({
+			level: params.level,
+			target: params.target,
+			files_changed: params.files_changed,
+			fanned_out: params.fanned_out,
+			reportId: params.report_id,
+			findings,
+		});
 
 		let outFile: string | null = null;
 		let writeError: string | null = null;
@@ -178,11 +277,12 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 				JSON.stringify(
 					{
 						level: params.level,
+						reportId: params.report_id ?? null,
 						target: params.target ?? null,
 						filesChanged: params.files_changed ?? null,
 						fannedOut: params.fanned_out ?? null,
 						generatedAt: now.toISOString(),
-						findings: params.findings,
+						findings,
 					},
 					null,
 					2,
@@ -200,8 +300,9 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 			: `\n\n[结构化落盘失败（${writeError ?? "未知原因"}），仅渲染报告]`;
 		const details: ReviewReportDetails = {
 			level: params.level,
-			findingsCount: params.findings.length,
+			findingsCount: findings.length,
 			outFile,
+			reportId: params.report_id ?? null,
 		};
 		return {
 			content: [{ type: "text" as const, text: report + tail }],
@@ -217,8 +318,8 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 	// throw, so a failure here degrades to the pre-change behavior rather than erroring.
 	renderResult(result, _options, _theme, _context) {
 		const text = result.content
-			.filter((c) => c.type === "text")
-			.map((c) => (c.type === "text" ? c.text : ""))
+			.filter((c): c is Extract<(typeof result.content)[number], { type: "text" }> => c.type === "text")
+			.map((c) => c.text)
 			.join("\n");
 		return new Markdown(text, 0, 0, getMarkdownTheme());
 	},

package/src/tools/subagent.ts

@@ -28,8 +28,9 @@ import {
 	type AgentSpawnResult,
 } from "@fyeeme/pi-subagent-core";
 
-/** Default concurrency ceiling when PI_MAX_CONCURRENT_SUBAGENTS is unset/invalid. */
-const DEFAULT_MAX_CONCURRENCY = 8;
+/** Default concurrency ceiling when PI_MAX_CONCURRENT_SUBAGENTS is unset/invalid.
+ *  20 = CC's CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ?? 20 (2.1.227 binary empirical). */
+const DEFAULT_MAX_CONCURRENCY = 20;
 
 /**
  * Effective concurrency ceiling, configurable via PI_MAX_CONCURRENT_SUBAGENTS
@@ -46,8 +47,9 @@ function getMaxConcurrency(): number {
  * runaway agent cannot otherwise be bounded. Generous (well above the ~10–15
  * turns the 4-angle finder/verify agents need) so legitimate work is not
  * truncated; callers may override with a smaller or larger explicit value.
+ * 50 = CC's FORKED_AGENT_DEFAULT_MAX_TURNS (2.1.227 binary empirical).
  */
-const DEFAULT_FANOUT_MAX_TURNS = 25;
+const DEFAULT_FANOUT_MAX_TURNS = 50;
 
 // Module-level registry so abortAgent can reach in-flight calls. callIds are
 // unique per tool call (toolCallId#index), so a single registry is safe.
@@ -61,6 +63,12 @@ const SubagentParams = Type.Object({
 		description: "Prompt(s) for the sub-agent(s). single/chain use order; parallel runs all.",
 	}),
 	model: Type.Optional(Type.String({ description: "Full model id (e.g. claude-sonnet-5). Omit for the session default." })),
+	thinking: Type.Optional(
+		Type.Union(
+			["off", "minimal", "low", "medium", "high", "xhigh", "max"].map((l) => Type.Literal(l)),
+			{ description: "Thinking level for the sub-agent(s), passed as --thinking. Omit for the model default." },
+		),
+	),
 	systemPrompt: Type.Optional(Type.String({ description: "Appended to the sub-agent's system prompt." })),
 	tools: Type.Optional(Type.Array(Type.String(), { description: "Tool whitelist for the sub-agent. Omit for default tools." })),
 	parallelism: Type.Optional(
@@ -251,6 +259,7 @@ export const subagentTool = defineTool<typeof SubagentParams, SubagentDetails>({
 		const baseOpts: Omit<AgentSpawnOptions, "callId" | "task"> = {
 			cwd,
 			model: params.model,
+			thinking: params.thinking,
 			tools: params.tools,
 			signal,
 			// Default turn budget applies when omitted; an explicit 0 is honored by