[backnotprop]

PR 5 of the approved 0.29 agent-sessions design: the plannotator tool comes to Pi, so a Pi agent opens reviews the same way the Claude Code mod does (non-blocking, with Ask this session) instead of running the blocking CLI.

What it does

• Registers the shared contract with pi.registerTool. Name, description, validation (parsePlannotatorToolInput), argument mapping (plannotatorToolArgs) and result text come from packages/shared/plannotator-tool.ts, vendored as generated/plannotator-tool.ts. parameters is PLANNOTATOR_TOOL_INPUT_SCHEMA itself, with no TypeBox copy: Pi has validated plain JSON Schema parameters since 0.79.1, the peer floor. executionMode: "sequential", so "edit, then open" in one message opens the edited file ([pi] plannotator_submit_plan can review a stale plan when batched with a write/edit (parallel tool execution race) #1622).
• One launch path. The three slash commands and the tool now share launchCodeReview, launchAnnotate and launchLastMessage: in-process server, session bridge attached, decision delivered later as a followUp. The commands still notify on errors. The tool throws them, and Pi reports that as an error result.
  • Opening returns at once with Session: pn-xxxxxx and the URL, and terminate: true ends the turn.
  • A gated session the tool opened also delivers a bare Approve (the mod's rule).
  • The annotate target is one argument, so the tolerant word split (/plannotator-annotate treats trailing natural language as a filename and fails #1182) never runs on it.
• list / close come from a per-instance registry (apps/pi-extension/plannotator-tool-host.ts). It records every review this Pi session opened (tool, /plannotator-* commands, plannotator_submit_plan) and is filtered by sessionManager.getSessionId(). The global sessions/ registry is never read.
  • unsent and decided come from the server's in-process hostControl.status().
  • close calls hostControl.close(), from feat(tool): contract v2 with session ids, list and close #1709: it acts as the reviewer's Close, the draft is kept, and nothing is delivered. Pi notifies "the agent closed …" instead.
  • Plan reviews are listed but never closed.
• Decision heading: review, annotate and last decisions, from commands too, now start with plannotatorDecisionHeading (Plannotator: notes.md (pn-3f2a9c) — Feedback · 1 comment.).
• Clear refusals: a list of files gets PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT, and the bundles PR only needs to add the open path, since validation is already shared. reply gets PLANNOTATOR_TOOL_REPLY_UNAVAILABLE_TEXT. A session without UI (print/JSON mode) is refused.

Deviations / notes

• Plan decision messages are unchanged (no heading). The submit result never named a session id, so plan review keeps its existing prompts.
• No Bash take-over on Pi. Pi's tool_call event can only block a call, and the model reads that as an error. The core skill already says to use a plannotator tool when there is one, so no skill change was needed.
• Remote mode: opening works. The URL is in the tool result and in the notification, and the Ask bridge stays off, as before. Close works in-process even though the HTTP host endpoints are off in remote mode.
• Subagent rules from the mod do not apply: Pi has no in-process subagents.

Tests

• apps/pi-extension/plannotator-tool.test.ts (7 tests) drives the real extension with real in-process annotate servers. It checks:
  • the schema equals the shared one and the installed Pi's validateToolArguments accepts and refuses calls correctly;
  • opening returns at once with the bridge attached, and feedback arrives as a followUp with the heading;
  • a gated bare approval is delivered;
  • list and close see only this Pi session (another session id and another instance get nothing), close keeps the draft, and nothing is sent;
  • command-opened reviews are listed, and close all skips a plan review;
  • review argument mapping;
  • refusals.
• Results:
  • bun test apps/pi-extension apps/hook/hooks/mod packages/shared/plannotator-tool.test.ts: 495 pass.
  • bun run typecheck (re-vendors): OK.
  • bun pm pack --dry-run includes plannotator-tool-host.ts and generated/plannotator-tool.ts.
• Live check, real Pi 0.85.1 and 1.0.2: rpc mode, isolated HOME and PLANNOTATOR_DATA_DIR, this worktree's extension, and a scripted faux model that calls the tool. On both versions:
  • The turn settled at once with no model call after terminate, and Ask AI listed "Ask this session · Pi".
  • list returned the review. Feedback arrived as a new turn: Plannotator: notes.md (pn-…) — Feedback · 1 comment.
  • close all reported "1 unsent comment saved as a draft". No turn followed, and the draft stayed on disk.
  • A gated approval arrived as … — Approved., and a file list was refused.

Co-Authored-By: Claude noreply@anthropic.com