pi-midcompact 0.6.0 → 0.7.0

package/README.md

@@ -17,7 +17,7 @@ The name `pi-midcompact` points to the other option: **mid-context compression**
 
 ## What it does
 
-At a natural checkpoint, `pi-midcompact` freezes the active session leaf as an anchor and opens a separate transaction. The Agent proposes ranges for completed low-value phases, preserves load-bearing messages verbatim, and prepares a draft for review. Nothing changes until you explicitly commit the plan.
+At a natural checkpoint, `pi-midcompact` freezes the active session leaf as an anchor and opens a separate transaction. The Agent proposes ranges for completed low-value phases, preserves load-bearing messages verbatim, and prepares a plan for review. Nothing changes until you explicitly commit the plan.
 
 ### User-directed depth, Agent-designed plan
 
@@ -29,7 +29,7 @@ That is planning guidance, not an enforced token target: semantic importance win
 
 ### A selective projection, prepared on a temporary branch
 
-`/midcompact:start` freezes the current session leaf as an **anchor**. Planning happens on a disposable child branch, so the discussion used to create and edit the draft never becomes part of the committed working context.
+`/midcompact:start` freezes the current session leaf as an **anchor**. Planning happens on a disposable child branch, so the discussion used to create and edit the plan never becomes part of the committed working context.
 
 ```text
 Frozen anchor: raw session history
@@ -53,9 +53,9 @@ The raw session JSONL still contains:
   [original d1]──[decision to KEEP]──[original d2]──[latest work]
 ```
 
-### A reviewed draft can reclaim meaningful context
+### A reviewed plan can reclaim meaningful context
 
-The earlier browser and TUI captures below illustrate a draft with **2 ranges** covering **42 of 73 atoms**, while the other 31 atoms remain verbatim. The current UI reports Pi-provided anchor usage as the baseline and derives a **display-only** projection of post-commit usage from documented char-class assumptions (labeled `est.`, shown as a range, never used for gating); factual content chars and image counts stay alongside it. Click either image to open it at full resolution.
+The earlier browser and TUI captures below illustrate a plan with **2 ranges** covering **42 of 73 atoms**, while the other 31 atoms remain verbatim. The current UI reports Pi-provided anchor usage as the baseline and derives a **display-only** projection of post-commit usage from documented char-class assumptions (labeled `est.`, shown as a range, never used for gating); factual content chars and image counts stay alongside it. Click either image to open it at full resolution.
 
 <p align="center">
   <a href="./figures/review-webui.png">
@@ -94,7 +94,7 @@ pi-midcompact — mid-context compression, review, then human commit
 | Starts | Automatically near the context limit, or with `/compact` | At an explicit natural checkpoint with `/midcompact:start` |
 | Selects | One older contiguous prefix; keeps a recent token-budgeted tail | One or more reviewed ranges, including non-contiguous ranges and `KEEP` holes |
 | Planning | Optional one-shot instruction to focus the generated summary | User states scope and retention depth; the Agent discusses trade-offs and drafts selective ranges and summaries |
-| Decision gate | Generates a compaction checkpoint directly | Draft → TUI or browser review → explicit human `/midcompact:commit` |
+| Decision gate | Generates a compaction checkpoint directly | Plan → TUI or browser review → explicit human `/midcompact:commit` |
 | Best fit | Automatic context maintenance and overflow recovery | Deliberate cleanup of completed phases while retaining specific decisions verbatim |
 
 `pi-midcompact` does not disable or replace Pi's automatic compaction; it gives you a separate, human-reviewed way to make selective reductions. See [Pi's compaction documentation](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/docs/compaction.md) for the built-in mechanism.
@@ -127,7 +127,7 @@ Run:
 /midcompact:start
 ```
 
-Pi opens a three-way chooser before creating transaction state: **Agent direct**, **User manual**, or **Drop**. Agent direct is the first and default-highlighted option, matching the previous fast path. The chooser is the standard `select` dialog, identical in interactive and RPC mode; RPC carries it as an extension UI `select` message with a bounded timeout, so an unresponsive client cancels instead of blocking. print/JSON modes have no dialog and default to **Agent direct**. Agent direct starts the existing inventory-first Agent workflow. User manual sends the same transaction guidance with a final “acknowledge only” instruction; after the Agent replies briefly, the Selection workbench opens (browser-based outside interactive mode). It does not start planning or mutate the DraftPlan until the user hands off later. Save the initial DraftPlan, close the UI, then tell the Agent to continue when you are ready. You can include an initial focus in the same command:
+Pi opens a three-way chooser before creating transaction state: **Agent direct**, **User manual**, or **Drop**. Agent direct is the first and default-highlighted option, matching the previous fast path. The chooser is the standard `select` dialog, identical in interactive and RPC mode; RPC carries it as an extension UI `select` message with a bounded timeout, so an unresponsive client cancels instead of blocking. print/JSON modes have no dialog and default to **Agent direct**. Agent direct starts the existing inventory-first Agent workflow. User manual sends the same transaction guidance with a final “acknowledge only” instruction; after the Agent replies briefly, the Selection workbench opens (browser-based outside interactive mode). It does not start planning or mutate the plan until the user hands off later. Save the initial plan, close the UI, then tell the Agent to continue when you are ready. You can include an initial focus in the same command:
 
 ```text
 /midcompact:start Compress the early repository exploration, but keep user requirements verbatim.
@@ -168,7 +168,7 @@ Use Selection to create or change ranges and KEEP holes:
 /midcompact:select-webui
 ```
 
-Use the TUI or local browser Review surface to edit summaries/topics and reject ranges. Review deliberately does not create or resize ranges; reopen Selection for boundary changes. To continue with Agent after a user-created plan, send a normal message asking it to continue the current midcompact draft; the Agent is prompted to read the existing plan first.
+Use the TUI or local browser Review surface to edit summaries/topics and reject ranges. Review deliberately does not create or resize ranges; reopen Selection for boundary changes. To continue with Agent after a user-created plan, send a normal message asking it to continue the current midcompact plan; the Agent is prompted to read the existing plan first.
 
 ### 4. Commit the reviewed compression
 
@@ -216,9 +216,9 @@ Enter/Esc/q        close
 | `/midcompact:select-webui` | Opens the local browser Selection workbench. |
 | `/midcompact:review` | Opens summary/topic review in the native TUI. |
 | `/midcompact:review-webui` | Opens summary/topic review in a local browser. |
-| `/midcompact:commit` | Commits the reviewed draft. Human only. |
+| `/midcompact:commit` | Commits the reviewed plan. Human only. |
 | `/midcompact:abort` | Abandons the transaction and returns to the anchor. |
-| `/midcompact:status` | Displays the current draft, or the committed compression state on this branch. |
+| `/midcompact:status` | Displays the current plan, or the committed compression state on this branch. |
 
 The extension shows planning status in Pi's footer only while a transaction is active. It disappears after commit or abort.
 
@@ -234,7 +234,7 @@ npm run dev:webui -- --port=4180 --no-open
 
 The command opens a fixture router for `review-ready`, `review-pending`,
 `selection-mixed`, `no-telemetry`, and `wide-content`. Each button opens an
-isolated workbench with its own in-memory draft. Fixture pages survive browser
+isolated workbench with its own in-memory plan. Fixture pages survive browser
 refresh and the page's Close action, reload HTML changes automatically, and
 restart for imported TypeScript changes. Stop the router with `Ctrl+C`. Use
 `dev/midcompact-debug-ui.ts` only when validating against an actual Pi session.
@@ -250,4 +250,4 @@ restart for imported TypeScript changes. Stop the router with `Ctrl+C`. Use
 - **Native Pi `/compact` interaction needs more real-session validation.** Avoid relying on mixed automatic/native compaction behavior for critical work until it has been exercised in your environment.
 - **Provider and extension interoperability needs more real-session validation.** Unusual message shapes, third-party context-transform ordering, and long-lived exact message fingerprints have not been broadly exercised.
 - **Very long sessions are not stress-tested.** Large review snapshots and repeated block accumulation may eventually require consolidation.
-- **Browser workbenches are local.** `select-webui` and `review-webui` bind to loopback and mutate the same branch-local DraftPlan as the native TUI surfaces.
+- **Browser workbenches are local.** `select-webui` and `review-webui` bind to loopback and mutate the same branch-local plan as the native TUI surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-midcompact",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Branch-aware mid-context compression for the Pi coding agent",
   "author": "frostime",
   "repository": {

package/skills/midcompact/SKILL.md

@@ -1,134 +1,101 @@
 ---
 name: midcompact
-description: Use when a midcompact runtime prompt starts or hands off a compression-planning transaction, or when current work needs details from an active committed midcompact block. Guides user-aligned candidate discovery, effort-scaled inspect/locate/plan work, replacement-summary writing, and recall.
+description: "Use when runtime starts or hands off midcompact planning, or current work needs originals from a committed block. Guides selective compression, local summaries, and recall."
 ---
 
 # Midcompact
 
-## Route the activation
-
-This skill handles two independent tasks: planning compression and recalling committed content. Choose the route before calling the tool.
-
-| Signal | Immediate duty | First action |
-|--------|----------------|--------------|
-| Runtime prompt says `FINAL STATE: USER MANUAL` | Let the user create the initial DraftPlan | Reply exactly `OK`; call no midcompact tool |
-| Runtime prompt says `FINAL STATE: AGENT DIRECT` | Start from the new empty draft | `request={action:"inspect"}` |
-| A handoff reports a persisted DraftPlan and the user asks to continue | Read the shared selection and determine what help the user wants | `request={action:"plan", op:"show"}` |
-| The user or a projected summary needs detail from a committed block | Retrieve that history only | Follow **Recall workflow** |
-
-The state-specific runtime prompt is authoritative. Recall does not enter planning or mutate the DraftPlan. During the User-manual acknowledgement turn, the no-tool instruction overrides every other route.
-
-The tool groups parameters by `action`: each action accepts only its own fields, and fields from other actions are rejected. Read `references/tool-interface.md` before adding workload-specific parameters, and treat the action-specific field lists there as exhaustive.
-
-## Plan compression
+The frozen **anchor** contains **atoms**, the smallest selectable units (ref `a0001`); tool calls and their results stay together. Agent and user share one **plan** of contiguous **ranges** with replacement summaries (id `d1`). **Measure** compares candidates without changing the plan. Human commit turns each range into a **block** (`c0001`), replacing its originals in future context. **Recall** retrieves those originals.
 
-Selected ranges become summaries in future model context; content outside them stays verbatim. Originals remain stored, but recall is a recovery path, not a substitute for a sufficient summary. Agent and user edit one DraftPlan; the user retains final control through review and `/midcompact:commit`.
-
-The start mode controls how the first draft is created. It does not determine whether a user selection is final, how much initiative the Agent should take, or how deeply the history should be investigated.
-
-Apply one invariant:
-
-> Every fact that can still affect future work must remain with sufficient fidelity, either outside the selected ranges or in their replacement summaries.
-
-### Planning workflow
-
-#### 1. Read the entry state and user intent
+## Route the activation
 
-For a fresh Agent-direct transaction, begin with `request={action:"inspect"}`. For a handed-off DraftPlan, begin with `request={action:"plan", op:"show"}`; inspect the anchor only if the requested work needs broader context.
+| Signal | Immediate action |
+|---|---|
+| Runtime says `FINAL STATE: USER MANUAL` | Reply exactly `OK`; call no midcompact tool. |
+| Runtime says `FINAL STATE: AGENT DIRECT` | Call `request={action:"inspect"}`. |
+| Handoff reports a persisted plan and user asks to continue | Call `request={action:"plan_show"}` before other midcompact actions. |
+| Current work needs originals from a committed block | Follow **Recall**; do not enter planning. |
 
-Establish the user's desired scope, fidelity, and planning effort from their words, current selection, `User focus: ...`, and surrounding interaction. Treat answers collected through question, questionnaire, or similar tools as user-originated input even when represented as tool results.
+Runtime instructions are authoritative. User-manual acknowledgement also forbids questions. Otherwise, complete the required first action before establishing direction.
 
-A manual selection records what the user selected, not whether they mean "only this" or "help me refine it." Follow a clear intent directly. If different interpretations would materially change the work, ask briefly whether to limit work to the selection or inspect and suggest changes. Do not force clarification when the user has already expressed a preference or delegated the judgment.
+Read `references/tool-interface.md` when composing calls or handling protection/truncation. Use the schema for fields and defaults.
 
-Match effort to the requested fidelity. A quick or approximate request calls for bounded planning; a precision-sensitive request may justify deeper work after alignment.
+## Establish the compression direction
 
-#### 2. Form a bounded semantic view
+If the user has not expressed a compression preference, ask before selecting ranges or investigating deeply:
 
-`inspect` returns factual structure with bounded user landmarks, grouped by user message. Use it for structure and volume, not to invent semantics. Ground candidates in visible conversation or a few targeted `locate` calls, and stop paging after the potentially relevant region. When exact candidate spans are known and their relative volume could change the choice, use read-only `inspect` spans to compare them without mutating the DraftPlan.
+> Do you want light cleanup or substantial room for what comes next? What should I focus on, and what must stay verbatim? You can give a target usage or delegate the choice.
 
-Segment by completed work phase, not message count. User-originated input and concluding Agent responses are useful landmarks for intent and outcome, but are not automatically KEEP. Intermediate tool exchanges may also contain decisions or evidence absent from the final response.
+Honor existing preferences; otherwise accept qualitative goals or delegation. Clarify ambiguous handoffs: refine the selection or work only within it? Respect explicit scope limits.
 
-| Often able to yield to a summary | Often load-bearing |
-|-----------------------------------|--------------------|
-| Repetitive or superseded exploration | Current intent and active constraints |
-| Tool output absorbed into a conclusion | Exact errors, evidence, or wording whose form matters |
-| A completed subtask's intermediate process | Decisions and rationale still governing the work |
-| A rejected attempt's mechanics | Its still-relevant failure reason |
+Match compression and investigation effort to that direction. Compare factual character/image measurements; do not promise exact post-commit token savings. If meeting a target requires sacrificing important information, explain the tradeoff.
 
-Use little or no `locate` during this reconnaissance. If a phase cannot yet be described faithfully, omit it from the proposal or mark it as needing confirmation rather than exploring the anchor broadly.
+## Select worthwhile ranges
 
-#### 3. Present semantic options and align
+Keep originals unless replacement serves the agreed goal; full-history coverage is not success.
 
-Before deep `locate` work or substantial DraftPlan mutation, establish the user's compression preference through explicit instruction, a reliable implication, or concise clarification.
+Use `inspect` for structure and volume, not to infer unseen content. Ground candidates in visible conversation or targeted `locate_ref`/`locate_search` calls. Investigate only what could change selection; omit uncertain candidates or ask if investigation exceeds the agreed effort. Use `measure` when relative sizes affect the choice.
 
-Describe each proposal in recognizable conversation terms:
+Weigh bulk removed against original detail lost and what retained context already carries. Technical eligibility alone does not justify compression.
 
-> From `<semantic start>` to `<semantic end>`, `<replace the whole phase / keep the endpoints and compress the work between>`; preserve `<load-bearing information>` in the summary.
+### Common patterns
 
-Use short recognizable excerpts when available and clear paraphrases otherwise. State whether the endpoint messages remain verbatim, what intermediate work disappears, and what the summary carries. Do not identify a user-facing range primarily by atom refs, DraftPlan ids, or arbitrary item numbers.
+These are examples, not fixed rules about message roles or age.
 
-When treatments involve a meaningful tradeoff, present concise alternatives and recommend one. A clear quick request may need only one proportionate proposal. Add factual content or image measurements only when they help the choice, and do not convert them into unsupported token-savings claims.
+- **Long execution between user messages.** Replace repetitive search, reading, editing, and testing when only results matter. Retain useful request/conclusion text and summarize key findings absent from it; tool output is not automatically noise.
+- **Multi-turn discussion.** Summarize superseded proposals, repeated clarification, and detours. Keep failure reasons that explain decisions or prevent repeated mistakes; age alone does not make discussion obsolete.
 
-#### 4. Resolve boundaries and build the DraftPlan
+One range reduces repetition in coherent discussion but may flatten distinctions. Semantic ranges allow different detail levels and KEEP holes, but risk duplication or broken causal links. Choose by content, not turn count; split around important originals.
 
-After the intended treatment is clear, use `request={action:"locate"}` for targeted content and boundary checks. An atom is the smallest selectable unit; a tool call and its matching results form one indivisible `tool_exchange` atom. Keep source text outside a range when exact wording or provenance matters and a summary cannot preserve it equivalently.
+### Preserve important user expression
 
-Choose boundaries from the information that must survive, not from a fixed category. A range may replace a whole semantic phase, including its initiating and concluding messages. It may instead retain a load-bearing user instruction and concluding Agent response while replacing only the execution between them. It may split around important material to leave KEEP holes. These are reasoning patterns, not rules tied to start mode, message age, or one prescribed kind of work.
+Keep important user goals, constraints, preferences, corrections, authorizations, and refusals verbatim by default. Summaries can alter their scope or force. Ask for explicit agreement before summarizing them; general permission for aggressive compression is insufficient.
 
-Build or refine the shared DraftPlan with `plan add`, `update`, `remove`, and `show`. A handed-off selection may be preserved or revised as the user's intent permits. Use separate ranges for non-contiguous phases; fill pending summaries before commit. If deeper inspection would materially change the agreed treatment, surface the change instead of silently applying it.
+Ask Question, questionnaire, and similar tool results may contain user expression. Judge by the speaker, not entry type. Retain the whole indivisible tool-exchange atom containing an important answer; split around it.
 
-Read `references/tool-interface.md` before retrying a rejected operation or when exact parameters, protected-atom causes, or measurements matter.
+Routine acknowledgements can be candidates; task completion alone does not invalidate important statements.
 
-#### 5. Write replacement summaries
+### Propose and stop
 
-A replacement summary is successor context for a future Agent, not a transcript or a prompt to perform compression. State the resulting knowledge and working state directly.
+Use conversation landmarks to explain replacements, originals kept, and summary contents. Offer alternatives for meaningful tradeoffs, not every delegated choice.
 
-Preserve, when applicable:
+Stop when the goal is reasonably served or further compression is not worth the loss, not when all eligible content is covered. Re-align if findings materially change the treatment.
 
-- user intent and active constraints;
-- decisions, conclusions, and necessary rationale;
-- relevant files, symbols, interfaces, commands, or configuration;
-- completed changes and validation results;
-- rejected approaches only when their failure reason still matters;
-- unresolved issues and any established next step or continuation state.
+## Write a local replacement
 
-Remove repetitive exploration, superseded hypotheses, raw output captured by a conclusion, and chronology with no remaining consequence. Do not turn uncertainty into fact, invent a next action, or use references that only make sense inside the removed text. If retained endpoint messages already carry part of the intended context, do not duplicate them mechanically; use the summary to preserve what would otherwise be lost.
+Summaries belong between retained earlier and later context, not as compression instructions or standalone handoffs.
 
-Organize by future utility rather than original chronology. When useful, use this compact frame without forcing empty fields:
+Preserve necessary causes, consequential actions and findings, and resulting knowledge. Name important files, symbols, commands, or artifacts with their roles. Distinguish proposals from changes and assumptions from observed results. Length follows information needs, not a fixed ratio.
 
-```text
-Goal and constraints:
-Established state and decisions:
-Artifacts and validation:
-Open issues and established next state:
-```
+Preserve consequential process, not activity logs. Replace vague “files changed, tests passed” with specific evidence: “Compared caller and parser, found ignored boundary arguments, added rejection, and verified an invalid-argument test.” Include relevant paths and results from the source.
 
-Length follows the information that must survive, not a target ratio. Final test: could a fresh Agent continue correctly from this summary plus retained context, without repeating work or violating a prior decision?
+### Fit the retained surroundings
 
-#### 6. Verify and hand off
+Read enough surrounding context to avoid duplication and preserve what it depends on from this range. Resolve dangling references without inventing facts. Recall is recovery, not a substitute for sufficient summaries.
 
-Call `request={action:"plan", op:"show"}`. Check that the intended semantic phases are covered, KEEP holes remain outside ranges, every range has a summary, and the summaries conserve the future working state.
+A range's end is a historical boundary, not automatically the present state:
 
-Describe the completed proposal with the same recognizable landmarks used during alignment. Direct the user to `/midcompact:select` or `/midcompact:select-webui` for boundaries and KEEP holes, and to `/midcompact:review` or `/midcompact:review-webui` for summary inspection or rejection. Use browser variants when the TUI is unavailable or preferred. Ask the user to run `/midcompact:commit` when ready; never commit for them.
+- Do not turn an old unfinished task into a current TODO. Omit it if later retained context resolves it and its earlier status adds nothing.
+- If the earlier status explains later events, describe it as historical. Do not attribute a later result to work within this range.
+- Include current open issues and established next steps only when the range reaches the current working frontier and continuation needs them. Never invent a next action.
 
-## Recall compressed content
+If later retained turns test and reject approach A, “Next: validate A” is stale. Preserve why A was proposed if needed to explain the rejection; leave later outcomes where they belong.
 
-Recall works with or without an active planning transaction. It reads committed blocks active on the current branch without changing projection or DraftPlan.
+## Build, check, and hand off
 
-### Recall workflow
+Resolve boundaries with targeted lookups; split around protected atoms. Use `plan_add`, `plan_update`, and `plan_remove`. Updates change summary/topic; boundaries require remove + add. Fill pending summaries before handoff.
 
-#### 1. Find the block
+Call `plan_show`; use `plan_read` when a stored summary needs full review. Check both:
 
-If its id is unknown, call `request={action:"recall", pattern:"..."}` to search active topics and summaries. A projected summary also states its block id and exact recall call.
+- **Selection:** Does each range serve the user's direction? Are important originals and intended KEEP holes retained? Has unnecessary full-history coverage crept in?
+- **Replacement:** Mentally remove the originals. Do summaries plus retained context explain the necessary causes, actions, evidence, and outcomes without gaps, vague claims, stale instructions, or state conflicts?
 
-#### 2. Retrieve the detail
+Report replacements, retained originals, and stopping rationale. Boundaries: `/midcompact:select` or `/midcompact:select-webui`. Summaries: `/midcompact:review` or `/midcompact:review-webui`. Prefer browser variants when TUI is unavailable or unwanted. Only the user runs `/midcompact:commit`.
 
-Call `request={action:"recall", ref:"c0001"}`. If the readable, structure-flattened result ends with a truncation marker, retry with `detail="full"`. Retrieve only what the current task needs; do not start or change a plan merely to recall history.
+## Recall
 
-## Tool conventions
+Recall reads active committed blocks without changing a plan and needs no transaction. If the id is unknown, use `request={action:"recall_list",pattern:"..."}` to search ids, topics, and summaries, not originals. Projected summaries carry block ids and recall calls.
 
-- `g0001` labels an inventory group; use its `a...` span as internal landmarks.
-- `a0001` is a transaction-local atom ref; `d1` is a DraftPlan range id; `c0001` is an active committed-block id.
-- Protected atoms cannot enter a range. Split around them.
+Use `request={action:"recall_read",block:"c0001"}`; retry truncation with `detail:"full"`. If still truncated, read `references/tool-interface.md`. Retrieve only needed content.
 
-These refs are planning handles, not the primary way to explain compression to the user. Read `references/tool-interface.md` for exact defaults and limits, rejected operations, protected-atom causes, measurements, repeated compression, or recall truncation.
+`a...` refs are transaction-local; `d...` identifies a plan range; `c...` a committed block. Inventory `g...` labels are display-only; use listed atom refs for calls.

package/skills/midcompact/references/tool-interface.md

@@ -1,87 +1,69 @@
-# Midcompact Tool Interface
+# Tool Call Patterns
 
-Read this reference when exact call requirements, limits, rejection behavior, repeated compression, or recall truncation matters. The main workflow remains in `../SKILL.md`.
+Use the schema for fields/defaults. Follow only the steps needed. Example refs and summaries must be replaced with verified content.
 
-## Parameter grouping
+## Survey where context space goes
 
-The parameters are one object with a single `request` field; `request` is a discriminated union where each branch binds one `action` value to exactly that action's fields and is closed (`additionalProperties: false`). A call that mixes actions (for example `locate` fields on `plan`) is rejected by the schema itself; do not repair it by dropping fields, re-issue the call with only the selected action's parameters. Shared field names (`ref`, `pattern`, `limit`, `detail`) are defined independently per action with the meaning documented in that section.
+Start a fresh Agent-direct transaction with:
 
-## Inspect
-
-Without `spans`, `request.action="inspect"` inventories the frozen anchor. It returns factual structure and bounded user landmarks, not full message bodies, assistant/tool previews, summaries, or image base64.
-
-- `page_size`: default 20 groups, maximum 50.
-- `cursor`: opaque value returned by the previous page.
-- Results include group refs, atom spans, content chars, image facts, protected/compressible counts, and Pi-reported anchor usage.
-
-Stop paging after the candidate regions are covered.
-
-To compare explicit candidates without mutating the DraftPlan, pass one or more possibly overlapping spans:
-
-```text
-midcompact(request={action:"inspect", spans=[
-  {"start":"a0006","end":"a0014"},
-  {"start":"a0006","end":"a0020"}
-]})
+```json
+{"request":{"action":"inspect"}}
 ```
 
-Span inspection reports bounded endpoint landmarks, atom/message and role counts, tool exchanges and calls, factual content share, images, and protected/compressible counts. It has a 12,000-character total output budget and reports how many requested spans fit. It does not report per-span tokens: Pi supplies usage for the whole anchor, not token attribution by range. Do not combine `spans` with `page_size` or `cursor`.
-
-## Locate
+Read overall Pi token usage and chronological groups: user landmarks, endpoints, characters, images, protection counts. This paginated volume distribution is not a per-group token curve. Large groups invite investigation, not automatic compression.
 
-`request.action="locate"` returns atoms from the frozen anchor. Supply either:
+Continue with the returned `cursor` only where relevant. Use listed `a...` refs, not display-only `g...` labels. Landmarks are not full content; combine the overview with user preferences before selection.
 
-- `ref`: one direct atom lookup; or
-- at least one real filter: `pattern`, `tool_name`, or `source` other than `any`.
+## Find evidence and check boundaries
 
-With no lookup or filter it returns no matches rather than an error. Filtered searches return at most three brief candidates; when more match, the result reports the total and asks for a more specific pattern or additional filter. `direction` is `oldest` by default or `newest`; `limit` may request one to three results.
+For a recent bash result containing a known phrase:
 
-Brief direct lookups preserve both ends of an atom landmark. Pattern searches show a bounded excerpt around the match rather than the atom prefix. `detail="full"` is allowed only with one direct `ref` and preserves both ends with an explicit middle-omission marker when the 12,000-character atom limit is exceeded.
+```json
+{"request":{"action":"locate_search","source":"tool_result","tool_name":"bash","pattern":"timeout","direction":"newest"}}
+```
 
-A `g...` inventory ref is not a locate ref; use the group's `a...` start/end landmarks.
+Filters combine with AND. Use a returned atom ref to inspect the match:
 
-## Plan
+```json
+{"request":{"action":"locate_ref","ref":"a0007","detail":"full"}}
+```
 
-`request.action="plan"` uses `op="show"` by default. Agent and user mutate the same DraftPlan.
+Known refs need no search. Excerpts are incomplete; `full` can omit the middle. Check markers before drawing conclusions. Narrow excessive matches with filters. Recover unknown refs using `inspect` or `locate_search`; `measure` needs known refs.
 
-| op | Required fields |
-|----|-----------------|
-| `show` | none; optional `draft_id` for one range |
-| `add` | `start`, `end`; optional `summary`, `topic` |
-| `update` | `draft_id` and at least one of `summary`, `topic` |
-| `remove` | `draft_id` |
+## Compare candidates without changing the plan
 
-Default show lists each range with bounded `from`, `to`, and `summary` landmarks plus factual metrics. Use `op="show", detail="full", draft_id="d1"` for one stored summary and endpoint previews under a 40,000-character total budget; full detail without `draft_id` is rejected. Show is read-only and does not persist a duplicate DraftPlan entry.
+```json
+{"request":{"action":"measure","candidates":[{"start":"a0006","end":"a0014"},{"start":"a0006","end":"a0020"}]}}
+```
 
-Add/update return the changed range in brief form; remove returns its id and compact draft totals. Mutation responses omit the Pi-awareness header and unchanged ranges. Use explicit show when complete awareness is needed.
+Candidates may overlap without changing the plan. Compare landmarks, content share, images, and protection, not assumed token savings. If fewer candidates are reported than requested, measure the remainder separately.
 
-An omitted or empty `summary` creates a pending range. Review can open it, but commit requires at least one range and a non-empty summary for every range. Changing boundaries requires removing the old range and adding the replacement.
+## Keep important originals between ranges
 
-### Add rejection conditions
+If an important user answer occupies `a0010`, locate it and verify boundaries, then add separate ranges on its two sides:
 
-| Condition | Response |
-|-----------|----------|
-| The range crosses a protected atom | Split the range around that atom |
-| The range overlaps an existing draft range | Remove or replace the existing range first |
-| `start` occurs after `end` | Correct the positional order |
-| An atom ref is unknown | Re-run inspect/locate against the current transaction snapshot |
+```json
+{"request":{"action":"plan_add","start":"a0006","end":"a0009","summary":"<replacement for the earlier work>"}}
+{"request":{"action":"plan_add","start":"a0011","end":"a0014","summary":"<replacement for the later work>"}}
+```
 
-An atom is protected when its tool protocol is incomplete or orphaned, it represents an existing compressed block, its message kind is unsupported, or it lacks the persistent session entry needed to anchor compression.
+Question-tool answers are user expression. Keep the whole tool-exchange atom containing an important answer; do not split a call from its results. Unlike measurement candidates, plan ranges cannot overlap or contain protected atoms.
 
-## Telemetry
+## Refine an existing plan
 
-Explicit `plan show` includes Pi-reported anchor usage when available and factual draft measurements: original/replacement content chars, image count, and decoded payload bytes. Mutation results omit awareness and report only compact totals plus the changed range where one remains. Local character or image measurements are not converted into token savings or projected-token percentages. Use measurements to compare the proposal with user-directed depth, not as an optimization target.
+Start with `plan_show`. Use `plan_read` with its returned `range_id` when the stored summary or endpoints need full review. Change summary/topic with `plan_update`.
 
-## Repeated compression
+For new boundaries, first read and retain the existing summary/topic and verify the replacement endpoints. Then `plan_remove` the old range and `plan_add` its replacement. Do not assume the new id is unchanged. Check the resulting plan; mutation replies show the changed item and compact totals, not all ranges. Fill pending summaries before handoff; only the user commits.
 
-Committed blocks appear as protected atoms in later transaction snapshots and cannot be compressed again. A later transaction may compress newly accumulated raw history around those blocks. Re-run inspect/locate because atom refs are transaction-local.
+## Work around protected content
 
-## Recall
+Split around protected atoms. Causes include incomplete tool exchanges, unsupported message kinds, missing persistent entries, and existing committed blocks. Later transactions can compress remaining raw history around those blocks, not recompress the blocks themselves. Obtain current atom refs from `inspect`; refs are transaction-local.
 
-`request.action="recall"` works independently of a planning transaction and reads committed blocks active on the current branch.
+## Retrieve committed evidence
 
-- Without `ref`, `pattern` searches block topics and summaries; `limit` defaults to 8 and has a maximum of 20.
-- With `ref="c0001"`, the tool renders that block's stored messages.
-- `detail="full"` raises the rendering cap when the normal result is truncated.
+```json
+{"request":{"action":"recall_list","pattern":"timeout"}}
+{"request":{"action":"recall_read","block":"c0001"}}
+```
 
-Recall has no paging. The truncation marker is `[truncated; refine the recall request or inspect the source session for more]`. If `detail="full"` still truncates before the needed detail, report that recall cannot expose the omitted content; do not infer it.
+Use the actual block id returned by the list; skip listing when known. Listing searches ids/topics/summaries, not originals. Recall needs no transaction. If truncated, retry the same block with `detail:"full"`. There is no paging: if still truncated, report that recall cannot expose the omitted evidence. Do not infer it or start another transaction as a recovery workaround. Inspecting the source session requires a separate available means; this tool offers none.

package/src/SPEC.md

@@ -71,12 +71,16 @@ package.json → `pi.extensions`).
 ## External contracts (reference, don't duplicate)
 
 - Tool: one `midcompact` tool whose parameters are `{ request: <union> }` —
-  a root `type: "object"` wrapping a discriminated union on `action`
-  (inspect/locate/plan/recall); each branch is closed
-  (`additionalProperties: false`), so cross-action parameters are
-  schema-rejected. The `request` wrapper exists because some providers
-  (e.g. DeepSeek) reject a root-level `anyOf` before the model sees the
-  schema.
+  a root `type: "object"` wrapping a union of 11 single-purpose actions
+  (inspect/measure/locate_ref/locate_search/plan_show/plan_read/plan_add/
+  plan_update/plan_remove/recall_list/recall_read); each branch is closed
+  (`additionalProperties: false`), so extra fields are rejected (schema where
+  enforced, runtime backstop everywhere — a silently ignored field is a bug).
+  Former second-level discriminators (plan `op`, locate ref-vs-filter, recall
+  list-vs-render, inspect inventory-vs-spans) are flattened into branches so
+  field legality is schema-visible. The `request` wrapper exists because some
+  providers (e.g. DeepSeek) reject a root-level `anyOf` before the model sees
+  the schema.
   Details: `skills/midcompact/references/tool-interface.md`.
 - Commands: `midcompact:start|abort|commit|review|review-webui|select|select-webui|status`;
   no composite `/midcompact`; native naming convention `name:sub` (Pi's
@@ -104,6 +108,7 @@ package.json → `pi.extensions`).
 
 ## Change rules
 
+- Model-facing copy (schema descriptions, prompts, errors, notices, skill docs) follows `.dev/docs/agent-vocabulary.md`; a new action, field, or concept is registered there **before** implementation.
 - Adding a tool action → new request branch + handler type + tool-interface
   section + SKILL.md routing; adding parameters to an action → its branch
   only (the union stays nested under `request`).

package/src/index.ts

@@ -63,13 +63,16 @@ import {
 
 const TOOL_NAME = "midcompact";
 const TOOL_DESCRIPTION =
-  "Inventory, locate, draft, or recall mid-context compression. Use the `midcompact` skill to route planning versus recall; during an active transaction, follow the runtime prompt for the state-specific first action.";
+  "Inspect, measure, locate, plan, or recall mid-context compression. Use the `midcompact` skill to route planning versus recall; during an active transaction, follow the runtime prompt for the state-specific first action.";
 const STATUS_KEY = "midcompact";
 const START_PROMPT_PREFIX = "A mid-compaction transaction is active on a frozen anchor snapshot.";
 
-// Canonical request model: one branch per action, and each branch owns exactly
-// its own fields (additionalProperties: false). The discriminant is a
-// single-value StringEnum instead of Type.Literal so it serializes as
+// Canonical request model: one branch per operation, and each branch owns
+// exactly its own fields (additionalProperties: false). Second-level operation
+// discriminators (the former plan `op`, locate ref-vs-filter, recall
+// list-vs-render, inspect inventory-vs-spans) are flattened into top-level
+// branches so field legality is visible in the schema itself. The discriminant
+// is a single-value StringEnum instead of Type.Literal so it serializes as
 // string+enum, which restricted JSON-Schema subsets (e.g. DeepSeek) accept
 // more readily than const.
 //
@@ -80,66 +83,165 @@ const START_PROMPT_PREFIX = "A mid-compaction transaction is active on a frozen
 // skills/midcompact/references/tool-interface.md.
 const InspectRequest = Type.Object(
   {
-    action: StringEnum(["inspect"] as const, { description: "Inventory the frozen anchor, or measure explicit candidate spans." }),
-    spans: Type.Optional(Type.Array(Type.Object({ start: Type.String(), end: Type.String() }), { description: "Candidate spans to measure, as {start,end} atom refs." })),
-    page_size: Type.Optional(Type.Number({ description: "Inventory groups per page (default 20, max 50)." })),
+    action: StringEnum(["inspect"] as const, { description: "Page through the frozen anchor inventory: groups, refs, sizes, protected/compressible counts." }),
+    page_size: Type.Optional(Type.Number({ description: "Groups per page (default 20, max 50; out-of-range values are clamped)." })),
     cursor: Type.Optional(Type.String({ description: "Pagination cursor from the previous page." })),
   },
   { additionalProperties: false },
 );
 
-const LocateRequest = Type.Object(
+const MeasureRequest = Type.Object(
   {
-    action: StringEnum(["locate"] as const, { description: "Locate atoms in the frozen anchor by ref or filters." }),
-    ref: Type.Optional(Type.String({ description: "One direct atom ref; mutually exclusive with search filters." })),
-    pattern: Type.Optional(Type.String({ description: "Content filter over anchor atoms." })),
-    source: Type.Optional(StringEnum(["any", "user", "assistant", "tool_call", "tool_result"] as const, { description: "Filter by entry source." })),
-    tool_name: Type.Optional(Type.String({ description: "Filter by originating tool name." })),
+    action: StringEnum(["measure"] as const, { description: "Measure candidate {start,end} atom spans without changing the plan." }),
+    candidates: Type.Array(
+      Type.Object({ start: Type.String({ description: "Candidate start atom ref." }), end: Type.String({ description: "Candidate end atom ref." }) }),
+      { minItems: 1, description: "Candidate spans to measure, e.g. [{start:\"a0006\",end:\"a0014\"}]." },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const LocateRefRequest = Type.Object(
+  {
+    action: StringEnum(["locate_ref"] as const, { description: "Look up one atom by ref in the frozen anchor." }),
+    ref: Type.String({ description: "Atom ref, e.g. a0001. Group labels shown by inspect are not atom refs." }),
+    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "brief (default) bounded preview; full atom text up to 12,000 characters." })),
+  },
+  { additionalProperties: false },
+);
+
+const LocateSearchRequest = Type.Object(
+  {
+    action: StringEnum(["locate_search"] as const, { description: "Search anchor atoms with at least one filter; filters combine conjunctively (AND)." }),
+    pattern: Type.Optional(Type.String({ description: "Case-insensitive substring filter over atom text." })),
+    source: Type.Optional(StringEnum(["user", "assistant", "tool_call", "tool_result"] as const, { description: "Filter by entry source class." })),
+    tool_name: Type.Optional(Type.String({ description: "Exact (case-insensitive) match on the originating tool name." })),
     direction: Type.Optional(StringEnum(["oldest", "newest"] as const, { description: "Match ordering, oldest (default) or newest." })),
-    limit: Type.Optional(Type.Number({ description: "1-3 results for filtered searches." })),
-    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "brief (default) or full atom output." })),
+    limit: Type.Optional(Type.Number({ description: "1-3 results (out-of-range values are clamped)." })),
+  },
+  { additionalProperties: false },
+);
+
+const PlanShowRequest = Type.Object(
+  {
+    action: StringEnum(["plan_show"] as const, { description: "List every plan range in brief form with plan telemetry." }),
   },
   { additionalProperties: false },
 );
 
-const PlanRequest = Type.Object(
+const PlanReadRequest = Type.Object(
   {
-    action: StringEnum(["plan"] as const, { description: "Show or mutate the shared DraftPlan." }),
-    op: Type.Optional(StringEnum(["show", "add", "update", "remove"] as const, { description: "show (default) / add / update / remove." })),
-    start: Type.Optional(Type.String({ description: "add: range start atom ref." })),
-    end: Type.Optional(Type.String({ description: "add: range end atom ref." })),
-    draft_id: Type.Optional(Type.String({ description: "show/update/remove: target draft range id." })),
-    topic: Type.Optional(Type.String({ description: "add/update: range topic." })),
-    summary: Type.Optional(Type.String({ description: "add/update: range summary (omitted or empty = pending range)." })),
-    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "show: brief (default) or full range output." })),
+    action: StringEnum(["plan_read"] as const, { description: "Read one plan range in full: stored summary and endpoint previews under a 40,000-character budget." }),
+    range_id: Type.String({ description: "Target range id from plan_show, e.g. d1." }),
   },
   { additionalProperties: false },
 );
 
-const RecallRequest = Type.Object(
+const PlanAddRequest = Type.Object(
   {
-    action: StringEnum(["recall"] as const, { description: "Read committed compression blocks; works without a transaction." }),
-    ref: Type.Optional(Type.String({ description: "One committed block id, e.g. c0001; renders its messages." })),
-    pattern: Type.Optional(Type.String({ description: "Filter block topics and summaries." })),
-    limit: Type.Optional(Type.Number({ description: "Blocks to list (default 8, max 20)." })),
-    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "full raises the rendering cap on truncated blocks." })),
+    action: StringEnum(["plan_add"] as const, { description: "Add one range over contiguous atoms; boundaries are immutable after add." }),
+    start: Type.String({ description: "Range start atom ref." }),
+    end: Type.String({ description: "Range end atom ref (inclusive)." }),
+    summary: Type.Optional(Type.String({ description: "Replacement summary; omitted or empty leaves the range pending." })),
+    topic: Type.Optional(Type.String({ description: "Optional range topic." })),
+  },
+  { additionalProperties: false },
+);
+
+const PlanUpdateRequest = Type.Object(
+  {
+    action: StringEnum(["plan_update"] as const, { description: "Update one range's summary and/or topic; boundaries change via plan_remove + plan_add." }),
+    range_id: Type.String({ description: "Target range id, e.g. d1." }),
+    summary: Type.Optional(Type.String({ description: "New summary; empty string marks the range pending." })),
+    topic: Type.Optional(Type.String({ description: "New topic." })),
+  },
+  { additionalProperties: false },
+);
+
+const PlanRemoveRequest = Type.Object(
+  {
+    action: StringEnum(["plan_remove"] as const, { description: "Remove one range from the plan." }),
+    range_id: Type.String({ description: "Target range id, e.g. d1." }),
+  },
+  { additionalProperties: false },
+);
+
+const RecallListRequest = Type.Object(
+  {
+    action: StringEnum(["recall_list"] as const, { description: "List committed blocks; works without a transaction." }),
+    pattern: Type.Optional(Type.String({ description: "Case-insensitive filter over block id, topic, and summary (not original content)." })),
+    limit: Type.Optional(Type.Number({ description: "Blocks to list (default 8, max 20; out-of-range values are clamped)." })),
+  },
+  { additionalProperties: false },
+);
+
+const RecallReadRequest = Type.Object(
+  {
+    action: StringEnum(["recall_read"] as const, { description: "Render one committed block's original messages." }),
+    block: Type.String({ description: "Committed block id, e.g. c0001." }),
+    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "full raises the rendering cap from 12,000 to 40,000 characters on truncated blocks." })),
   },
   { additionalProperties: false },
 );
 
 const Params = Type.Object(
-  { request: Type.Union([InspectRequest, LocateRequest, PlanRequest, RecallRequest]) },
+  {
+    request: Type.Union([
+      InspectRequest,
+      MeasureRequest,
+      LocateRefRequest,
+      LocateSearchRequest,
+      PlanShowRequest,
+      PlanReadRequest,
+      PlanAddRequest,
+      PlanUpdateRequest,
+      PlanRemoveRequest,
+      RecallListRequest,
+      RecallReadRequest,
+    ]),
+  },
   {
     additionalProperties: false,
-    description: "`request.action` selects exactly one request shape; fields of the other actions are not valid.",
+    description: "`request.action` selects exactly one request shape; each shape accepts only its own fields.",
   },
 );
 
 type ToolParams = Static<typeof Params>;
 type InspectRequestType = Static<typeof InspectRequest>;
-type LocateRequestType = Static<typeof LocateRequest>;
-type PlanRequestType = Static<typeof PlanRequest>;
-type RecallRequestType = Static<typeof RecallRequest>;
+type MeasureRequestType = Static<typeof MeasureRequest>;
+type LocateRefRequestType = Static<typeof LocateRefRequest>;
+type LocateSearchRequestType = Static<typeof LocateSearchRequest>;
+type PlanShowRequestType = Static<typeof PlanShowRequest>;
+type PlanReadRequestType = Static<typeof PlanReadRequest>;
+type PlanAddRequestType = Static<typeof PlanAddRequest>;
+type PlanUpdateRequestType = Static<typeof PlanUpdateRequest>;
+type PlanRemoveRequestType = Static<typeof PlanRemoveRequest>;
+type RecallListRequestType = Static<typeof RecallListRequest>;
+type RecallReadRequestType = Static<typeof RecallReadRequest>;
+
+// Runtime closure backstop: providers are not trusted to enforce
+// additionalProperties at call time, and a silently ignored field is worse
+// than a rejection. Keys are the per-branch optional/required fields besides
+// the discriminant.
+const BRANCH_FIELDS: Record<ToolParams["request"]["action"], readonly string[]> = {
+  inspect: ["page_size", "cursor"],
+  measure: ["candidates"],
+  locate_ref: ["ref", "detail"],
+  locate_search: ["pattern", "source", "tool_name", "direction", "limit"],
+  plan_show: [],
+  plan_read: ["range_id"],
+  plan_add: ["start", "end", "summary", "topic"],
+  plan_update: ["range_id", "summary", "topic"],
+  plan_remove: ["range_id"],
+  recall_list: ["pattern", "limit"],
+  recall_read: ["block", "detail"],
+};
+
+function rejectExtraFields(request: ToolParams["request"]): void {
+  const allowed: readonly string[] = BRANCH_FIELDS[request.action];
+  const extras = Object.keys(request).filter((key) => key !== "action" && !allowed.includes(key));
+  if (extras.length > 0) throw new Error(`${request.action} does not accept: ${extras.join(", ")}.`);
+}
 
 type RuntimeSnapshot = { atoms: Atom[]; anchorState?: CompressionState };
 
@@ -193,9 +295,9 @@ export default function (pi: ExtensionAPI) {
       message: {
         customType: "midcompact-handoff",
         content: [
-          "An active midcompact transaction exists with a persisted DraftPlan.",
-          `Draft revision ${currentDraft.revision}; ${currentDraft.ranges.length} existing range(s), which may have been created by the user.`,
-          "If the current user request asks to continue midcompact, read the `midcompact` skill first, then call midcompact(request={action:\"plan\", op:\"show\"}) before any other midcompact action. Treat the existing plan as the current shared draft. Infer from the user's request whether to preserve, refine, or extend it; ask only if materially ambiguous.",
+          "An active midcompact transaction exists with a persisted plan.",
+          `Plan revision ${currentDraft.revision}; ${currentDraft.ranges.length} existing range(s), which may have been created by the user.`,
+          "If the current user request asks to continue midcompact, read the `midcompact` skill first, then call midcompact(request={action:\"plan_show\"}) before any other midcompact action. Treat the existing plan as the shared starting point. Infer from the user's request whether to preserve, refine, or extend it; ask only if materially ambiguous.",
         ].join("\n"),
         display: false,
       },
@@ -239,21 +341,21 @@ export default function (pi: ExtensionAPI) {
     },
   });
   pi.registerCommand("midcompact:commit", {
-    description: "Commit the current draft to the branch state",
+    description: "Commit the current plan to the branch state",
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
       await ctx.waitForIdle();
       return commitTransaction(ctx);
     },
   });
   pi.registerCommand("midcompact:review", {
-    description: "Open the interactive TUI review to inspect and edit the draft",
+    description: "Open the interactive TUI review to inspect and edit the plan",
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
       await ctx.waitForIdle();
       return reviewTransaction(ctx, "tui");
     },
   });
   pi.registerCommand("midcompact:review-webui", {
-    description: "Open a local web page to inspect and edit the draft (works without TUI)",
+    description: "Open a local web page to inspect and edit the plan (works without TUI)",
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
       await ctx.waitForIdle();
       return reviewTransaction(ctx, "web");
@@ -274,7 +376,7 @@ export default function (pi: ExtensionAPI) {
     },
   });
   pi.registerCommand("midcompact:status", {
-    description: "Show current transaction and draft status",
+    description: "Show current transaction and plan status",
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
       await ctx.waitForIdle();
       return showStatus(ctx);
@@ -346,7 +448,7 @@ export default function (pi: ExtensionAPI) {
       return;
     }
     if (!tryAcquireUi(planningLock)) {
-      ctx.ui.notify("The Agent is currently processing the midcompact draft. Try Selection after the Agent turn ends.", "warning");
+      ctx.ui.notify("The Agent is currently processing the midcompact plan. Try Selection after the Agent turn ends.", "warning");
       return;
     }
 
@@ -364,12 +466,12 @@ export default function (pi: ExtensionAPI) {
         if (action.action === "save") {
           try {
             applySelection(action.spans ?? [], action.keepRefs ?? []);
-            ctx.ui.notify("DraftPlan saved. Tell the Agent to continue processing it when ready.", "info");
+            ctx.ui.notify("Plan saved. Tell the Agent to continue processing it when ready.", "info");
           } catch (error) {
             ctx.ui.notify(`Selection could not be saved: ${error instanceof Error ? error.message : String(error)}`, "warning");
           }
         } else {
-          ctx.ui.notify("Selection closed. The DraftPlan remains available; reopen select or tell the Agent to continue.", "info");
+          ctx.ui.notify("Selection closed. The plan remains available; reopen select or tell the Agent to continue.", "info");
         }
         return;
       }
@@ -386,7 +488,7 @@ export default function (pi: ExtensionAPI) {
           updateStatus(ctx, currentTx, draft, planningLock.owner);
         },
       }, "selection", { openBrowser: openReviewWebBrowser });
-      ctx.ui.notify("Selection closed. The DraftPlan is saved; tell the Agent to continue when ready.", "info");
+      ctx.ui.notify("Selection closed. The plan is saved; tell the Agent to continue when ready.", "info");
     } finally {
       releaseUi(planningLock);
     }
@@ -397,17 +499,17 @@ export default function (pi: ExtensionAPI) {
     const promptLines = [
       START_PROMPT_PREFIX,
       awareness,
-      "The extension provides inspect for bounded inventory, locate for local details, plan show/add/update/remove for one shared DraftPlan, and recall for committed blocks.",
-      "The user owns the final compression decision. You may edit the DraftPlan, but you must not commit. Preserve facts that future work still needs; local character and image counts are not token estimates.",
+      "The extension provides inspect for the bounded inventory, measure for candidate spans, locate for atom details, plan_show/plan_read/plan_add/plan_update/plan_remove for one shared plan, and recall_list/recall_read for committed blocks.",
+      "The user owns the final compression decision. You may edit the plan, but you must not commit. Preserve facts that future work still needs; local character and image counts are not token estimates.",
     ];
     if (customInstructions) promptLines.push(`User focus: ${customInstructions}`);
     if (mode === "agent") {
       promptLines.push(
-        "FINAL STATE: AGENT DIRECT. The new DraftPlan is empty. Read the `midcompact` skill before doing any planning work, then call inspect first and use locate and plan to create ranges and summaries. Stop before commit.",
+        "FINAL STATE: AGENT DIRECT. The new plan is empty. Read the `midcompact` skill before doing any planning work, then call inspect first and use measure, locate, and the plan actions to create ranges and summaries. Stop before commit.",
       );
     } else {
       promptLines.push(
-        "FINAL STATE: USER MANUAL. The user is about to edit the initial DraftPlan. Acknowledge with OK only. Do not call any midcompact tool, inspect, locate, plan, or recall; do not change the draft or commit. Wait until the user finishes editing and sends a later request. On that later request, read the `midcompact` skill before doing any planning work, then call plan show first.",
+        "FINAL STATE: USER MANUAL. The user is about to edit the initial plan. Acknowledge with OK only. Do not call any midcompact action; do not change the plan or commit. Wait until the user finishes editing and sends a later request. On that later request, read the `midcompact` skill before doing any planning work, then call plan_show first.",
       );
     }
     await pi.sendUserMessage(promptLines.join("\n"));
@@ -415,7 +517,7 @@ export default function (pi: ExtensionAPI) {
 
   async function abortTransaction(ctx: ExtensionCommandContext): Promise<void> {
     if (planningLock.owner === "agent") {
-      ctx.ui.notify("The Agent is currently processing the midcompact draft. Abort after the Agent turn ends.", "warning");
+      ctx.ui.notify("The Agent is currently processing the midcompact plan. Abort after the Agent turn ends.", "warning");
       return;
     }
     const restored = restoreTransaction(ctx.sessionManager.getBranch() as SessionEntry[]);
@@ -439,7 +541,7 @@ export default function (pi: ExtensionAPI) {
 
   async function commitTransaction(ctx: ExtensionCommandContext): Promise<void> {
     if (planningLock.owner === "agent") {
-      ctx.ui.notify("The Agent is currently processing the midcompact draft. Commit after the Agent turn ends.", "warning");
+      ctx.ui.notify("The Agent is currently processing the midcompact plan. Commit after the Agent turn ends.", "warning");
       return;
     }
     const restored = restoreTransaction(ctx.sessionManager.getBranch() as SessionEntry[]);
@@ -450,7 +552,7 @@ export default function (pi: ExtensionAPI) {
       return;
     }
     if (!currentDraft?.ranges.length) {
-      ctx.ui.notify("Draft is empty; nothing to commit.", "warning");
+      ctx.ui.notify("Plan is empty; nothing to commit.", "warning");
       return;
     }
     // Commit validation: reject empty summary, invalid boundaries, overlaps, protected atoms.
@@ -508,7 +610,7 @@ export default function (pi: ExtensionAPI) {
       return;
     }
     if (!tryAcquireUi(planningLock)) {
-      ctx.ui.notify("The Agent is currently processing the midcompact draft. Try opening review after the Agent turn ends.", "warning");
+      ctx.ui.notify("The Agent is currently processing the midcompact plan. Try opening review after the Agent turn ends.", "warning");
       return;
     }
     try {
@@ -579,7 +681,7 @@ export default function (pi: ExtensionAPI) {
   /** Agent tool path: all active-transaction operations yield to an editing UI. */
   function requireAgentAccess(ctx: ExtensionContext): boolean {
     if (!acquireAgent(planningLock)) {
-      ctx.ui.notify("A Selection/Review UI is currently editing the midcompact draft. Close it before the Agent can continue.", "warning");
+      ctx.ui.notify("A Selection/Review UI is currently editing the midcompact plan. Close it before the Agent can continue.", "warning");
       return false;
     }
     return true;
@@ -600,7 +702,9 @@ export default function (pi: ExtensionAPI) {
     async execute(_id: string, params: ToolParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
       try {
         const request = params.request;
-        if (request.action === "recall") return toolResult(handleRecall(request, ctx));
+        rejectExtraFields(request);
+        if (request.action === "recall_list") return toolResult(handleRecallList(request, ctx));
+        if (request.action === "recall_read") return toolResult(handleRecallRead(request, ctx));
         const restored = restoreTransaction(ctx.sessionManager.getBranch() as SessionEntry[]);
         const currentTx = withCompatDefaults(restored.transaction ?? transaction);
         if (!currentTx) return toolResult("No active midcompact transaction. Ask the user to run `/midcompact:start` first.");
@@ -611,17 +715,22 @@ export default function (pi: ExtensionAPI) {
         }
         const snapshot = buildAnchorSnapshot(ctx.sessionManager, currentTx);
 
-        if (request.action === "inspect") return toolResult(handleInspect(request, snapshot.atoms, currentTx));
-        if (request.action === "locate") return toolResult(handleLocate(request, snapshot.atoms));
-        if (request.action === "plan") {
-          const result = handlePlan(request, draft!, snapshot.atoms);
-          if (result.op === "show") {
-            return toolResult(formatDraft(draft!, draftTelemetry(transaction, draft), {
-              detail: request.detail,
-              draftId: request.draft_id,
-              atoms: snapshot.atoms,
-            }));
-          }
+        if (request.action === "inspect") return toolResult(handleInventory(request, snapshot.atoms, currentTx));
+        if (request.action === "measure") return toolResult(handleMeasure(request, snapshot.atoms));
+        if (request.action === "locate_ref") return toolResult(handleLocateRef(request, snapshot.atoms));
+        if (request.action === "locate_search") return toolResult(handleLocateSearch(request, snapshot.atoms));
+        if (request.action === "plan_show") {
+          return toolResult(formatDraft(draft!, draftTelemetry(transaction, draft), { atoms: snapshot.atoms }));
+        }
+        if (request.action === "plan_read") {
+          return toolResult(formatDraft(draft!, draftTelemetry(transaction, draft), {
+            detail: "full",
+            draftId: request.range_id,
+            atoms: snapshot.atoms,
+          }));
+        }
+        if (request.action === "plan_add" || request.action === "plan_update" || request.action === "plan_remove") {
+          const result = handlePlanMutation(draft!, snapshot.atoms, request);
           draft = result.draft;
           pi.appendEntry(DRAFT_ENTRY, draft);
           updateStatus(ctx, transaction, draft, planningLock.owner);
@@ -634,31 +743,37 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  function handleInspect(params: InspectRequestType, atoms: Atom[], tx: TransactionState): string {
-    if (params.spans) {
-      if (params.page_size !== undefined || params.cursor !== undefined) {
-        throw new Error("inspect spans cannot be combined with inventory pagination.");
-      }
-      return formatSpanInspection(atoms, params.spans);
-    }
+  function handleInventory(params: InspectRequestType, atoms: Atom[], tx: TransactionState): string {
     const page = buildInventory(atoms, { pageSize: params.page_size, cursor: params.cursor }, { transaction: tx });
     return formatInventory(page);
   }
 
-  function handleRecall(params: RecallRequestType, ctx: ExtensionContext): string {
+  function handleMeasure(params: MeasureRequestType, atoms: Atom[]): string {
+    if (!params.candidates?.length) throw new Error("measure requires at least one start/end candidate.");
+    return formatSpanInspection(atoms, params.candidates);
+  }
+
+  function restoreBranchState(ctx: ExtensionContext): CompressionState | undefined {
+    return restoreCompressionState(ctx.sessionManager.getBranch() as SessionEntry[]) ?? activeState;
+  }
+
+  function handleRecallList(params: RecallListRequestType, ctx: ExtensionContext): string {
+    const branchState = restoreBranchState(ctx);
+    if (!branchState?.blocks.length) return "No compressed blocks are active on this branch.";
+    const query = (params.pattern ?? "").trim().toLocaleLowerCase();
+    const matches = branchState.blocks.filter((block) => !query || `${block.id}\n${block.topic ?? ""}\n${block.summary}`.toLocaleLowerCase().includes(query));
+    if (!matches.length) return "No compressed blocks matched.";
+    return matches.slice(0, Math.max(1, Math.min(params.limit ?? 8, 20))).map((block) =>
+      `${block.id}${block.topic ? ` | ${block.topic}` : ""} | ${block.originalContentChars ?? 0} original chars${block.originalImageCount ? ` · ${block.originalImageCount} images` : ""}\n${block.summary}`
+    ).join("\n\n");
+  }
+
+  function handleRecallRead(params: RecallReadRequestType, ctx: ExtensionContext): string {
     const sm = ctx.sessionManager;
-    const branchState = restoreCompressionState(sm.getBranch() as SessionEntry[]) ?? activeState;
+    const branchState = restoreBranchState(ctx);
     if (!branchState?.blocks.length) return "No compressed blocks are active on this branch.";
-    if (!params.ref) {
-      const query = (params.pattern ?? "").trim().toLocaleLowerCase();
-      const matches = branchState.blocks.filter((block) => !query || `${block.id}\n${block.topic ?? ""}\n${block.summary}`.toLocaleLowerCase().includes(query));
-      if (!matches.length) return "No compressed blocks matched.";
-      return matches.slice(0, Math.max(1, Math.min(params.limit ?? 8, 20))).map((block) =>
-        `${block.id}${block.topic ? ` | ${block.topic}` : ""} | ${block.originalContentChars ?? 0} original chars${block.originalImageCount ? ` · ${block.originalImageCount} images` : ""}\n${block.summary}`
-      ).join("\n\n");
-    }
-    const block = branchState.blocks.find((candidate) => candidate.id === params.ref);
-    if (!block) return `Unknown compressed block ${params.ref}.`;
+    const block = branchState.blocks.find((candidate) => candidate.id === params.block);
+    if (!block) return `Unknown compressed block ${params.block}.`;
     const byId = new Map((sm.getEntries() as SessionEntry[]).map((entry) => [entry.id, entry]));
     const parts: string[] = [];
     for (const id of block.entryIds) {
@@ -681,59 +796,58 @@ export default function (pi: ExtensionAPI) {
 
 // ---- Pure handlers ----
 
-function handleLocate(params: LocateRequestType, atoms: Atom[]): string {
-  const hasFilter = Boolean(params.pattern || params.tool_name || (params.source && params.source !== "any"));
-  if (params.ref && hasFilter) {
-    throw new Error("locate accepts either one direct ref or search filters, not both.");
-  }
-  if (params.detail === "full" && !params.ref) {
-    throw new Error("locate detail=full requires one direct atom ref.");
+function handleLocateRef(params: LocateRefRequestType, atoms: Atom[]): string {
+  const result = locateAtomMatches(atoms, { ref: params.ref });
+  if (!result.atoms.length) return "No matching atoms in the frozen anchor snapshot.";
+  return formatLocatedAtom(result.atoms[0]!, params.detail ?? "brief");
+}
+
+function handleLocateSearch(params: LocateSearchRequestType, atoms: Atom[]): string {
+  if (!params.pattern && !params.tool_name && !params.source) {
+    throw new Error("locate_search requires at least one filter: pattern, tool_name, or source.");
   }
   const result = locateAtomMatches(atoms, {
-    ref: params.ref,
     pattern: params.pattern,
     source: params.source,
     toolName: params.tool_name,
     direction: params.direction,
     limit: params.limit,
-    detail: params.detail,
   });
   if (!result.atoms.length) return "No matching atoms in the frozen anchor snapshot.";
   const rendered = result.atoms
-    .map((atom) => formatLocatedAtom(atom, params.detail ?? "brief", params.pattern))
+    .map((atom) => formatLocatedAtom(atom, "brief", params.pattern))
     .join("\n\n---\n\n");
   if (result.totalMatches <= result.atoms.length) return rendered;
   return [
-    `Showing ${result.atoms.length} of ${result.totalMatches} matches (${params.direction ?? "oldest"} first). Refine pattern or add source, tool_name, or direction.`,
+    `Showing ${result.atoms.length} of ${result.totalMatches} matches (${params.direction ?? "oldest"} first). Refine pattern or add source or tool_name.`,
     rendered,
   ].join("\n\n");
 }
 
-type PlanHandleResult =
-  | { op: "show"; draft: DraftPlan }
-  | { op: "add" | "update" | "remove"; draft: DraftPlan; changedId: string };
-
-function handlePlan(params: PlanRequestType, current: DraftPlan, atoms: Atom[]): PlanHandleResult {
-  const op = params.op ?? "show";
-  if (op === "show") return { op, draft: current };
-  if (op === "remove") {
-    if (!params.draft_id) throw new Error("plan remove requires draft_id.");
-    return { op, draft: removeDraftRange(current, params.draft_id), changedId: params.draft_id };
+type PlanMutationOp = "add" | "update" | "remove";
+
+function handlePlanMutation(
+  current: DraftPlan,
+  atoms: Atom[],
+  request: PlanAddRequestType | PlanUpdateRequestType | PlanRemoveRequestType,
+): { op: PlanMutationOp; draft: DraftPlan; changedId: string } {
+  if (request.action === "plan_add") {
+    const draft = addDraftRange(current, atoms, { start: request.start, end: request.end, summary: request.summary, topic: request.topic });
+    const previousIds = new Set(current.ranges.map((range) => range.id));
+    const changedId = draft.ranges.find((range) => !previousIds.has(range.id))!.id;
+    return { op: "add", draft, changedId };
   }
-  if (op === "update") {
-    if (!params.draft_id) throw new Error("plan update requires draft_id.");
-    if (params.summary === undefined && params.topic === undefined) throw new Error("plan update requires summary or topic.");
+  if (request.action === "plan_update") {
+    if (request.summary === undefined && request.topic === undefined) {
+      throw new Error("plan_update requires summary and/or topic; boundaries change via plan_remove + plan_add.");
+    }
     return {
-      op,
-      draft: updateDraftRange(current, params.draft_id, { summary: params.summary, topic: params.topic }),
-      changedId: params.draft_id,
+      op: "update",
+      draft: updateDraftRange(current, request.range_id, { summary: request.summary, topic: request.topic }),
+      changedId: request.range_id,
     };
   }
-  if (!params.start || !params.end) throw new Error("plan add requires start and end.");
-  const next = addDraftRange(current, atoms, { start: params.start, end: params.end, summary: params.summary, topic: params.topic });
-  const previousIds = new Set(current.ranges.map((range) => range.id));
-  const changedId = next.ranges.find((range) => !previousIds.has(range.id))!.id;
-  return { op, draft: next, changedId };
+  return { op: "remove", draft: removeDraftRange(current, request.range_id), changedId: request.range_id };
 }
 
 function validateDraftForCommit(draft: DraftPlan, atoms: Atom[]): void {

package/src/inventory.ts

@@ -217,7 +217,7 @@ export function formatInventory(page: InventoryPage): string {
 
 /** Measure explicit, possibly overlapping candidate spans without mutating the DraftPlan. */
 export function formatSpanInspection(atoms: readonly Atom[], spans: readonly InspectSpan[]): string {
-  if (spans.length === 0) throw new Error("inspect spans requires at least one start/end span.");
+  if (spans.length === 0) throw new Error("measure requires at least one start/end candidate.");
   const byRef = new Map(atoms.map((atom) => [atom.ref, atom]));
   const anchorChars = aggregateMetrics(atoms.map((atom) => atom.metrics)).contentChars;
   const lines = [
@@ -228,7 +228,7 @@ export function formatSpanInspection(atoms: readonly Atom[], spans: readonly Ins
   for (const span of spans) {
     const start = byRef.get(span.start);
     const end = byRef.get(span.end);
-    if (!start || !end) throw new Error(`Unknown span ref ${!start ? span.start : span.end}; re-run inspect against the current snapshot.`);
+    if (!start || !end) throw new Error(`Unknown span ref ${!start ? span.start : span.end}; re-run measure against the current snapshot.`);
     if (start.index > end.index) throw new Error(`Span ${span.start} → ${span.end} is reversed.`);
 
     const selected = atoms.slice(start.index, end.index + 1);

package/src/plan.ts

@@ -22,14 +22,14 @@ export function addDraftRange(
 ): DraftPlan {
   const start = atoms.find((atom) => atom.ref === input.start);
   const end = atoms.find((atom) => atom.ref === input.end);
-  if (!start || !end) throw new Error("Unknown atom ref; run locate/inspect again against the current anchor snapshot.");
+  if (!start || !end) throw new Error("Unknown atom ref; run inspect or locate again against the current anchor snapshot.");
   if (start.index > end.index) throw new Error("start must not occur after end.");
   const selected = atoms.slice(start.index, end.index + 1);
   if (selected.length === 0) throw new Error("Empty range.");
   const unsafe = selected.find((atom) => isProtectedAtom(atom));
   if (unsafe) throw new Error(`Range crosses protected atom ${unsafe.ref} (${unsafe.kind}). Split the plan around it.`);
   const overlaps = draft.ranges.some((range) => !(end.index < range.startIndex || start.index > range.endIndex));
-  if (overlaps) throw new Error("Range overlaps an existing draft range.");
+  if (overlaps) throw new Error("Range overlaps an existing plan range; remove or replace it first.");
 
   const metrics = rangeMetricsForAtoms(selected);
   const summary = input.summary ?? "";
@@ -76,7 +76,7 @@ export function updateDraftRange(
   patch: { summary?: string; topic?: string },
 ): DraftPlan {
   const target = draft.ranges.find((range) => range.id === draftId);
-  if (!target) throw new Error(`Unknown draft range ${draftId}.`);
+  if (!target) throw new Error(`Unknown plan range ${draftId}.`);
   const summary = patch.summary ?? target.summary;
   const topic = patch.topic ?? target.topic;
   const replacement = replacementContentChars(summary, topic);
@@ -90,7 +90,7 @@ export function updateDraftRange(
 }
 
 export function removeDraftRange(draft: DraftPlan, draftId: string): DraftPlan {
-  if (!draft.ranges.some((range) => range.id === draftId)) throw new Error(`Unknown draft range ${draftId}.`);
+  if (!draft.ranges.some((range) => range.id === draftId)) throw new Error(`Unknown plan range ${draftId}.`);
   return { ...draft, revision: draft.revision + 1, ranges: draft.ranges.filter((range) => range.id !== draftId) };
 }
 
@@ -153,18 +153,18 @@ export interface DraftFormatOptions {
 /** Agent-facing plan output with bounded semantic landmarks and summaries. */
 export function formatDraft(draft: DraftPlan, telemetry?: DraftTelemetry, options: DraftFormatOptions = {}): string {
   if (options.detail === "full" && !options.draftId) {
-    throw new Error("plan show detail=full requires draft_id.");
+    throw new Error("Full plan output requires a known range id.");
   }
   const selected = options.draftId
     ? draft.ranges.filter((range) => range.id === options.draftId)
     : draft.ranges;
   const atomsByRef = options.atoms ? new Map(options.atoms.map((atom) => [atom.ref, atom])) : undefined;
-  if (options.draftId && selected.length === 0) throw new Error(`Unknown draft range ${options.draftId}.`);
+  if (options.draftId && selected.length === 0) throw new Error(`Unknown plan range ${options.draftId}.`);
 
   const lines: string[] = [];
   if (telemetry) lines.push(formatTelemetry(telemetry));
   if (draft.ranges.length === 0) {
-    lines.push(`Draft v${draft.revision}: no compression ranges.`);
+    lines.push(`Plan v${draft.revision}: no compression ranges.`);
     return lines.join("\n\n");
   }
   lines.push(draftHeader(draft));
@@ -180,7 +180,7 @@ export function formatDraft(draft: DraftPlan, telemetry?: DraftTelemetry, option
     const block = formatRangeBrief(range, atomsByRef);
     const currentLength = lines.join("\n\n").length;
     if (currentLength + 2 + block.length > DRAFT_OUTPUT_LIMIT) {
-      const notice = `Output budget reached: showed ${shown} of ${selected.length} range(s). Use draft_id to inspect one range.`;
+      const notice = `Output budget reached: showed ${shown} of ${selected.length} range(s). Use plan_read to inspect one range.`;
       if (currentLength + 2 + notice.length <= DRAFT_OUTPUT_LIMIT) lines.push(notice);
       break;
     }
@@ -199,7 +199,7 @@ export function formatPlanMutation(
 ): string {
   const pendingCount = draft.ranges.filter((range) => range.summary.trim().length === 0).length;
   const verb = op === "add" ? "added" : op === "update" ? "updated" : "removed";
-  const lines = [`Draft v${draft.revision}: ${verb} ${changedId} · ${draft.ranges.length} range(s) · ${pendingCount} pending summary.`];
+  const lines = [`Plan v${draft.revision}: ${verb} ${changedId} · ${draft.ranges.length} range(s) · ${pendingCount} pending summary.`];
   if (op !== "remove") {
     const changed = draft.ranges.find((range) => range.id === changedId);
     const atomsByRef = atoms ? new Map(atoms.map((atom) => [atom.ref, atom])) : undefined;
@@ -211,7 +211,7 @@ export function formatPlanMutation(
 function draftHeader(draft: DraftPlan): string {
   const pendingCount = draft.ranges.filter((range) => range.summary.trim().length === 0).length;
   const reviewState = pendingCount === 0 ? "ready for review" : `${pendingCount} pending summary`;
-  return `Draft v${draft.revision}: ${draft.ranges.length} range(s) (${reviewState}).`;
+  return `Plan v${draft.revision}: ${draft.ranges.length} range(s) (${reviewState}).`;
 }
 
 function formatRangeBrief(range: DraftRange, atomsByRef?: ReadonlyMap<string, Atom>): string {

package/src/review-ui.ts

@@ -46,7 +46,7 @@ export async function showReviewUi(
 
           const header: string[] = [
             h("╭"),
-            framed(accent(theme.bold(`Midcompact Review · Draft v${draft.revision} · ${draft.ranges.length} range(s)`))),
+            framed(accent(theme.bold(`Midcompact Review · Plan v${draft.revision} · ${draft.ranges.length} range(s)`))),
             framed(usageLine(telemetry, theme)),
             h("├"),
           ];
@@ -195,7 +195,7 @@ export async function showReviewUi(
 
 export function buildReviewText(atoms: Atom[], draft: DraftPlan, telemetry: DraftTelemetry): string {
   const lines = [
-    `Midcompact Review · Draft v${draft.revision}`,
+    `Midcompact Review · Plan v${draft.revision}`,
     plainUsageLine(telemetry),
     "This is awareness, not a target.",
     "",

package/src/selection-ui.ts

@@ -159,7 +159,7 @@ export async function showSelectionUi(
 
           const header = [
             rule(w, "+", "+"),
-            frame(accent(theme.bold(`Midcompact Selection | Draft v${draft.revision}`)), w),
+            frame(accent(theme.bold(`Midcompact Selection | Plan v${draft.revision}`)), w),
             frame(dim(`Anchor Pi usage: ${usageLine(telemetry)}`), w),
             frame(dim(`Selected ${selectedAtoms.length}/${atoms.length} atoms | ${chars}/${totalChars} chars (${charShare} of anchor) | up to ${charShare} fewer anchor chars | ${images} images`), w),
             rule(w, "+", "+"),

package/src/start-ui.ts

@@ -16,8 +16,8 @@ interface StartChoiceOption {
  * Agent-first start path, and RPC clients see the recommended entry first.
  */
 const START_CHOICES: StartChoiceOption[] = [
-  { value: "agent", label: "Agent direct — Inspect and draft with Agent" },
-  { value: "user", label: "User manual — Select the initial DraftPlan yourself" },
+  { value: "agent", label: "Agent direct — Inspect and plan with Agent" },
+  { value: "user", label: "User manual — Select the initial plan yourself" },
   { value: "cancelled", label: "Drop — Leave the session unchanged" },
 ];
 

package/src/telemetry.ts

@@ -100,7 +100,7 @@ export function formatTelemetry(telemetry: DraftTelemetry): string {
     lines.push("anchor: Pi context usage unavailable [Pi reported; not derived from local char counts].");
   }
   lines.push(
-    `draft: ${telemetry.rangeCount} range(s) · ${telemetry.selectedOriginalContentChars} → ${telemetry.selectedReplacementContentChars} content chars · ${telemetry.selectedImageCount} images (${telemetry.selectedImagePayloadBytes} payload bytes) · ${telemetry.pendingSummaryCount} pending summary`,
+    `plan: ${telemetry.rangeCount} range(s) · ${telemetry.selectedOriginalContentChars} → ${telemetry.selectedReplacementContentChars} content chars · ${telemetry.selectedImageCount} images (${telemetry.selectedImagePayloadBytes} payload bytes) · ${telemetry.pendingSummaryCount} pending summary`,
   );
   return lines.join("\n");
 }