Changelog

All notable changes to this project will be documented in this file.

v0.16.0 (2026-08-11) — provider prompt overhaul: one-shot contract + text-based output format

All 10 pi- provider prompts rewritten around three system-wide contracts: a one-shot turn contract (state assumptions instead of asking — headless CLI calls have no second round), per-skill output budgets, and a text-based severity/verdict format replacing emoji + 1-10 scores.* The execution layers (dispatch rules, timeouts, fallbacks) are untouched; this release changes only what travels to Codex/Gemini and the few presentation-layer lines that consume it.

Changed (shared contracts — all 10 commands)

One-shot turn contract — every provider prompt now opens with "You get exactly one turn: do not ask clarifying questions; state your assumptions and answer anyway", with per-skill adaptations (pi-fact-check: state your reading of an ambiguous claim and check that reading; pi-ui-design: mark design assumptions as  HTML comments that Claude's post-processing audits back to the user)
Text severity tags + verdict replace emoji + 1-10 score — review prompts (pi-code-review / pi-multi-review / pi-ui-review) request [CRITICAL|MEDIUM|SUGGESTION] line prefixes and a closing VERDICT: line (safe | needs-fixes | do-not-merge; pi-ui-review uses ready | needs-fixes | not-ready since it reviews files, not merges). Emoji rendering moves to Claude's presentation layer (CRITICAL→🔴 etc.), so user-facing output is unchanged; the insights-log severity mapping becomes a direct text-tag pass-through. The 1-10 overall score is removed — it had no downstream consumer in single-provider reviews, and cross-model score comparison was false precision. pi-multi-review's Score Comparison table becomes Verdict Comparison, with a verdict split called out as a real signal
Structured finding blocks — the finding-bar questions become output fields (Failure scenario / Impact / Fix — pi-ui-review: User impact / Standard / Fix), capped at 8 findings per provider with an anti-padding rule ("say VERDICT: safe directly — do not invent findings to seem thorough")
Per-skill length budgets — pi-askall and pi-plan capped at ~800 words with strongest-points-first guidance; search-class prompts get density rules instead of hard caps
Uniform stdin transport — pi-code-review / pi-ui-review / pi-research / pi-ui-design switch from arg-embedded prompts (with a >3000-char stdin escape hatch) to the temp-file + stdin shape already used by pi-askall / pi-plan / pi-multi-review; the CLI argument is now always a short label. Closes the remaining ARG_MAX exposure — guideline blocks (CLAUDE.md) expanded into argv unboundedly

Changed (per-skill)

pi-ask-codex / pi-ask-gemini — raw $ARGUMENTS forwarding replaced with a thin framing: one-shot contract + "lead with your answer, then reasoning; be concise by default". No role-play, no format demands — user-authored prompts pass through unpolluted
pi-askall — framing gains a clear-position requirement ("if your answer is 'it depends', name the deciding factors and commit to a recommendation") so synthesis has real divergence to compare instead of two hedges
pi-plan — architect prompt restructured under fixed headings (Assumptions / Challenges / Recommendation / Rejected alternative / Risks / Complexity) so the two providers' answers align for synthesis; "at least one rejected alternative" upgraded to "the strongest alternative you rejected" with an honest exit ("if no serious alternative exists, say so") — anti-strawman; risks must name the concrete scenario in which they bite; a >1-step complexity split between providers is now a documented synthesis signal, recorded in the plan file's new Metadata Complexity line
pi-multi-review — Gemini's attack surface is domain-aware: backend diffs (per Step 2.5 detection) drop the accessibility/responsive item instead of inviting forced findings; both prompts gain "skip attack surfaces that do not apply to this diff"
pi-ui-review — WCAG 2.1 → 2.2 AA; the prompt now explicitly requests specific success-criterion citations (e.g., WCAG 2.4.7), aligning the upstream ask with the downstream +20 confidence factor that already scored them; decorative emoji dropped from the focus list
pi-fact-check — Step 2's existing impact assessment now travels: [HIGH-IMPACT] claim markers direct deeper multi-angle search before settling on UNVERIFIABLE; key findings quote the source's own sentence where possible (strengthens Step 4.5 content-match validation); Today is <date> injected (agy date awareness not guaranteed); batch=2 annotated as pre-agy tuning pending re-measurement
pi-research — new strict anti-hallucination block: never construct/complete/guess URLs; claims from training data must be marked [KNOWLEDGE]; version/release-date/breaking-change claims must quote the exact source sentence or be marked [LOW-CONFIDENCE] (a fabricated quote+URL pair is far harder to produce than a plausible paraphrase). New Step 4.5 source validation ported from pi-fact-check: up to 5 Gemini-sourced URLs WebFetch-verified before synthesis, quote-existence checked, >50% failure poisons all unsampled Gemini URLs to (unverified). Multi-angle search directive replaces bare "in-depth research"; solution-comparison framing relaxed for non-selection topics; date injection
pi-ui-design — Tailwind CSS v3 Play CDN (cdn.tailwindcss.com) → v4 browser CDN (cdn.jsdelivr.net/npm/@tailwindcss/browser@4) with @theme CSS-first config written into the prompt (v4 has no JS config object — the old <script> extend block was v3-only); WCAG 2.2 AA baseline requirements (alt text, form labels, focus states, contrast); viewport meta made explicit; output-purity rule (HTML only, starting at <!DOCTYPE html>, no fences); Claude post-processing extended to v3-era class renames and the ASSUMPTION-comment audit; spec-generation prompt capped at one page

Changed (docs)

README.md + README.zh-TW.md — FAQ format-fallback answer updated from emoji/score to severity-tag/verdict wording; pi-ui-design description notes Tailwind v4
checksums.sha256 — regenerated for all 10 command files

v0.15.1 (2026-07-15) — agy 1.1.2 compatibility fix + ARG_MAX guard

Changed (agy 1.1.2 compatibility)

scripts/call-gemini.sh — prompt delivery migrated from stdin pipe to -p arg — agy 1.1.2 changed -p semantics: the flag value is now treated as the prompt directly and stdin is ignored. Prompt delivery changed from printf '%s' "$PROMPT" | agy -p " " to agy -p "$PROMPT" < /dev/null. The < /dev/null isolates stdin so agy does not hang on inherited non-EOF file descriptors from Claude Code subshells. call-codex.sh is unaffected (codex uses printf | codex exec ... - stdin pipe)
README.md + README.zh-TW.md — model examples updated to agy display-name format — agy 1.1.2 model catalog uses display names with spaces and parentheses (e.g. Gemini 3.5 Flash (Medium)) instead of slugs (gemini-3-flash-preview). Environment variable table, shell profile examples, FAQ, and per-invocation -m examples all updated; agy models / codex doctor hints added
scripts/call-gemini.sh + scripts/call-codex.sh — "Keep in sync" annotations updated — exec block comments now document the prompt delivery divergence (gemini: -p arg; codex: stdin pipe) while noting that remaining blocks (timeout/heartbeat/first-byte/OUT_TMP) still mirror

Added

scripts/call-gemini.sh — ARG_MAX 120KB size guard — -p "$PROMPT" is subject to OS execve limits (macOS ~1MB, Linux ~128KB per-arg). Guard at 120,000 bytes fires before exec with structured PROMPT_TOO_LARGE error + log. No workaround until agy adds --prompt-file or stdin mode. call-codex.sh unaffected (stdin pipe has no ARG_MAX limit)

v0.15.0 (2026-06-18) — Gemini provider migrated to agy (Antigravity CLI)

The Gemini provider's call-gemini.sh now drives agy (Antigravity CLI) over Google AI Pro OAuth, shipped on the June 18, 2026 @google/gemini-cli sunset date. The wrapper keeps its filename and [gemini] log tag for log-contract continuity, and adds rc=0 content classification to catch agy's silent network/auth failures (empirically verified against agy 1.0.6–1.0.9). This release also wires the full 62-scenario smoke suite into CI behind a tag/package.json version-sync gate, and bundles the pi-plan synthesis checkpoint + conflict-resolution mechanisms adapted from compound-engineering's ce-plan.

Changed (Gemini provider — agy migration)

scripts/call-gemini.sh migrated from Gemini CLI to agy (Antigravity CLI) (1617e14) — ahead of the 2026-06-18 @google/gemini-cli sunset. Binary resolve agy + AGY_BIN env (GEMINI_BIN honored as deprecated fallback with WARN); model flag -m → --model passthrough; --print-timeout TIMEOUT_S+30s keeps the wrapper soft-timeout firing first. New rc=0 content classification: agy 1.0.6/1.0.7 swallow network failures (rc=0, empty output) and auth failures (rc=0, OAuth prompt on stdout) — classified as EMPTY_OUTPUT / AUTH_ERROR from output content (empirically verified 2026-06-10). Smoke E1-E7 all pass on agy 1.0.7. Filename and [gemini] log tag kept for log-contract continuity
README.md + README.zh-TW.md synced to the completed agy migration — Prerequisites table now installs Antigravity CLI (curl -fsSL https://antigravity.google/cli/install.sh | bash) instead of the sunset @google/gemini-cli; the two pre-migration notice blocks (2026-03-25 routing update, 2026-05-19 "migration under evaluation" transition notice) replaced by a single completed-migration block stating what stays (script name, [gemini] log tag, GEMINI_MODEL) and what changed (OAuth-only auth, AGY_BIN with GEMINI_BIN as deprecated alias). Environment-variable table drops GEMINI_API_KEY (no longer read by the wrapper) and documents AGY_BIN / deprecated GEMINI_BIN; FAQ slow-response entry now covers agy's rc=0 empty-output auth symptom; architecture diagram, Tech Stack, and Project Structure labels updated from "Gemini CLI" to "agy (Antigravity CLI)"

Added (CI — smoke tests actually run)

.github/workflows/smoke-test.yml — new workflow running the full tests/smoke-test.sh suite (62 scenarios) on every PR and push to main. The suite was CI-ready by design (wrapper logic tests inject fake binaries via CODEX_BIN / AGY_BIN; CLI availability checks degrade to SKIP — verified 58 pass / 0 fail / 3 skip in a clean no-CLI environment) but had never been wired into CI: release.yml's "smoke test" step was a file-existence loop only, so logic regressions (timeout layers, log rotation, classifiers) could reach a release undetected
release.yml — real smoke tests + tag/package.json version sync gate — the file-existence loop is replaced by ./tests/smoke-test.sh (file presence remains covered by the checksum verify + tarball steps), and a new step fails the release when the pushed tag does not match package.json version, closing the third same-shape manual-sync gap (after the two checksum regeneration misses)

Added (pi-plan synthesis mechanisms)

commands/pi-plan.md — synthesis checkpoint + conflict resolution (a650072) — three mechanisms adapted from compound-engineering's ce-plan, scoped to pi-plan's cost structure (external provider calls run 1–9 minutes, so misread tasks are expensive):
- Step 3.5 synthesis checkpoint — Stated / Inferred / Out-of-scope bucketing before provider dispatch; pauses for user confirmation only when an Inferred assumption would change the prompt's direction (max 3 call-outs, each judgeable without reading code)
- Architect prompt requires a rejected alternative with reasoning — synthesis can tell genuine agreement from coincidence; providers that omit it count as unreasoned agreement (weaker signal)
- Step 6 conflict resolution principles — repo-grounded beats generic, official docs beat speculation, agreement must be reasoned. Plan template gains an as-needed Out of Scope section
commands/pi-research.md — divergence ruling in merge rules (a650072) — official sources beat secondary commentary; version / breaking-change / API-stability claims require cross-verification against an official source before being reported as fact, else marked (unverified)

Fixed

EMPTY_OUTPUT classifier alignment across docs (a528d5a) — the agy migration added EMPTY_OUTPUT to call-gemini.sh but only pi-ask-gemini.md mentioned it. Aligned the remaining six command docs (pi-plan / pi-askall / pi-multi-review / pi-research / pi-ui-review / pi-ui-design) and the README graceful-degradation lists; checksums.sha256 regenerated. Codex-only lists untouched (call-codex.sh has no EMPTY_OUTPUT)

v0.14.6 (2026-05-20) — Phase A2 first-byte detector + supply-chain hardening

Tri-state first_byte_method field (measured / fallback / na) shipped to forensic log lines, letting downstream consumers mechanically filter race-fallback samples before treating first_byte_ms as a latency signal. Bundled with the supply-chain hardening that landed on main between releases (third-party GitHub Actions immutable-SHA-pinned + Dependabot enabled), a per-skill timeout calibrator (scripts/calibrate-timeout.sh), and an Antigravity CLI transition notice pre-disclosed in Prerequisites ahead of the June 18, 2026 Gemini CLI cutoff.

Added (Phase A2: first-byte detector tri-state)

scripts/call-codex.sh + scripts/call-gemini.sh — per-invocation detector subshell polls $OUT_TMP and writes the unix-ts to a marker file on first non-empty observation. Main shell reads the marker after wait to compute first_byte_ms and emit a three-state first_byte_method field in both success and soft_timeout end-log lines:
- measured — detector observed the first byte mid-stream; first_byte_ms is the true upstream first-byte arrival time
- fallback — wrapper finished too fast for the 1s detector poll (race fallback); first_byte_ms carries an end-time approximation, not first-byte time. Downstream stats consumers must filter these out before computing latency percentiles
- na — output never arrived (pure stall / Mode A); first_byte_ms is NA
_first_byte_meta() helper — dual-global assignment (FIRST_BYTE_MS + FIRST_BYTE_METHOD) on every codepath, no fallthrough. Detector subshell + helper both gate on [[ -f && -s ]] (different times, different invariants — load-bearing semantic duplication)
Security hardening (OWASP A08 + AI-vuln #13, Medium) — TOCTOU symlink race between mktemp return and detector's first write closed. Bash > calls open(2) without O_NOFOLLOW, so a swap-by-symlink in a world-writable TMPDIR would redirect writes to an attacker-chosen path. Mitigated by replacing per-file mktemp ... claude-prism-first-byte.XXXXXX with per-dir mktemp -d ... claude-prism-fb.XXXXXX (mode 0700) + fixed /ts inside. Sticky-bit /tmp + 0700 dir blocks other-user unlink, and the marker file does not exist until the detector writes it (no pre-existing file to swap)

Added (Tooling — `scripts/calibrate-timeout.sh`)

Per-skill timeout calibrator — reads ~/.claude/logs/multi-ai-YYYY-MM.log (cross-month, excludes symlink / archive), computes per-skill p99 / median / suggested timeout with class-aware clamping. Class mapping frozen from v0.14.4 + commit 71f997d: heavy class (pi-askall, pi-fact-check, pi-plan, pi-multi-review, pi-code-review) floor 480s / ceiling 540s; small class (pi-ask-codex, pi-ask-gemini, pi-research, pi-ui-design, pi-ui-review) floor 240s / ceiling 300s
Formula: clamp(floor, ceiling, ceil(p99 × 1.15 / 10) × 10). N<5 sticks with current (low-confidence guard); ERROR pids excluded
Default reports only; --apply updates commands/pi-*.md TIMEOUT in place. Uses only macOS built-ins (grep / awk / sort / mktemp / shopt) — no jq / python

Changed (Supply-chain hardening — SHA pin + Dependabot)

All .github/workflows/*.yml (PR #4 bf9843e) — third-party actions migrated from mutable tags (@v5, @2.0.0) to immutable 40-char SHA pin format owner/action@<sha> # vX.Y.Z (SHA is the source of truth; version comment is for humans). Affected: actions/checkout (4 workflows), actions/setup-node (1 workflow), ludeeus/action-shellcheck (1 workflow). Mitigates supply-chain risks like the Mini Shai-Hulud-class mutable-tag retag attacks
.github/dependabot.yml (PR #4) — new file enabling Dependabot version updates for the github-actions ecosystem, weekly schedule, root directory. PR-based human review remains the merge gate
actions/checkout v5.0.1 → v6.0.2 (PR #5 fe3539e, Dependabot-generated) — 4 workflow files. v6 breaking change: persist-credentials store path moved to $RUNNER_TEMP. Prism workflows do not perform post-checkout credential operations, so no breaking impact
actions/setup-node v5.0.0 → v6.4.0 (PR #6 72aedd5, Dependabot-generated) — release.yml only. v6 breaking change: devEngines.runtime now preferred over engines.node for node-version-file. Prism uses explicit node-version: '24', so no breaking impact

Added (Documentation — Antigravity CLI transition notice)

README.md + README.zh-TW.md — Antigravity CLI transition notice block in Quick Start → Prerequisites, immediately following the existing March 25, 2026 Gemini CLI service update warning. Discloses: (a) Gemini CLI cutoff date 2026-06-18 for AI Pro / Ultra / free Code Assist users (Enterprise license unaffected); (b) claude-prism wrappers remain functional through the cutoff; (c) Antigravity CLI (agy) ships as a TUI — current call-gemini.sh stdin-pipe + stdout-capture pattern is not compatible; (d) migration paths under evaluation (wait for agy headless flag / switch to Gemini API HTTP / deprecate gemini provider), evaluation kicks off the week of 2026-05-25. Sources: Google Developers Blog transition post + Antigravity CLI repo
Pattern rationale: surfaces the change inline where users actually look for Gemini CLI install instructions, not buried in a separate migration doc

Fixed

ShellCheck SC2206 in scripts/calibrate-timeout.sh (8d05960) — LOG_FILES=( $LOG_GLOB ) pattern intentionally relies on word splitting + globbing (guarded by shopt -s nullglob). Marked with # shellcheck disable=SC2206 # intentional glob expansion; nullglob handles no-match case so CI stops flagging
Dead FIRST_BYTE_MS="" / FIRST_BYTE_METHOD="" pre-assignments before _first_byte_meta() (013ac19) — helper assigns both globals unconditionally on every codepath, so the paranoia init was dead writes. Cleaned up across both wrappers
Smoke T14.3 regex tighten (013ac19) — first_byte_ms=[A-Za-z0-9]+ → first_byte_ms=(NA|[0-9]+). Old class silently passed drift values like Inf / null / aBc123; new pattern enforces the actual contract (numeric integer OR literal NA)

Testing

tests/smoke-test.sh — T14.3 + T14.4 upgraded to tri-state regex; T16.1-T16.7 added (short-success / long-success / pure stall / mid-stall / gemini mirror / marker cleanup contract / vocab strictness). 51 → 60 tests, all pass
ShellCheck CI green at 3f748fa (run 26105637358, 17s)

Notes

Phase A2 detector subshell is patch-isomorphic with the v0.14.0 six-layer soft-timeout defense (provider-string differences only between call-codex.sh and call-gemini.sh). The byte-sync wrapper invariant from v0.14.x is preserved
Phase A3 deferred — race-fallback ms-precision improvements wait until real-CLI tri-state distribution data accumulates (first_byte_method=measured proportion vs fallback vs na)

v0.14.5 (2026-05-11) — codex-cli 0.130.0 sandbox interface drift fix + small-skill timeout calibration

Resolves a 0-second failure in pi-* skills when invoked from non-git-repo working directories. codex-cli 0.130.0 dropped none from --sandbox <SANDBOX_MODE>'s [possible values] list and added an independent "trusted directory" check that refuses to run outside a git repo for any sandbox mode unless --skip-git-repo-check is passed. The wrapper's legacy read-only → none downgrade path produced invalid value 'none' for '--sandbox' and exited at argument validation — silently breaking pi-askall etc. when cwd was /tmp or any other non-repo directory. Bundled with three accumulated timeout calibration fixes since v0.14.4.

Fixed (codex sandbox interface drift)

scripts/call-codex.sh — replace sandbox-value downgrade with --skip-git-repo-check flag. Introduce SKIP_GIT_CHECK=false default; the git_check block now sets SKIP_GIT_CHECK=true (instead of mutating SANDBOX), and the codex exec command conditionally appends the flag. Sandbox stays read-only (preserves Q&A intent — no writes); the new flag solves the trusted-directory check independently
--sandbox validator + diag — valid-list realigned to codex 0.130.0 (read-only | workspace-write | danger-full-access). Previous read-only | sandbox | none had all three values drifted from the actual CLI surface. SANDBOX error diagnostic now suggests --sandbox workspace-write for Q&A instead of the invalid none
Log schema — invoke line gains skip_git_check=$SKIP_GIT_CHECK field for forensic attribution of which path the wrapper took per call

Fixed (skill caller export + timeout calibration since v0.14.4)

CLAUDE_PRISM_CALLER export across all 13 wrapper invocations (commit 71f997d) — v0.14.4 added wrapper-side read but skill-side export was missed; 3-day log analysis (35 invokes, 100% caller="unknown", 4 soft_timeout) surfaced the gap. Future grep can now partition per-skill p99
Per-skill CLAUDE_PRISM_TIMEOUT split (commit 71f997d) — empirical p99=255s on 44 v0.14.4-onward successes means ~36% of real invocations need >110s; all 4 observed soft_timeouts sat on small skills inheriting the 110s default. Split: 7 small-Q&A skills → 300s (p99=255s + 18% buffer); 3 heavy skills (pi-plan, pi-multi-review, pi-code-review) keep 540s
pi-askall + pi-fact-check promoted 300s → 540s (commit 6de0666) — both run multi-batch / multi-provider workloads where individual calls already approach 300s on real traffic. Aligned with the three heavy skills
pi-research + pi-fact-check Bash tool timeout aligned to 600000ms (commit 0b95f7a) — body text had drifted to obsolete 90s/90000ms, shorter than the inner CLAUDE_PRISM_TIMEOUT (300/540), which would hard-kill before the wrapper soft-timeout could fire a structured error

Testing

tests/smoke-test.sh Test 11 rewritten — drift-proof. The prior assertion grepped sandbox downgraded to 'none' in dry-run output, treating the wrapper-internal string as spec while silently masking the actual bug (codex CLI rejecting none). New form asserts (a) --skip-git-repo-check appears in dry-run output, and (b) wrapper's --sandbox <value> is in codex exec --help's [possible values: ...] list. The (b) assertion catches future codex CLI rename / removal of sandbox modes that would otherwise reproduce this class of silent breakage
All 53 smoke tests pass; shellcheck clean on wrappers
End-to-end verified: cd /tmp && call-codex.sh "..." now returns real codex response (previously 0-second invalid value 'none' exit at arg validation)

Notes

Root cause + L4 reflection stored to ccRecall (#117, discovery) — wrapper-layer hardcode of external CLI sub-parameter values (vs flag names) is a structural drift risk. call-gemini.sh escaped only because Gemini has no equivalent sub-mode concept. Future wrappers that hardcode external CLI sub-values must pair a drift-proof smoke check
No new feature: patch release. The four bundled fixes are all bug-class — sandbox interface drift, missing caller export, undersized small-skill timeout, drifted Bash-tool timeout

v0.14.4 (2026-04-29) — Log forensic fields + monthly rotation + sub-agent timeout default

Forensic-level observability for silent-kill diagnosis, automatic monthly log rotation, and a CLAUDE_PRISM_TIMEOUT=540 default for review/plan sub-agent skills. Solves the "wrapper SIGKILL leaves no trace" blindness from the Claude Code 2026-04+ auto-background regression by recording per-invocation cwd / caller / cc_ver plus 30-second heartbeats so the last alive line approximates the death moment when the EXIT trap can't run.

Added (Phase A1: Log Forensic Fields)

scripts/call-codex.sh / scripts/call-gemini.sh — invoke line gains caller="..." (env CLAUDE_PRISM_CALLER), cwd="..." (sanitized via tr -d '\n"' to defend against log injection / quote escape), and cc_ver="..." (read from harness-provided AI_AGENT env-var; unknown outside Claude Code) fields. Enables per-project / per-session attribution that the previous single-line invoke ppid=N stage=entry couldn't provide
30s heartbeat subshell writes [DEBUG] [pid=N] alive elapsed_s=N bytes=N lines while the wrapper pipeline runs. Two diagnostic purposes:
1. Stall onset detection — bytes count per heartbeat reveals where the upstream froze (e.g. bytes stuck at N for 60s = stalled at second 30)
2. Silent-kill death-time estimate — when Claude Code SIGKILLs the wrapper (uncatchable, EXIT trap doesn't run, no success / soft_timeout / signal log), the last heartbeat ≈ death moment within ±30s
DEBUG level keeps heartbeat out of default grep -E '\[(INFO|WARN|ERROR)\]' view; forensic queries use grep 'pid=N' multi-ai*.log for full timeline
EXIT trap kills the heartbeat subshell PID (no orphan process; ad-hoc verified post-timeout)
success / soft_timeout ERROR end lines gain elapsed_s=N + first_byte_ms=NA placeholder. Real first_byte_ms tracking deferred to Phase A2 (requires watcher refactor for byte-level stream sampling)

Added (Phase B: Monthly Log Rotation)

scripts/call-codex.sh / scripts/call-gemini.sh — write to multi-ai-YYYY-MM.log (UTC month) instead of single multi-ai.log. Year-scale storage scaling: 472KB / 2 months → ~10-15 MB/year split across 12 files
multi-ai.log becomes a symlink to current month so analyze-log.sh / usage-summary.sh / external greppers see "latest view" transparently with no tool changes
One-time migration on first run: pre-rotation regular file archives as multi-ai-archive-pre-rotation.log via mv -n (BSD-safe; concurrent wrappers race-losing see no-op since source already moved). Symlink atomic via ln -sf (POSIX rename). Production migration verified during dev cycle: 485KB pre-rotation log preserved intact, no data loss
Historical query: grep ... ~/.claude/logs/multi-ai-*.log glob

Changed (sub-agent timeout default)

commands/pi-plan.md / pi-multi-review.md / pi-code-review.md — sub-agent / direct call gains CLAUDE_PRISM_TIMEOUT=540 env-var prefix on ~/.claude/scripts/call-codex.sh invocation. 60s buffer below the documented Bash tool 600s ceiling so wrapper soft-timeout fires first (preserving structured rc=124 + sentinel + soft_timeout log event) before the harness force-kills. Real-world trigger: pi-plan elapsed 6m 2s (362s, > previous 110s wrapper default) on 2026-04-29 confirmed the 110s default was systematically too tight for adversarial review / architectural plan workloads
Inline rationale comment above each invocation explaining 540 vs 600 semantics + Keep in sync: pi-plan.md, pi-multi-review.md, pi-code-review.md marker (mirrors v0.12.6 wrapper byte-sync convention so future maintainers can't drift one file independently)
Not changed: pi-askall.md (Q&A simple-query workload dominant; 110s default appropriate; sync marker explicitly excludes per design decision). pi-research.md has a separate Bash-tool-side timeout=90000 conflict (90s outer < 110s inner) — left for a separate fix

Fixed

scripts/usage-summary.sh — set -e + pipefail was killing the sum pipeline when LINES lacked a provider tag (first grep '\[gemini\]' rc=1 on no match → pipefail propagates → set -e exits with no output). Disabled pipefail in the sum section; awk's END always prints 0 so missing matches naturally yield 0. Latent bug since pipefail was added; revealed by T6 LOG_DIR isolation refactor (rotation made the prod log a symlink to a fresh empty month file, exposing the [gemini]-absent code path)

Testing

Smoke 43 → 51 (+8 cases):
- T14.1-T14.4 (Phase A1 observability): codex/gemini invoke fields + success-line elapsed_s + first_byte_ms end fields + soft_timeout ERROR first_byte_ms
- T15.1-T15.4 (Phase B rotation): fresh-dir creation, archive migration of pre-existing regular file, re-run idempotency (no double-archive), gemini wrapper mirrors codex
- T6 refactor: isolated LOG_DIR + fake-fast CLI to make usage-summary deterministic post-rotation
All 51 pass; shellcheck clean on all wrappers
/gogo quality pipeline ran clean before tag (Step 1 codex review: 1 finding, score 100, fixed; Step 2 simplify: 1 item, fixed; Step 3 security: 0 ≥Medium; Step 4 final verify: PASS)

Notes

Caller env-var contract: CLAUDE_PRISM_CALLER is optional; sub-agent skills should set it to sub-agent (or descriptive label) so log forensics can distinguish direct main-conversation Bash vs sub-agent fan-out paths. Current sub-agent templates do not yet propagate this — future enhancement
Migration is idempotent: re-running wrappers after upgrade leaves the archive file untouched (mv -n no-ops once source is gone) and keeps refreshing the symlink to current month. Cross-month transitions (e.g. May 1) automatically create the new month file and update the symlink

v0.14.3 (2026-04-28) — Phase 2: `CLAUDE_PRISM_OUT_TMP` env-var contract + stall observability

Resolves v0.14.2 Known Limitation for sub-agent fan-out skills. Callers (skill layer) pre-allocate a mktemp path via CLAUDE_PRISM_OUT_TMP env-var; the wrapper writes directly to that path and the shared pi-{codex,gemini}-last.out symlink is not updated (legacy-mode only). Skill-side fallback now reads the caller-owned path — no cross-session race. Known Limitation partially preserved: the 7 direct skills (pi-ask-codex, pi-ask-gemini, pi-code-review, pi-fact-check, pi-research, pi-ui-design, pi-ui-review) keep the shared-symlink legacy fallback in their narrative instructions. Low-frequency silent-hallucination risk (no cross-provider verification safety net in direct skills) — not rewritten because the 7-skill narrative-update cost was disproportionate to an unobserved-in-production risk.

Changed

scripts/call-codex.sh / scripts/call-gemini.sh — OUT_TMP accepts CLAUDE_PRISM_OUT_TMP env-var override (defaults to mktemp in LOG_DIR if unset). Symlink update wrapped in if [ -z "${CLAUDE_PRISM_OUT_TMP:-}" ]: legacy mode preserves v0.14.2 behavior; env-var mode skips symlink since the caller owns the path. Byte-sync contract between the two scripts preserved
commands/pi-askall.md / pi-plan.md / pi-multi-review.md — sub-agent Bash template creates per-invocation OUT_PATH=$(mktemp "${TMPDIR:-/tmp}/prism-{codex,gemini}-out-XXXXXX") and prefixes wrapper call with CLAUDE_PRISM_OUT_TMP="$OUT_PATH". Fallback cat reads $OUT_PATH, not the shared symlink. Gemini substitution list gains a new rule: replace prism-codex-out → prism-gemini-out in the mktemp template
Explicit / separator in ${TMPDIR:-/tmp}/prism-... — mirrors wrapper's ${TMPDIR:-/tmp}/claude-prism-timeout.XXXXXX pattern. Avoids malformed paths on systems where $TMPDIR has no trailing /

Security / Concurrency

Eliminates cross-session same-provider fallback wrong-file selection for sub-agent fan-out skills. v0.14.2 behavior: concurrent same-provider invocations each own a mktemp file but share one symlink; if Claude Code auto-bg silences stdout and a skill falls back to cat-ing the symlink, it may read another session's output. Now: sub-agent skills pass their own mktemp path via env-var; wrapper writes there directly; skill reads its own file
Preserved Known Limitation — direct skills' narrative fallback ("If Bash returns empty, read pi-{codex,gemini}-last.out") still uses the shared symlink. Two concurrent Claude Code sessions using the same direct skill on the same provider can theoretically cross-read. Low-frequency (requires auto-bg + empty-stdout + same-provider + time overlap); unlike pi-multi-review, direct skills have no cross-provider verification (references_exist_in_codebase -50pt signal) to catch hallucinated references from wrong-file content

Observability

scripts/call-codex.sh / scripts/call-gemini.sh — soft-timeout ERROR log line gains an output_bytes=N field. 0 distinguishes upstream stall (no byte received before kill) from >0 slow-but-progressing — enables triage between transient codex/OpenAI/network stall and structural latency issues without re-running the same prompt. Computed as wc -c < "$OUT_TMP" guarded by [ -f ] (rejects FIFO / device / blocking-symlink paths that a Phase 2 env-var caller could supply, which would otherwise re-hang the wrapper at the diagnostic step). tr -d ' \n' sanitization closes OWASP A09 log-injection vector (BSD wc may emit leading \n; matches existing err_text_safe prior art elsewhere in the same file)

Testing

internal/experiments/phase2-cross-session-race/run.sh — fake-CLI harness (fake-codex, fake-gemini) + 2 race scenarios (same-session concurrent + cross-session concurrent) × 2 providers × 2 Bash versions (5.3.9 Homebrew + 3.2.57 macOS system). All 32 assertions pass: OUT_A and OUT_B get separate non-empty distinct content; shared symlink is not created in env-var mode ([ -z ... ] gate honored)
Smoke suite unchanged at 43/43 passing; scripts/call-{codex,gemini}.sh shellcheck clean
Observability patch validation: FIFO smoke (caller supplies mkfifo path → wrapper completes in 2.5s, log writes output_bytes=0, no read-block) + full /gogo quality pipeline (codex review → simplify → security lint → final verify) ran clean before tag

Notes

Release policy exception: shipped 2026-04-28 instead of the originally communicated ≥ 2026-05-01 target. Bundled with output_bytes observability patch (single soak window covers both)
BSD mktemp -t quirk discovered in precheck: mktemp -t <prefix> on BSD leaves XXXXXX as literal, not a placeholder (produces prism-test-XXXXXX.RANDOM). Sibling skills (pre-Phase 2) use this form with literal XXXXXX in filenames as a known quirk; Phase 2 sidesteps this with mktemp "${TMPDIR:-/tmp}/prefix-XXXXXX" absolute-template form (XXXXXX replaced correctly)
Not changed: wrapper's EXIT trap (still doesn't rm "$OUT_TMP" — contract strengthens in env-var mode since the path is caller-owned). Legacy-mode symlink behavior unchanged when env-var unset

v0.14.2 (2026-04-24)

Wrapper: per-invocation OUT_TMP + atomic symlink. Eliminates byte-level tee interleaving on the safety-net log file (pre-existing MEDIUM-severity finding). When two sub-agents or two Claude Code sessions invoke the same provider simultaneously, each gets its own mktemp-named output file; pi-{codex,gemini}-last.out becomes an atomic symlink to the latest invocation. The 10 pi-* skills are unchanged — the symlink is transparent to cat. Known limitation: this fix closes byte-level corruption; it does not solve fallback file-selection under concurrent same-provider invocation — the shared pi-*-last.out symlink still points to the last writer, so a skill that falls back to cat it may read another concurrent invocation's response. See Notes for the deferred env-var OUT_TMP contract that resolves this.

Changed

scripts/call-codex.sh / scripts/call-gemini.sh — OUT_TMP now points to a per-invocation mktemp "${LOG_DIR}/pi-{codex,gemini}-last-XXXXXX" file. After wait "$LAST" completes, ln -sf "$(basename "$OUT_TMP")" "${LOG_DIR}/pi-{codex,gemini}-last.out" atomically updates the stable path to the newest file. The ln -sf runs after wait (so the target is fully written) and is not conditioned on rc — partial output from soft-timeout or error paths still reaches the skill diagnostic fallback. Byte-sync mirror between the two scripts preserved; Keep-in-sync comment extended to cover the new block

Security

Eliminates byte-level tee interleaving (MEDIUM-severity finding). Prior behavior: concurrent writers to the fixed path ~/.claude/logs/pi-{codex,gemini}-last.out interleaved at the byte level inside tee, corrupting any skill fallback that reads the file after the wrapper exits. The race was latent under v0.12.x because main-conversation Bash is a structural FIFO (empirically N=7, ratio 1.00, zero variance). v0.13.0 sub-agent fan-out introduced genuine parallelism (N=13, median dispatch delta 2.8s), activating the race pathway. After this change, each concurrent invocation owns its own mktemp file; byte-level interleaving is impossible
Remaining exposure — cross-session same-provider fallback file-selection: the pi-{codex,gemini}-last.out symlink is a single stable pointer, "last ln -sf wins". If two Claude Code sessions on the same machine both invoke the same provider and one of them triggers the empty-stdout fallback, it may cat the symlink and read the other session's response. Frequency is low (requires cross-session + same-provider + empty-stdout concurrently) but non-zero. Mitigation before env-var contract ships: avoid running two Claude Code instances that concurrently use the same provider for unrelated tasks, or rely on sub-agent output fields rather than re-reading the symlink

Testing

Race-regression test — two parallel invocations under controlled fake-CLI fixtures on both Bash 5.3.9 (Homebrew) and Bash 3.2.57 (macOS system), both scripts. All four combinations verified to produce uncorrupted per-file output (exactly one BEGIN/END marker per file) with symlink pointing to a complete file. Test script resides under developer /tmp/ (not shipped — requires fake-CLI injection and a throwaway log dir)
Existing smoke suite unchanged at 43/43 passing. Test 13 soft-timeout regression (6 cases) verified to still pass — ln -sf is placed after wait and before classification, so timeout path still writes the symlink before exiting 124

Notes

Backward-compatible: the 10 pi-* skill fallback reads (cat ~/.claude/logs/pi-{codex,gemini}-last.out) transparently follow the symlink. No skill markdown files changed
Not addressed (deferred): same-provider 3+ fan-out within a single skill. The symlink-points-to-latest model is non-deterministic under 3+ concurrent same-provider invocations. Today's pi-* skills all use 1 Codex + 1 Gemini pairs; when a real 3+ fan-out pattern emerges, migration is an env-var OUT_TMP path-return contract (caller sets OUT_TMP, wrapper respects it, skill reads that specific path). Out of scope for this release
BSD mktemp template: XXXXXX at end of template, no suffix. Matches the pre-existing verified pattern for TIMEOUT_MARKER in call-*.sh
Cleanup of stale pi-*-last-* files is deferred — text logs are ~1–100 KB each; 50 calls/day = ~5 MB/day is not a storage problem. If needed later, cleanup will anchor to install.sh upgrade rather than a hot-path find on every wrapper invocation

v0.14.1 (2026-04-24)

Documentation restructure. Split the 798-line README into a leaner 550-line entry point plus a docs/ tree for deep-dive topics, and surface the empirical research behind the sub-agent fan-out design.

Added

## Empirical Foundation section in both README variants (~80 lines). Summarizes the N=36+ controlled experiments that identified Claude Code's main-conversation Bash tool as a structural FIFO queue (delta/first_exec = 1.00 across 7 runs in two capacity windows) while sub-agent Bash is genuinely parallel (median dispatch delta 2.8s, N=13). Includes a MECE layer behavior matrix and a sequenceDiagram contrasting the anti-pattern vs the sub-agent fan-out design
docs/research/bash-tool-parallelism.md (English, 102-line research summary). Publishes the experiment groups (A/B/C/F/D), the resulting layered conclusions, and the product decisions traced back to the data (sub-agent fan-out, asymmetric commit, rejection of fire-and-forget + polling, v0.14.0 soft-timeout as the next hardening step). Full per-run data and methodology deferred to a separate long-form write-up
docs/ tree with six deep-dive topics (bilingual): observability, ci-cd, cost, supply-chain-security, privacy, reflections. Each exists in native English and Traditional Chinese variants per the bilingual convention — not machine translations

Changed

README.md / README.zh-TW.md both reduced from 798 → 550 lines (-31%). Six heavy chapters (Observability / CI/CD Integration / Cost Estimation / Supply Chain Security / Privacy & Data Flow / Reflections) moved to docs/. The README now focuses on 30-second pitch + 10-minute onboarding; anything beyond that points into docs/
New ## Documentation index section at the end of both README variants lists all docs/ entries with bilingual links

Notes

Runtime behavior, scripts, commands, and checksums.sha256 are unchanged. docs/ is not in the npm files: list, so this release is documentation-only for npm consumers
Internal experiment scaffold (prompts, runner scripts, raw jsonl) remains in the gitignored internal/ directory. Future publication as a reproducible scaffold is deferred

v0.14.0 (2026-04-23)

Soft-timeout wall-clock guard for call-*.sh. Bounds provider-CLI execution to a configurable wall-clock limit so the script exits with a structured marker before the ~130s Claude Code harness watchdog SIGKILLs it silently. Addresses the F-group silent-death signature (N=1/7, evening-bad) identified in the 2026-04-20→21 bg-regression experiments.

Added

CLAUDE_PRISM_TIMEOUT environment variable (integer seconds, range 1..3600; default 110). Invalid values (non-integer, zero, negative, or above 3600) fall back to 110 with a WARN log entry. The upper bound prevents values that macOS BSD sleep rejects, which would otherwise kill the watcher subshell under set -e and silently disable the timeout guard entirely. Power users can widen per-invocation for known-long runs: CLAUDE_PRISM_TIMEOUT=180 ./call-codex.sh "40KB review prompt"
Soft-timeout mechanism in both scripts/call-codex.sh and scripts/call-gemini.sh: background pipeline + watcher subshell + per-invocation marker file. On timeout, the watcher first confirms the pipeline is still alive (kill -0 "$LAST" gate, avoids boundary-race log pollution), then writes the marker, emits a soft_timeout stage=exec elapsed_s=N event to the shared log, and issues pkill -TERM -P $$ to terminate all pipeline members (pipeline members are direct children of the parent shell in Bash's pipeline semantics). Parent's EXIT trap handles KILL-escalation plus marker/temp cleanup. Classification uses rc in {143,137} && [[ -s "$TIMEOUT_MARKER" ]] — the marker is mktemp-unique per invocation, eliminating PID-reuse false positives. Exit code 124 (GNU timeout convention) for external consumers; stderr sentinel [CLAUDE-PRISM: soft-timeout at STAGE=exec after ${TIMEOUT_S}s] for human-readable diagnosis
SOFT_TIMEOUT outcome in scripts/analyze-log.sh — log-event-driven classification via msg ~ /^soft_timeout / match, prioritized over subsequent ERROR / SIGNAL events from the same pid (both of which call-*.sh also emits during teardown). Summary now shows TO Soft-timeout: N alongside the existing OK / ER / SG / !! counters

Security

Strict ISO-8601 timestamp validation in analyze-log.sh:to_epoch (OWASP A03). The awk function previously interpolated $ts (first whitespace-delimited field of each matching log line) into a shell command via cmd | getline. Legitimate log entries produced by _log are always well-formed, but if the log file were externally tampered — e.g. by a local attacker with write access to ~/.claude/logs/, or by a future log writer accepting user-controlled content in field $1 — a crafted "timestamp" like $(touch /tmp/pwned) would execute. Added a strict regex gate (^[0-9]{4}-...Z$) before shell interpolation. Zero false negatives for legitimate entries; adversarial fixtures verified blocked

Testing

Added Test 13 (6 regression cases) to tests/smoke-test.sh using injected fake CLI binaries via CODEX_BIN / GEMINI_BIN env vars — no real API calls, no credentials required. T13.1 codex normal completion (rc=0, no sentinel, and no soft_timeout event in log — the absence-assertion is the boundary-race regression guard); T13.2 codex timeout fires (rc=124 + sentinel + log event); T13.3 custom CLAUDE_PRISM_TIMEOUT=5 honoured within ±2s tolerance; T13.4 no orphan fake-slow-cli processes after timeout fires (process-leak regression guard); T13.5 gemini mirror fires identically to codex (byte-sync contract verification); T13.6 overflow CLAUDE_PRISM_TIMEOUT=9999999999 falls back to 110 with WARN log (macOS BSD sleep bypass regression guard). smoke-test total: 37 → 43

Mechanism design (rationale in `.claude/pi-plans/soft-timeout-call-scripts.md`)

Three provider-proposed mechanisms were refuted by local POC during plan revision:

SIGALRM-to-parent trap does not interrupt foreground pipelines. Bash queues the signal until the shell regains control, so trap '...' ALRM only fires after the pipeline completes naturally — timeout effectively useless. Verified on Bash 5.3.9 + 3.2.57. Fix: background the pipeline with & so wait is interruptible; use a watcher subshell instead of parent trap
rc=124 cannot drive analyzer classification because analyze-log.sh doesn't inspect exit codes — it matches log message patterns. SOFT_TIMEOUT is therefore log-event-driven (cleaner — no cross-layer exit-code leak) while still exiting 124 for external consumers
Killing pipeline middle-stage via $! alone is insufficient. $! captures the last pipeline member (tee), and SIGPIPE does not propagate to middle-stage CLIs that don't write stdout. pkill -TERM -P $$ targets all parent's direct children, which includes every pipeline member

Notes

Mechanism B (Gemini service-side tail event → harness drops output silently) is NOT addressed by this change — that requires skill-layer log fallback, deferred
Byte-sync between call-codex.sh and call-gemini.sh enforced by Keep in sync comment header; future CI lint check to be added (deferred, not v0.14.0 scope)

v0.13.0 (2026-04-23)

Skill layer hardening — sub-agent fan-out + GEMINI_MODEL passthrough. Two related policy changes to the pi-* command surface, both prompted by bg-regression experiment data (N=36+ runs) showing the prior prescription did not deliver its stated guarantee.

Changed

Sub-agent fan-out replaces main-conversation parallel Bash for pi-askall, pi-plan, and pi-multi-review. Main-conversation Bash is a structural FIFO queue — the second parallel Bash waits for the first to finish (delta ≈ first_exec precisely, N=7 across two capacity slots). The v0.12.3 prescription "send two Bash tool calls in a single response" was therefore semantically a no-op: provider calls ran sequentially, not concurrently. v0.13.0 dispatches via two parallel Agent tool calls (subagent_type: "general-purpose"), each invoking its CLI wrapper inside the sub-agent's own Bash — sub-agent Bash dispatches in parallel (median delta 2.8s, N=13). Live POC captured during this release confirms the pattern works. This is primarily a correctness fix (restore parallel semantics); for long provider calls it also saves wall-clock (pi-plan baseline ~156s via fan-out vs ~218s hypothetical FIFO = 28% saved)
Skills no longer set GEMINI_MODEL — the user's shell environment passes through to the sub-agent's Bash, then call-gemini.sh, then the Gemini CLI, with no skill-side override. Previously pi-plan, pi-multi-review, pi-fact-check, and pi-research all wrapped their Gemini call with GEMINI_MODEL="${GEMINI_MODEL_DEEP:-${GEMINI_MODEL:-}}", which gave GEMINI_MODEL_DEEP priority over the user's explicit GEMINI_MODEL choice. The layering looked user-respectful but silently promoted the deep tier whenever GEMINI_MODEL_DEEP was set. If a call fails with RATE_LIMIT / capacity, the skill surfaces the error and leaves the tier decision to the user

Documentation

Dispatch rules preamble in pi-askall, pi-plan, and pi-multi-review replaces the v0.12.3 "Bash invocation rules" notice. Explains why main-conversation parallel Bash fails (FIFO), how sub-agent fan-out differs (separate dispatch layer), and when run_in_background: true still applies (unchanged escape hatch for genuinely-long calls)
GEMINI_MODEL passthrough note in pi-askall spells out the policy so future skill authors don't reintroduce layering

Breaking changes

GEMINI_MODEL_DEEP is no longer read by any skill. Users who set GEMINI_MODEL_DEEP to force the deep tier for pi-plan / pi-multi-review / pi-fact-check / pi-research will, after upgrade, fall through to whatever GEMINI_MODEL is set to (or the CLI's own default if unset). Migration: if you previously set GEMINI_MODEL_DEEP=gemini-3-pro-preview to keep the deep tier for reviews while running Flash for general Q&A, either (a) set GEMINI_MODEL=gemini-3-pro-preview globally and accept the deep tier everywhere, (b) launch Claude Code with the env var set for that session only, e.g. GEMINI_MODEL=gemini-3-pro-preview claude, or (c) leave it unset and let the CLI default apply
Downstream skill authors extending pi-askall / pi-plan / pi-multi-review verbatim must follow the new sub-agent fan-out pattern — the old "two parallel Bash tool calls" prescription is gone

Notes

For end-users who did NOT set GEMINI_MODEL_DEEP, the only behaviour change is "parallel now actually parallel"
pi-fact-check and pi-research make one Gemini Bash call + N WebSearch calls. They don't trigger the two-Bash FIFO, so sub-agent fan-out is not applied there — only the GEMINI_MODEL passthrough change affects them. The Bash + WebSearch queue interaction is untested; a future investigation tied to the call-*.sh soft-timeout work may surface additional changes

v0.12.6 (2026-04-20)

Regression test hardening — lock in the v0.12.3→v0.12.5 stdin fixes with six dedicated test cases so future edits to the stdin block in call-codex.sh / call-gemini.sh fail fast instead of silently regressing.

Testing

Added six stdin regression scenarios to tests/smoke-test.sh (pipe / file redirect / </dev/null × 2 wrappers). Uses exact prompt-length assertions so silent truncation or drop cannot pass the test — the prior > 1 form would have accepted partial-byte loss. Inherited non-EOF fd case intentionally excluded and documented in-line (FIFO is not a valid proxy for the v0.12.3 anonymous-pipe bug shape, and macOS lacks timeout). smoke-test total: 31 → 37
Added # Keep in sync with scripts/call-<other>.sh comments above the shared stdin block in both wrappers, aligning with the existing install.sh / uninstall.sh mirror convention so manual edits carry a visible sync signal

Fixed

EXIT trap for temp dir cleanup in smoke-test.sh regression block — the new Test 12 section created two temp dirs (mktemp -d for fixture + git repo) but relied on a trailing rm -rf for cleanup. Under set -euo pipefail, any error between mktemp and the final cleanup would leak the dirs (including an initialized git repo). Register an EXIT trap immediately after both mktemp -d calls so cleanup runs on success, error, and signal paths alike. OWASP A10 Mishandling of Exceptional Conditions

v0.12.5 (2026-04-20)

Hardening pass on top of v0.12.4 — adversarial review (Codex) and security lint surfaced two issues that complete the stdin attack surface fix.

Fixed

Silent drop of < file.txt redirect input — v0.12.4's stdin guard [[ ! -t 0 && -p /dev/stdin ]] correctly stopped the cat deadlock but narrowed too far: a regular-file redirect (call-codex.sh "..." < diff.txt) is not a FIFO under bash, so the redirected payload was discarded without warning. Broaden the guard to [[ ! -t 0 && ( -p /dev/stdin || -f /dev/stdin ) ]] so any finite EOF-reaching source is consumed; non-EOF inherited fds still skip (preserving the v0.12.4 fix). Verified across pipe / file redirect / </dev/null / no-redirect inheritance
Log injection via unsanitized CLI stderr — _log ERROR "... $err_text" in both wrappers wrote raw subprocess stderr to ~/.claude/logs/multi-ai.log, which lets a crafted prompt fragment echoed back by Codex/Gemini forge log entries (e.g. \n2026-04-20T00:00:00Z [codex] [INFO] [pid=1] fake success). The v0.12.4 stdin guard widening enlarged the attacker-controlled payload surface (file redirect now consumed too), so harden the sink. Strip newlines via tr '\n' ' ' before the _log call. The user-facing Details: stderr echo keeps the raw text — that path is for terminal display, not structured log parsing. OWASP A09 Logging & Monitoring Failures

v0.12.4 (2026-04-20)

Fix stdin pipe deadlock — call-codex.sh / call-gemini.sh no longer hang on cat when invoked without an upstream pipe.

Fixed

stdin pipe deadlock when no pipe present — call-codex.sh / call-gemini.sh previously hung on cat when invoked without a pipe but with an inherited non-TTY stdin (a Claude Code v0.12.3+ subshell behavior surfaced after the auto-background bypass landed). Affected 6 commands across 8 call sites: pi-plan, pi-multi-review, pi-code-review (main path), pi-ui-design (spec-generation step), pi-ask-codex (no-context path), and pi-ask-gemini (no-context path). The fix narrows the stdin guard from [[ ! -t 0 ]] to [[ ! -t 0 && -p /dev/stdin ]] so the script only reads when there's an actual FIFO with a writer that will close. The 8 pipe-based call sites (pi-research, pi-askall, pi-fact-check, pi-ui-review, pi-ui-design HTML generation, pi-code-review long-input mode, pi-ask-{codex,gemini} with-context path) are unaffected.

Documentation

Added "Cache TTL Behavior" section under Observability in both README.md and README.zh-TW.md. Documents Claude Code's current 5-minute prompt cache TTL (applying to all subscribers regardless of Pro or Max tier), the 2026-03-08 Claude Code-wide shift from a 1-hour default back to 5 minutes (see GitHub issue #46829), and clarifies that "Max subscribers automatically receive a 1-hour TTL" is an unverified community claim — Anthropic's official prompt caching documentation does not gate TTL by subscription tier. Non-alarmist informational framing; no preamble, command, or script changes
Sharpened review-insights wording in both README.md and README.zh-TW.md to accurately reflect that Claude (the AI) participates in both writing and reading sides of the JSONL log: at write time Claude interprets Codex/Gemini output (emoji→severity mapping, source inference, ≥80 confidence filter) before appending; at read time review-insights.sh only computes raw counts via jq, with deeper interpretation (trends, root causes) handled by Claude. Replaced passive voice / "automatically records" phrasing across 4 spots — How It Works step 7, the Review Insights section, the bash comment annotation, and the Privacy "What Stays Local" note — so readers don't mistake the pipeline for pure script automation

v0.12.3 (2026-04-18)

Bypass Claude Code auto-background regression — commands and scripts harden against the 2026-04+ regression where Claude Code's auto-background path silently kills child processes (output file stays 0 bytes, ps shows no trace).

Root cause

Claude Code 2026-04+ versions (observed on v2.1.114) changed the auto-background lifecycle: when the runtime decides to background a Bash tool invocation, the child process gets killed instead of detached — the task dir gets a "running" entry but ps aux shows nothing, and output files stay empty because the process never reached the tee write. Explicit run_in_background: true uses a different (working) lifecycle, and foreground synchronous calls are unaffected.

Mitigation

All 10 pi-* commands now include a "Bash invocation rules" preamble directing Claude to call call-codex.sh / call-gemini.sh in foreground synchronous mode with an explicit timeout: 600000 (10-minute ceiling). Explicit &, run_in_background: true, and nohup are forbidden — any path that lets Claude Code decide to background triggers the regression. run_in_background: true remains as an escape hatch for commands genuinely expected to exceed 10 minutes
Parallel provider calls (pi-askall, pi-multi-review, pi-plan) achieve concurrency by sending two Bash tool calls in a single response, each foreground-synchronous, instead of relying on shell-level &

Observability (new)

Lifecycle logging — call-codex.sh and call-gemini.sh gain INVOKE (entry), STAGE (tracks entry → parse_flags → stdin_read → git_check → binary_resolve → exec → done), and SIGNAL (HUP/INT/TERM traps) log events. Every log line now carries a [pid=N] prefix to group events by invocation. SIGKILL is uncatchable, so the absence of a SUCCESS/ERROR/SIGNAL event after an INVOKE is the signature of an auto-background kill
SIGHUP trap replaces silent ignore — the previous trap '' HUP is replaced with trap '_log_signal HUP' HUP. Behavior is unchanged (HUP still doesn't terminate the script), but now the event is recorded
scripts/analyze-log.sh — new utility that reads multi-ai.log, groups entries by pid, and reports each invocation's outcome (Success / Error / Signal / Silent death). Silent deaths point to suspected Claude Code auto-background SIGKILLs. Pre-v0.12.3 log entries (no pid prefix) are skipped

Documentation

Removed "Changing the output language" section from both README.md and README.zh-TW.md. The original guidance had two problems: it biased the example toward a specific language (a public open-source package shouldn't assume its readers' preferred language), and it pointed users at commands/*.md files that ./install.sh overwrites on every upgrade — so the customization wouldn't persist anyway. A proper mechanism (likely an env var) is deferred to a future release
Added "Invocation Diagnostics" section under Observability in both README variants, documenting analyze-log.sh usage, the four outcome categories (SUCCESS / ERROR / SIGNAL / SILENT), and how SILENT deaths signal Claude Code auto-background SIGKILL events

v0.12.2 (2026-04-11)

Background fallback — all 10 commands now recover from Bash tool backgrounding.

Fallback read instructions — every pi-* command prompt now includes a fallback directive: if the Bash tool was backgrounded or returned empty output, Claude reads the result from ~/.claude/logs/pi-{codex,gemini}-last.out (persisted by the script's tee safety net since v0.11.4/v0.12.0)
Completes the three-layer defense against background output loss: script-level tee streaming (v0.11.4) → file persistence (v0.12.0) → command-level fallback read (v0.12.2)

v0.12.1 (2026-04-07)

Community — added contributing guide and code of conduct.

CONTRIBUTING.md — development setup, code standards (Bash 3.2+, ShellCheck), testing, commit convention, PR process, and contribution boundaries (what we accept / don't accept)
CODE_OF_CONDUCT.md — Contributor Covenant 2.1
README updates — added Contributor Covenant badge and Contributing section to both README.md and README.zh-TW.md

v0.12.0 (2026-04-03)

Adversarial review upgrade — review prompts redesigned from neutral "Senior Reviewer" to adversarial stance with divided attack surfaces, inspired by codex-plugin-cc concepts (Apache 2.0).

Adversarial review prompts

pi-code-review — Codex prompt upgraded to adversarial stance: "break confidence in the change, not validate it." 9-category attack surface (auth, data loss, race conditions, rollback safety, edge cases, schema drift, observability, annotation compliance, guideline compliance), finding bar (every finding must answer what/why/impact/fix), calibration rules ("prefer one strong finding over several weak ones"), and final self-check
pi-multi-review — both provider prompts upgraded to adversarial with divided attack surfaces: Codex attacks security & data integrity (7 categories), Gemini attacks design, UX & maintainability (7 categories). Aligns with existing domain-aware weighting (Codex → backend authority, Gemini → frontend authority)
Consistent filtering — "DO NOT flag" criteria unified across all three prompts (including lint-ignore/noqa/@ts-ignore exclusion)

Output persistence safety net

Last-run output files — call-codex.sh and call-gemini.sh now persist output to ~/.claude/logs/pi-codex-last.out and pi-gemini-last.out (fixed paths, not temp files). Files survive script exit as a fallback if stdout is lost during background execution
Builds on v0.11.4's tee streaming fix — stdout remains the primary output channel; file persistence is the safety net

v0.11.4 (2026-04-03)

Fix: streaming CLI output to prevent background execution data loss

Streaming output

RESULT=$(...) → tee streaming — call-codex.sh and call-gemini.sh no longer buffer the entire CLI response in a shell variable. Output now streams directly to stdout via tee, so callers that background the script (e.g. Claude Code Bash tool auto-backgrounding) can capture output in real time instead of seeing 0 bytes
SIGHUP survival — added trap '' HUP to both wrapper scripts so they survive terminal detach when backgrounded, preventing silent process death
bash 3.2 compat (error path) — ${err_text,,} in installed scripts now uses printf | tr (matching the v0.11.3 repo fix that hadn't been re-installed)

v0.11.3 (2026-03-29)

Fix: macOS bash 3.2 compatibility — error classification no longer breaks on stock macOS bash.

Bash compatibility

${var,,} → tr replacement — call-codex.sh and call-gemini.sh error classification used bash 4+ lowercase syntax (${err_text,,}), which causes bad substitution on macOS built-in bash 3.2. Replaced with POSIX-compatible printf | tr '[:upper:]' '[:lower:]'
Only affects the error path (CLI call failure); normal execution was never impacted

v0.11.2 (2026-03-29)

Fix: pi-ui-review stdin pipe — large code reviews no longer silently fail.

Stdin pipe migration

/pi-ui-review stdin pipe — code content moved from shell argument to stdin pipe, matching the v0.9.6 standard used by all other commands. Previously, large frontend code reviews caused call-gemini.sh to return 0 bytes silently due to ARG_MAX limits and shell metacharacter expansion in run_in_background mode
Historical review comments via stdin — Step 1.7 PR comment context also routed through stdin to avoid argument overflow on repos with extensive review history

v0.11.1 (2026-03-27)

Model Tier Override — two-tier model setup for heavy-reasoning commands.

Model tier override

GEMINI_MODEL_DEEP env var — new environment variable for selecting a higher-tier Gemini model on heavy-reasoning commands. Falls back to GEMINI_MODEL, then CLI default — zero behavioral change for existing setups
Four commands upgraded — /pi-fact-check, /pi-research, /pi-multi-review, and /pi-plan now use GEMINI_MODEL_DEEP when set, automatically routing to Gemini Pro for deep reasoning while keeping Flash as the fast default for other commands
Nounset-safe — parameter expansion uses ${GEMINI_MODEL_DEEP:-${GEMINI_MODEL:-}} to avoid set -u breakage in strict shell environments

v0.11.0 (2026-03-27)

Provider Resilience — dual-track research, structured error diagnostics, and graceful degradation across all commands.

Driven by Gemini CLI service degradation (Discussion #22970: paid users hitting 429 errors, 7–10 min latency, 24hr+ outages post-March 25 update), this release hardens every command against provider instability.

Dual-track research

/pi-research upgraded to dual-track — now launches Gemini (search grounding) and WebSearch simultaneously, same architecture proven in /pi-fact-check. If Gemini times out or returns 429, WebSearch results cover the gap. Claude synthesizes all available sources with URL attribution
Source URLs in research reports — Gemini prompted to return source URLs; WebSearch URLs included in final report. Claims without sources marked as (unverified)
Provider Status table — research reports now begin with a track status table (Gemini ✅/⚠️, WebSearch ✅/⚠️, Claude ✅ always)

Structured error diagnostics

Error classification in shell scripts — call-gemini.sh and call-codex.sh now classify errors into 7 categories: TIMEOUT, RATE_LIMIT, AUTH_ERROR, PERMISSION, SANDBOX (Codex only), NETWORK, CLI_ERROR, plus CLI_NOT_FOUND for missing binaries
Bash regex over grep — error classification uses [[ "$err_lower" =~ pattern ]] instead of echo | grep -qi, eliminating subshell forks on the error path and avoiding a set -euo pipefail edge case. Lowercase conversion updated to printf | tr for macOS bash 3.2 compatibility in v0.11.3
PERMISSION class — new error category for filesystem permission denied (previously misclassified as AUTH_ERROR in both scripts). call-codex.sh reordered: SANDBOX now matches before AUTH_ERROR, preventing "permission denied" from triggering wrong recovery guidance
CLI_NOT_FOUND class — binary resolution failures now emit the same structured Error: CLI_NOT_FOUND: prefix as runtime errors, so downstream commands can parse failure reason consistently

Unified failure handling across all commands

All 10 commands updated with consistent failure handling:

Specific failure reasons — every failure message now includes the error classification from stderr (e.g., "⚠️ Gemini unavailable (RATE_LIMIT) — ...") instead of generic "unavailable"
Alternative command suggestions — when a provider fails, the message suggests a relevant alternative:
- /pi-ask-codex / /pi-ask-gemini → suggest /pi-askall
- /pi-code-review → suggest /pi-multi-review
- /pi-ui-review → suggest /pi-multi-review
Full error category lists — all command docs now list the complete set of error categories (no more "etc." shortcuts), matching the actual script output. Gemini commands include PERMISSION; Codex commands include SANDBOX
Never abort — consistent across all commands: always produce output, even if all providers fail

Analysis context

Gemini CLI log analysis (628 log entries, Feb 24 – Mar 27): average latency increased ~30% post-March 25 service update, 6 timeout incidents concentrated on API deployment dates (Mar 18: 60% failure rate, Mar 25: 22% failure rate)
/pi-research and /pi-fact-check confirmed as architecturally distinct (exploratory vs verification) — not merged, but /pi-research elevated to the same resilience tier

v0.10.3 (2026-03-26)

Fact-Check Dual-Track — Gemini + WebSearch race eliminates dead-wait time.

Dual-track search architecture — /pi-fact-check now launches Gemini (search grounding) and WebSearch simultaneously instead of sequential fallback. Whichever returns first is usable immediately; both results merge for stronger source convergence
Batch size optimization — Gemini batches reduced from 5 to 2 claims each (search grounding serializes internally; smaller batches complete within timeout)
Timeout fix — replaced perl alarm with Bash tool timeout parameter (fixes orphan process on macOS, removes permission allowlist dependency)
Convergence-based confidence — new report format with source convergence scoring (🟢 High/🟡 Medium/🟠 Single/🔴 Conflicting) and 6-tier source ranking (L1 official records through L6 community)
URL validation — Step 4.5 verifies Gemini-sourced URLs via WebFetch, downgrades verdict on hallucinated/fabricated sources, triggers full WebSearch fallback if >50% fail
Editorial chain dedup — same-origin sources (e.g., AP wire republished by 5 outlets) collapsed to 1 independent source for accurate convergence counting
README updates — bilingual documentation updated to reflect dual-track architecture, cost estimation, and degradation path

v0.10.2 (2026-03-22)

Score Transparency & README Rewrite — show your work, sharpen claims.

Score transparency (Show Your Work) — all 3 review commands (/pi-code-review, /pi-multi-review, /pi-ui-review) now end with a show scores affordance. Users can request a full factor breakdown for every finding, showing exactly how each confidence score was calculated (base 40, applicable factors, arithmetic)
README rewrite — "The Problem" / "The Solution" sections rewritten with clearer narrative: F1 noise → cross-provider triangulation → evidence-based scoring → local-first. New "Why Trust the Findings?" section explains the difference between LLM self-assessment and deterministic evidence-based scoring
Accuracy fixes — F1-to-false-positive claim corrected (removed unsupported ratio), Anthropic plugin comparison softened to factual statement, determinism claims qualified to "core formula" per spec §2.2
Bilingual affordance — score transparency hint line now bilingual (EN/zh-TW) for international users
Gemini CLI service update notice — added Prerequisites notice about Google's March 25, 2026 changes (free accounts limited to Flash models)
Acknowledgments section — added to both READMEs, crediting newtype-os/super-fact-checker

v0.10.1 (2026-03-19)

Fact-Check Rewrite — original methodology, unified English.

Rewritten /pi-fact-check prompt — replaced external methodology with original cross-provider approach: natural language claim extraction, source preference ordering, 4 verdicts (Verified / Imprecise / Incorrect / Unverifiable), 5 cross-verification dimensions
Adversarial evidence — new verification dimension: court filings, regulatory actions, and competitor analyses that implicitly confirm facts carry highest confidence (survived hostile scrutiny)
Unified English — all prompt content now in English, consistent with other commands
Simplified — 186 → 121 lines without losing functionality

v0.10.0 (2026-03-19)

New Command: Fact-Check

New /pi-fact-check command — cross-provider fact verification using Gemini (Google search) for source discovery and Claude for cross-verification. Two providers, two roles: Gemini finds evidence, Claude judges it
Gemini-only — no Codex. Fact-checking is an evidence-based task; Codex has no web search and would not add verification value
Graceful degradation — Gemini timeout (90s) → WebSearch fallback → Claude training data. Never aborts
Save results — optional save to .claude/pi-fact-check/<slug>.md

v0.9.9 (2026-03-15)

New Command & Trigger Refinement

New /pi-askall command — ask Codex and Gemini the same question in parallel, then Claude synthesizes all three perspectives. Works with any topic (code, architecture, strategy, writing, decisions) — not limited to code review
Narrowed /pi-plan trigger scope — now triggers only for architectural decisions, tech stack selection, and tasks with multiple viable approaches. Simple task breakdown is left to Claude Code's built-in plan mode

v0.9.8 (2026-03-12)

Review Quality Improvements — three new review dimensions inspired by analysis of Anthropic's official code-review plugin.

Historical PR comments — review commands and ci-review.sh now query review comments from recent merged PRs that touched the same files, surfacing recurring issues as high-confidence context. CI uses a single GraphQL query; slash commands use gh CLI interactively
Inline annotation compliance — all review commands now check if changes violate nearby code comments (IMPORTANT, WARNING, FIXME, TODO, NOTE annotations)
Diff scope constraint — provider prompts now explicitly constrain reviewers to focus on the diff, reducing hallucination and out-of-scope noise
Removed /pi-exec — Claude Code is already a powerful agentic executor with built-in task tracking (TodoWrite) and cross-session resume (RESUME.md). /pi-exec duplicated these native capabilities without adding cross-provider value
Repositioned core narrative — added "Why claude-prism?" comparison table contrasting cross-provider review with single-provider multi-agent approaches
Diff hunk validation for inline suggestions — ci-review.sh now validates that suggestion line numbers fall within actual diff hunks before posting via the GitHub Reviews API

v0.9.7 (2026-03-09)

GitHub Suggestion Blocks — review commands now output one-click fixable code suggestions.

Suggestion block output — /pi-code-review, /pi-multi-review, /pi-ui-review now include GitHub suggestion blocks for issues with concrete, unambiguous code fixes
Inline PR review comments — ci-review.sh parses suggestion blocks and posts them as inline review comments via the GitHub Reviews API, enabling one-click "Apply suggestion" in PRs
Graceful fallback — if the Reviews API fails or no suggestions are found, falls back to regular PR comment (fully backward-compatible)

v0.9.6 (2026-03-09)

Prompt Quality & Consistency — multi-provider review of all 9 command prompts, with fixes.

Confidence scoring implemented — evidence extraction, hallucination verification, and --verbose flag applied to all 3 review commands (/pi-code-review, /pi-multi-review, /pi-ui-review), aligned with spec v1.0
Fix: pi-exec resume bug — plan step checkbox syntax (1. [ ] vs - [ ]) mismatch between /pi-plan and /pi-exec caused resume detection to fail
Fix: pi-ask-gemini "review" prefix — code context invocation hardcoded "review" as the prompt, biasing Gemini's response
Standardized stdin pipe invocation — all commands with code context now use echo "context" | call-xxx.sh "$ARGUMENTS" pattern consistently (avoids ARG_MAX limits)
/pi-research enhanced — added project context awareness, optional save-to-file (.claude/pi-research/), and improved Claude supplement wording
/pi-ui-design fixed — resolved undefined variables ($DESIGN_SPEC_CONTENT, $USER_INPUT), standardized to $ARGUMENTS and stdin pipe
Context budget — all commands with code/context injection now enforce a 4000 char limit with summarization guidance
Internationalization — removed hardcoded Chinese text from command prompts; output language now follows user's own Claude Code language settings
Failure message consistency — standardized format across all commands: "[Provider] unavailable — [action] by Claude only."

v0.9.5 (2026-03-09)

Supply Chain Security — improve socket.dev score and npm packaging.

npm files precision — excluded CI-only scripts (ci-review.sh, review-insights.sh, usage-summary.sh) from npm package; only runtime scripts shipped
bugs field — added bugs.url to package.json for npm metadata completeness
npm OIDC Trusted Publishing — CI uses Node 24 + OIDC for npm publish with provenance (no NPM_TOKEN secret needed)

v0.9.1 (2026-03-06)

Security & Bug Fixes — audit-driven hardening across all scripts.

Prompt injection defense — ci-review.sh now wraps both GUIDELINES and DIFF blocks with explicit data boundary markers to prevent LLM instruction injection
stderr/stdout separation — call-gemini.sh and call-codex.sh no longer mix stderr into AI responses; errors are logged and forwarded to stderr separately
gh CLI dependency check — ci-review.sh --pr mode now validates gh availability before attempting to fetch PR diff
--sandbox whitelist — call-codex.sh validates sandbox mode against allowed values (read-only, sandbox, none)
review-insights.sh rewrite — switched from fragile sed/grep JSON parsing to jq; added jq dependency check; fixed unquoted variable references
Schema consistency — pi-code-review.md logging schema now includes domain field (matching pi-multi-review.md)
Domain detection tests — 6 new test cases for detect-domain.sh (smoke test: 26 → 32)
Docs — added CLI version compatibility table and checksums trust model explanation to README

v0.9.0 (2026-03-05)

Confidence Scoring & Guideline Compliance — evidence-based noise filtering and project rule enforcement across all review commands.

Confidence scoring — every review issue scored 0–100 on evidence quality (line numbers, cited rules, reproducibility, consensus). Only issues ≥ 80 shown. Scoring is evidence-based, not opinion-based — Claude cannot veto cross-provider findings with strong evidence
Guideline compliance — auto-discovers CLAUDE.md and Agents.md in the project, checks code against project-specific rules. Ready for the emerging Agents.md standard
False positive filtering — explicit exclusion rules in all review prompts: no pre-existing issues, no linter-detectable problems, no pedantic nitpicks, no lint-ignore lines
Applied to: /pi-code-review, /pi-multi-review, /pi-ui-review, ci-review.sh
Review insights enhanced — JSON schema adds confidence score and guideline category

v0.8.0 (2026-03-04)

Distribution — added npx and Homebrew install support.

npx claud-prism-aireview for one-command install
brew tap tznthou/claude-prism && brew install claud-prism-aireview for macOS
Added GitHub Release workflow for automated npm publishing
Legacy command cleanup in install/uninstall scripts

v0.7.0 (2026-03-04)

Smart Routing, Plan/Execute & Command Namespace — domain-aware review weighting, persistent planning, and pi- prefix for all commands.

Breaking: `pi-` command prefix

All 9 commands are now prefixed with pi- (e.g., /code-review → /pi-code-review, /research → /pi-research).

Why? Claude Code has a built-in /plan command (enters plan mode). Our new /plan command for persistent planning would collide with it. Rather than only prefixing the conflicting commands, we chose to prefix all commands uniformly for namespace safety and brand identity. The pi- prefix (from Prism Initial) is short enough to type quickly while making it clear which commands belong to claude-prism.

Migration: After updating, re-run ./install.sh. The installer will overwrite the old command files. To clean up old (unprefixed) commands manually:

cd ~/.claude/commands
rm -f ask-codex.md ask-gemini.md code-review.md multi-review.md \
     research.md ui-design.md ui-review.md plan.md execute.md

Smart routing

/pi-multi-review now auto-detects the domain of the code changes (frontend / backend / fullstack) and adjusts provider weight during synthesis.

How it works:

File paths from the review scope are piped to detect-domain.sh
The script classifies each file by extension and path:
- Frontend signals: .css, .tsx, .jsx, .vue, .svelte, .html, .svg / components/, pages/, styles/, ui/
- Backend signals: .go, .py, .rs, .java, .sql, .proto / api/, controllers/, models/, middleware/, migrations/
- Neutral (not counted): .ts, .js, .json, .yaml, .md, .sh
If ≥ 70% of classifiable files lean one way → that domain; otherwise → fullstack

During synthesis:

Domain	Gemini weight	Codex weight	Rationale
frontend	Higher	Standard	Gemini excels at UI/UX, accessibility, design patterns
backend	Standard	Higher	Codex excels at algorithms, security, API design
fullstack	Equal	Equal	No domain advantage

Design philosophy: "weight, don't route." Both providers are always called. The domain only affects how Claude resolves disagreements — if both providers agree on an issue, it's reported regardless of weighting. This preserves graceful degradation: if one provider is down, the other still covers the full review.

Plan/Execute

Two new commands for persistent, cross-session task planning:

/pi-plan <task description> — Analyze the codebase and generate a structured plan file:

Optionally consults Codex and Gemini in parallel for independent technical analysis
Detects domain via detect-domain.sh to contextualize recommendations
Outputs a markdown plan to .claude/pi-plans/<slug>.md with: context, multi-provider analysis, step-by-step implementation (with checkboxes), key files, risks, and verification criteria
Does not auto-execute — the plan is a proposal for the user to review

/pi-exec <plan-file> — Execute a plan step by step:

Reads the plan, validates status (draft / approved / in-progress / completed)
Executes each step sequentially, updating - [ ] → - [x] as it goes
If a step fails, stops and asks the user how to proceed
Resume support: If a session ends mid-execution, running /pi-exec on the same file resumes from the first unchecked step — no progress is lost

Why not SESSION_ID? Some planning tools use session IDs and a separate binary to track state. We use markdown checkboxes instead — the plan file itself is the state. This keeps the mechanism simple (no external dependencies), human-readable (you can edit the plan in any editor), and consistent with our zero-compile-dependency principle.

Other changes

Review insights enhanced — review-insights.jsonl now includes a domain field for domain-aware trend analysis
detect-domain.sh — new standalone utility script (can be used outside of multi-review; reads file paths from stdin)

v0.6.0 (2026-03-03)

Security Hardening — security audit and fixes across all shell scripts:

Temp file safety — review-insights.sh now uses mktemp instead of a predictable /tmp path (symlink attack prevention)
Input validation — ci-review.sh validates --pr argument as a positive integer
Process visibility — call-codex.sh and call-gemini.sh now always pipe prompts via stdin (prevents exposure in ps output)
Install integrity — install.sh verifies SHA256 checksums before installing (new checksums.sha256 file)
ShellCheck CI — new GitHub Actions workflow for static analysis on all shell scripts
ShellCheck fixes — removed unused variables, fixed invalid >= operator, quoted command substitutions

v0.5.0 (2026-02-24)

CI/CD Integration — automated multi-provider PR review via GitHub Actions:

ci-review.sh — CI/CD review orchestrator that calls Gemini API + OpenAI API in parallel, with optional Claude synthesis. Uses REST APIs directly (no CLI installation needed)
GitHub Actions workflow (ai-review.yml) — label-triggered or auto-triggered PR review with concurrency control
Graceful degradation in CI — works with any combination of API keys (1-3 providers)
Large diff handling — auto-truncation at 32K chars (configurable via MAX_DIFF_CHARS)
Smoke test expanded to 24 tests (from 20)

v0.4.0 (2026-02-24)

Reliability & Observability — graceful degradation, usage tracking, and review insights:

Graceful degradation across all 7 commands — if a provider fails, Claude continues with remaining providers instead of aborting. Non-conforming output (no emoji, no score) is handled via semantic extraction
usage-summary.sh — per-provider call stats, success/error breakdown, estimated token consumption (--week, --all, --date)
review-insights.sh — analyze recurring patterns from review history (category/severity distribution, consensus vs. single-provider findings, most frequent issues)
Review insights auto-recording — /code-review and /multi-review append structured JSONL after each review for trend analysis
Smoke test expanded to 20 tests (from 14)

v0.3.1 (2026-02-24)

/ui-design redesigned — now generates a previewable HTML mockup (Tailwind CDN) from design spec files
Workflow: design spec → HTML mockup → browser preview → confirm → Claude Code implements
Text input (no spec file) triggers a two-step flow: generate spec → generate mockup
Next steps presented as choices (adjust, implement, or /ui-review)

v0.3.0 (2026-02-24)

New command: /ui-design — UI/UX design spec generation via Gemini (information architecture, wireframes, component breakdown, visual direction)
Optional --html flag generates a self-contained HTML prototype with Tailwind CDN
Auto-detects project tech stack to inform design suggestions

v0.2.1 (2026-02-24)

Script hardening — fixes identified via /multi-review (Codex + Gemini + Claude triple-provider review):

-m flag guard: -m without a value now shows a clear error instead of crashing with "unbound variable" (set -u)
Deduplicate execution logic: merged identical error handling from the if/else branches into a single || { ... } block
Sanitize error logs: error log entries no longer include response content (which could contain source code or tokens); only exit code is logged

v0.2.0 (2026-02-24)

Initial public release
6 slash commands: /ask-codex, /ask-gemini, /code-review, /ui-review, /research, /multi-review
Model defaults deferred to CLI built-in (no hardcoded versions)
Dry-run exits before binary check (works without CLI installed)

FilesExpand file tree

CHANGELOG.md

Latest commit

History

CHANGELOG.md

File metadata and controls

Changelog

v0.16.0 (2026-08-11) — provider prompt overhaul: one-shot contract + text-based output format

Changed (shared contracts — all 10 commands)

Changed (per-skill)

Changed (docs)

v0.15.1 (2026-07-15) — agy 1.1.2 compatibility fix + ARG_MAX guard

Changed (agy 1.1.2 compatibility)

Added

v0.15.0 (2026-06-18) — Gemini provider migrated to agy (Antigravity CLI)

Changed (Gemini provider — agy migration)

Added (CI — smoke tests actually run)

Added (pi-plan synthesis mechanisms)

Fixed

v0.14.6 (2026-05-20) — Phase A2 first-byte detector + supply-chain hardening

Added (Phase A2: first-byte detector tri-state)

Added (Tooling — scripts/calibrate-timeout.sh)

Changed (Supply-chain hardening — SHA pin + Dependabot)

Added (Documentation — Antigravity CLI transition notice)

Fixed

Testing

Notes

v0.14.5 (2026-05-11) — codex-cli 0.130.0 sandbox interface drift fix + small-skill timeout calibration

Fixed (codex sandbox interface drift)

Fixed (skill caller export + timeout calibration since v0.14.4)

Testing

Notes

v0.14.4 (2026-04-29) — Log forensic fields + monthly rotation + sub-agent timeout default

Added (Phase A1: Log Forensic Fields)

Added (Phase B: Monthly Log Rotation)

Changed (sub-agent timeout default)

Fixed

Testing

Notes

v0.14.3 (2026-04-28) — Phase 2: CLAUDE_PRISM_OUT_TMP env-var contract + stall observability

Changed

Security / Concurrency

Observability

Testing

Notes

v0.14.2 (2026-04-24)

Changed

Security

Testing

Notes

v0.14.1 (2026-04-24)

Added

Changed

Notes

v0.14.0 (2026-04-23)

Added

Security

Testing

Mechanism design (rationale in .claude/pi-plans/soft-timeout-call-scripts.md)

Notes

v0.13.0 (2026-04-23)

Changed

Documentation

Breaking changes

Notes

v0.12.6 (2026-04-20)

Testing

Fixed

v0.12.5 (2026-04-20)

Fixed

v0.12.4 (2026-04-20)

Fixed

Documentation

v0.12.3 (2026-04-18)

Root cause

Mitigation

Observability (new)

Documentation

v0.12.2 (2026-04-11)

v0.12.1 (2026-04-07)

Added (Tooling — `scripts/calibrate-timeout.sh`)

v0.14.3 (2026-04-28) — Phase 2: `CLAUDE_PRISM_OUT_TMP` env-var contract + stall observability

Mechanism design (rationale in `.claude/pi-plans/soft-timeout-call-scripts.md`)

Breaking: `pi-` command prefix