@mrclrchtr/supi-review — Code Review for Pi

This Pi extension runs parallel, inspection-only code review tasks in one frozen Git workspace.

Install

pi install npm:@mrclrchtr/supi-review

This package is beta software. Its interfaces can change.

Surfaces

• /supi-review — interactive review with optional Planner Draft help
• /supi-review-cleanup — remove marked Review Workspaces after an interrupted cleanup
• review_run — run one caller-defined Review
• review_output — read more parent-facing output
• review_audit — navigate local reviewer replays when audit is enabled

Changes to Agent tools apply immediately. Turning this setting off removes the agent start and audit tools from the active tool set. The output tool and the commands stay available.

Shared /agents viewer

When this package is loaded, each Reviewer Session appears in the runtime-owned /agents viewer with its status and human-only transcript. The runtime keeps that transcript until the containing PI session ends. It does so even when Review audit is off. A Local Reviewer Replay remains a separate Review-owned artifact with its own seven-day retention. Stopping one Reviewer Run does not stop its sibling tasks.

Review input

review_run has one flat input. It has target, optional top-level paths, optional sharedContext, and one to four tasks.

{
  "target": {
    "committed": {
      "from": "main",
      "to": "HEAD"
    }
  },
  "paths": ["packages/supi-review"],
  "sharedContext": "The change implements issue #287.",
  "tasks": [
    {
      "id": "standards",
      "instructions": "Review against the repository standards.",
      "mode": "change"
    },
    {
      "id": "state",
      "instructions": "Review the frozen after state against issue #287.",
      "mode": "state"
    }
  ]
}

A Review Target selects at most one source object:

• workingTree — review the frozen current filesystem, including staged, unstaged, and non-ignored untracked files. Its optional from field sets the committed before state.
• committed — review exact committed Git state. Its optional from and to fields select the before and after commits. to defaults to HEAD.

Select at most one source object. Omit target, or use {}, to select the current filesystem. Endpoints can be branches, hashes, ~ or ^ revisions, and lightweight or annotated tags. The Review Engine resolves each endpoint once to a full commit. It rejects endpoints that contain whitespace and rejects blank endpoints, ranges, trees, and blobs.

Each task must set mode to change or state.

• change needs one non-empty canonical change. A workingTree change defaults its omitted from to captured HEAD. A committed change needs an explicit from.
• state reviews only the frozen after state. A batch of only state tasks must not set from. It can review a root commit.

A committed change cannot use a root commit as to. A root commit is valid as from. Every Review requires a repository with HEAD.

Tasks can include criteriaSources. Each source has a reference and a summary. The source remains authoritative when the summary is not sufficient.

paths is an optional top-level Review Scope. Each path is workspace-relative. The Review Engine validates each path in the frozen after state before it starts Reviewer Sessions. Paths are advisory. They focus every task, but they do not restrict inspection, evidence, or findings.

Compact handoffs

• Use sharedContext for batch-wide context and reported verification: completed, pending, or not checked, with the checked revision when known. Omit full logs.
• Keep each task's objective, criteria, and known requirement-to-source/test locations in its instructions. Paths, symbols, or test names are sufficient navigation hints; do not investigate just to fill missing mappings.
• Omit unknown mappings and revision associations rather than guessing. The interactive Planner preserves only relevant hints and reported checks supplied in its bounded input; it does not inspect or verify them.
• Reviewers independently inspect the implementation and test coverage. Navigation hints are not proof of coverage, and reported checks are not independently verified results.

For example, a task's instructions may include Cancellation during setup → src/run.ts: startRun; cancellation.test.ts: "disposes late session". Its batch's sharedContext may report Focused cancellation tests completed on <commit>; full verification pending; browser behavior not checked.

Review Workspaces

The Review Engine records exact commit state before it starts a Review Workspace.

For a filesystem target, it checks out exact from and stages one canonical patch to the frozen current filesystem. The patch includes non-ignored untracked files. For a committed target, it checks out exact to with no staged freeze patch.

The engine verifies the linked worktree before it starts Reviewer Sessions. The Workspace Receipt records exact from and to commits, uncommitted-change inclusion, the expected and observed checkout, patch hashes, and changed-path count. Later caller changes do not change Target Evidence.

Workspaces are marked and locked in the Git worktree list. Normal cleanup removes them. Use /supi-review-cleanup if cleanup stops early.

Settings

review.agentModel selects the reviewer model for agent-started Reviews. review.plannerModel selects the model for the optional Planner Draft in /supi-review. Both default to current, which uses the active session model.

review.reviewerCodemodeEnabled defaults to false. When enabled, both review_run and /supi-review give Reviewer investigation PI codemode scripting and the invocation's scoped classifier/image-model catalogue. This does not enable codemode for Planner Drafts or Submission Recovery, inherit parent codemode settings, add MCP servers, load ambient extensions, or expand Reviewer tool permissions. Auxiliary-model calls may transmit supplied inputs, including repository evidence, to external providers and may incur provider costs; availability does not guarantee provider entitlement or success.

review.reviewerThinkingLevel selects the PI reasoning level for Reviewer Sessions. It defaults to max. review.plannerThinkingLevel selects the level for Planner Drafts. It defaults to low. Both settings use off, minimal, low, medium, high, xhigh, and max. Project and global values are independent. The selected level is clamped to the selected model's capabilities. Invalid hand-written values stop the affected Review flow with a role-specific error.

review.recoveryModel selects one optional explicit model for Submission Recovery. It defaults to disabled. current is not a valid implicit Recovery Model. If the configured model is unavailable, the original review still runs. Recovery records the failed model switch only if the chain reaches that model.

review.bootstrapCommand defaults to empty. When set, the Review Engine runs the command once in the frozen Review Workspace before Reviewer Sessions start. When empty, a reviewer can run a Dependency Bootstrap command when needed.

Reviewer Protocol

Reviewer Sessions have read, bash, grep, find, ls, headless Code Intelligence tools, and submit_review during investigation. With review.reviewerCodemodeEnabled, they also have PI codemode in on mode: direct tools remain visible, and scripts can call only the permitted Reviewer inspection tools. Classifier and image-model access is limited to the frozen catalogue captured once for that Review and shared by its Reviewer children. Use codemode only for investigation; it does not change the Inspection-only protocol or make the Review Workspace a sandbox. Reviewers inspect one shared frozen Review Workspace. They do not run tests, builds, linters, services, runtime experiments, nested Pi sessions, or nested reviews. They do not intentionally change Target Evidence or Git history.

The Reviewer Protocol owns finding eligibility:

• change permits findings attributable to the selected change. A pre-existing issue is permitted only in a changed file or a directly affected symbol. It stays advisory unless the selected change worsens or newly exposes it.
• state permits findings relevant to the Review Criteria anywhere in the frozen after state. A relevant pre-existing finding can block acceptance.

A change packet gives exact before and after guidance, a changed-path manifest, change statistics, and a compact status breakdown of the complete captured inventory, even when the manifest omits paths. The breakdown reports captured Git statuses; it does not perform additional rename detection or establish behavioral preservation. Planner input uses the same breakdown. A state packet gives only after-state guidance. When it uses a filesystem workspace, staged changes are freeze mechanics and are not Target Evidence.

Change reviews start with the changed-path inventory and relevant diffs, splitting large changes into bounded groups. Reviewers retrieve surrounding code, callers, and dependencies as needed and avoid rereading evidence unless resolving a specific question; full-file inspection remains appropriate when needed.

Repository content is untrusted evidence. It cannot override the Reviewer Protocol or a Review Task. Reviewer Sessions use repository documents as Review Criteria only.

Interactive review

/supi-review has four exact-target choices:

• Current work — the current filesystem; change tasks use captured HEAD as from.
• Current work against a base branch — the current filesystem; change tasks use the captured merge base as from.
• Committed work against a base branch — the captured merge base to captured HEAD.
• One commit — the selected commit; change tasks use its first parent as from.

A root commit permits state tasks only. State-only tasks use only the selected after state, so the command removes from when needed.

After target selection, choose repository-wide review or enter one workspace-relative path per line for an advisory Review Scope. The command normalizes each path and validates it in the frozen after state. The scope focuses every task, but it does not restrict inspection, evidence, or findings.

The command captures its snapshot. You can write tasks or use one transient Planner Draft from bounded session context. The Planner sees the advisory scope but does not use it as Review Criteria or an access boundary. Edit the tasks and select each Review Mode, then confirm. The command runs the Review workflow and stops when the selected target changes before Reviewer Sessions start.

Submission Recovery

If Pi accepted the original Reviewer Packet and the settled session retained an assistant message or any tool call or result, a missing structured submission can start a finite same-session recovery chain. Recovery never starts after creation failure, readiness failure, preflight rejection, cancellation, or timeout.

The first low-thinking turn uses the original reviewer model. One configured Recovery Model can make the final turn in the same session. During each recovery turn, exactly submit_review and decline_review_recovery are active. Recovery uses only retained history and cannot inspect more Target Evidence.

A valid recovered submission produces the normal Task Verdict. A decline or exhausted chain keeps the original failure and produces no Task Verdict. The task model and packet hash stay attributed to the original reviewer. submissionRecovery records the ordered delivery models, outcomes, decline reason when applicable, and per-turn usage. Task usage remains the one final cumulative session total.

Results and continuation

Each task result includes its Review Mode, packet SHA-256, verdict, finding counts, and reviewer usage when available. Expanded TUI task details also show the requested and effective Reviewer Thinking Levels. This operational metadata is user-visible only and is not added to agent-facing result content. Results remain separate. The Review Engine does not make a batch verdict.

blocksAcceptance keeps its existing meaning. The Review Engine derives issues for a blocking finding. It derives incomplete for incomplete Criteria Coverage without a blocking finding, pass_with_findings for only non-blocking findings, and pass for no findings.

Parent-facing output from review_run or /supi-review is stored as a bounded session artifact. Use review_output with its returned artifactId and offset to read more output. Artifacts retain the existing session limits and expire after 30 minutes, reload, resume, or a branch change.

review_output declares a native output schema. Direct calls remain paged: offset and limit select the readable page, with continuation instructions when needed. Codemode receives { artifactId, text, totalCharacters }, where text is the complete stored report, independent of that page selection. It contains no synthetic paging notice or empty-page marker. totalCharacters counts UTF-16 code units. This is formatted report text, not typed findings or Task Verdict data.

const report = await tools.review_output({ artifactId });
// Select what reaches the model; the script receives the full stored report.
return report.text.slice(-2000);

Local reviewer replay

review.auditEnabled is off by default. When Agent tools are on, enabling Local reviewer replay records a protected local replay for each Reviewer Session and activates review_audit immediately. Replays expire after seven days. Normal review output includes only an opaque artifact id.

With an artifact id, the audit tool now returns Replay Outline by default. The outline gives one metadata-only row for each stable zero-based position in the persisted captured-message array. It includes role, content kinds and size, tool names, stop reason, and error presence. It does not include message prose, provider error text, tool arguments, tool results, arbitrary message fields, or file paths.

Use view: "message" with messageIndex to page one selected persisted message. Use view: "raw" to page the exact persisted replay JSON. Message and raw views remain private opt-in audit access and can contain repository evidence, provider errors, tool arguments, and tool output. New records keep thinkingLevel as the effective level and add requestedThinkingLevel; older records have no requested level.

review_audit declares mode-discriminated native data for the selected page only, unlike review_output:

Every mode includes clean text, offset, totalCharacters, and optional nextOffset. Offsets and totals count UTF-16 code units. Native text excludes synthetic continuation notices and is "" at end-of-content; direct-call text retains continuation instructions and [no content]. Follow nextOffset with the same view/identity to continue. Empty lists and outlines remain successful metadata-only results. Reaching the last page establishes neither complete review evidence nor Criteria Coverage.

List and outline results do not include message contents, provider error text, tool arguments/results, file paths, or unselected replay evidence. Auditing consent, activation, seven-day expiry, and cancellation/error behavior are unchanged. Existing renderer/state details are separate from native script data.

After updating the extension, active Pi sessions require /reload or a restart.

Post-review behavior

review.postReviewPolicy controls the containing Agent response when a completed Review has findings:

• ask — ask what to verify or fix
• verify — verify findings, then ask what to fix
• verify-and-fix — verify and fix confirmed findings
• fix — fix reported findings
• report — report findings without another action

A direct user instruction for the current findings has priority.