@tduyng/pi-prewalk 0.0.3 → 0.0.4

package/README.md

@@ -1,59 +1,40 @@
 # @tduyng/pi-prewalk
 
-Plan on the frontier model, execute on the cheap one, in one unbroken context. The first edit swaps the model, and the planner comes back only when the executor hits a wall.
+Plan on the frontier model, execute on the cheap one, in one unbroken context. The first edit swaps the model, and the planner returns only when the executor hits a wall.
 
-## What it costs
+Most turns in a task are execution: applying a change the plan already describes, running the check, reading the error. Paying frontier prices for those is the largest avoidable cost in a long session.
 
-`prewalk_plan` is deferred at 716 tokens in the sessions that load it, and nothing before that. The router is one hook on `streamSimple` and registers no extra schema, so an armed session pays the router and the plan tool, and an unarmed one pays nothing.
+Writing the plan down and handing it to a fresh session does not fix it. Stencil measured 1.81B tokens over about 2M tool calls and found edits are roughly 9 percent of them. Reads are the rest, so an executor reopens the files the planner already read, and the plan document saves the thinking while paying twice for the exploration.
 
-The saving is the tier. On SWE-bench this reached 92 to 97 percent of the frontier pass rate for 53 to 61 percent of its cost. Planning is the expensive step, and it is bought once per task rather than once per turn.
+`prewalk_plan` is 716 tokens and only while prewalk is armed in plan mode. The router is one hook on `streamSimple` and registers no schema, so an unarmed session pays nothing.
 
-## Why not a plan document
+## One context, two models
 
-Stencil measured 1.81B tokens over about 2M tool calls and found edits are roughly 9 percent of them. Reads are the rest, so a plan document does not help: whoever executes it opens the same files again.
+A prompt cache belongs to one model, so a swap costs exactly one cold read of the prefix, at the cheap model's input rate, once per task. Both models then read the transcript and keep their own cache warm across their own turns.
 
-prewalk keeps one context instead. The planner explores and makes the first edit, and the cheap model carries on from the same history with the plan in hand.
+Prompts are never rewritten and no message is edited afterwards. Rewriting one message invalidates the prefix for both.
 
-## The router
-
-prewalk registers one virtual model, `prewalk/auto`, selected with `/prewalk` or from `/model`. Pi calls the router before every request, so prewalk never moves the session's model itself and no `setModel` runs mid task. Every model change in the session file is one prewalk made.
-
-Each route returns one request's model, so planner and executor can differ inside a single task.
+On SWE-bench this reached 92 to 97 percent of the frontier pass rate for 53 to 61 percent of its cost.
 
-## A task boundary
+## The router
 
-prewalk asks one question, and only when a task is about to start. The boundary is the gap between one settled run and the next prompt typed after it, so a task routes once and the turns inside it are never touched.
+prewalk registers one virtual model, `prewalk/auto`. Pi calls the router before every request, so the session's model is never moved mid-task and every model change in the session file is one prewalk made. Each route returns one request's model, so planner and executor can differ inside a single task.
 
-Pi's own `reason: "user"` cannot carry that boundary, because it fires for a steer and a follow-up too. prewalk keeps its own flag set from the `input` event, which reads `streamingBehavior` as the three cases it is: undefined when the session was idle, `steer` when the text joins the turn in flight, and `followUp` when it waits for that turn to settle and opens a task of its own. The first router call that sees the flag consumes it, so one prompt routes once. A message from another extension opens a task the same way, and the only text that opens nothing is prewalk's own nudge, recognized by its `[prewalk]` prefix.
+A task boundary is the gap between one settled run and the next prompt typed after it. A task routes once and the turns inside it are never routed.
 
-| You type | What happens |
+| Input | What happens |
 | --- | --- |
-| A prompt during the task in flight | The model stays, the prompt runs as written, no routing call. This is the common case, and what keeps the bill linear in turns rather than quadratic |
-| A question while the executor is in play | A steer long enough to be a question moves the task back to the planner, which stays until the next edit hands it over. No routing call, because the phase answers it. A one-word steer is a redirect and stays where it is |
+| A prompt during the task in flight | The model stays, the prompt runs as written, no routing call |
+| A question while the executor is in play | A steer long enough to be a question moves the task back to the planner, which stays until its next edit hands it over |
+| A one-word steer | A redirect, so the task stays where it is |
 | A new task | The session moves to the planner before the first token |
-| A prompt under 8 characters | Not a task: it holds whatever is in play |
-
-## The handoff
-
-The planner explores, then must commit a structured plan through `prewalk_plan` before it can edit. The first edit is blocked once with a message naming the tool, and a planner that ignores the block degrades to a plain edit-only swap.
-
-The first `edit`, `write`, `multiedit`, or `notebookedit` after the plan swaps the session to the executor, and so does a bash command that writes a file outside the temp dir (a redirect, `sed -i`, `tee`, `patch`, `git apply`, or an inline script that writes), which also demands the plan first. A third tool call after the plan still hands over, for a planner that writes in a way the check cannot see. An edit under the temp dir is scratch and swaps nothing.
-
-The plan tool returns the handoff brief itself: the goal, the facts with file:line, each step with file, anchor, change, and verify command, the out-of-scope list, and the rules of engagement. Both roles read the same bytes, so neither cache is rewritten.
-
-## When the executor is stuck
+| A prompt under 8 characters | Not a task, so nothing moves |
 
-Three failed tool results in a row are a wall. One miss does not hand the task back, and any success resets the count. The third failure appends a brief naming the step, and the planner takes the task back on the next request until its next edit.
+Pi's own `reason: "user"` cannot carry that boundary, because it fires for a steer and a follow-up too. prewalk keeps its own flag from the `input` event, which reads `streamingBehavior` as the three cases it is: undefined when the session was idle, `steer` when the text joins the turn in flight, and `followUp` when it waits for that turn to settle and opens a task of its own.
 
-A task buys two upgrades, because each swap re-reads the whole prefix at the new model's input rate, and a task cannot ping-pong between the models.
+## The plan is a tool call
 
-When the executor finishes the plan, or stalls after its nudge, the planner takes the task back once per plan. It reads the edits already in the transcript, runs the final check, and fixes what is wrong. Work the plan did not cover gets a new plan, which is how a long task runs in phases of up to 20 steps. `"review": false` in `prewalk.json` turns that off.
-
-The session badge reads `prewalk replan` while this happens.
-
-## The plan tool
-
-`prewalk_plan` is in the active set while prewalk is armed in plan mode, and the executor meets it only through tool search. Its description carries the planning brief, which is why nothing is prepended to your prompt.
+The planner must call `prewalk_plan` before it can edit, and a guard blocks the first edit once with a message naming the tool. A planner that ignores the block degrades to a plain edit-only swap rather than stalling. The tool's result is the handoff brief, so both roles read the same bytes and neither cache is rewritten.
 
 | Field | Meaning |
 | --- | --- |
@@ -63,34 +44,38 @@ The session badge reads `prewalk replan` while this happens.
 | `check` | Final verification command |
 | `outOfScope` | Files the executor must not touch |
 
-## Progress
+The first `edit`, `write`, `multiedit` or `notebookedit` after the plan swaps to the executor. So does a bash command that writes a file outside the temp dir: a redirect, `sed -i`, `tee`, `patch`, `git apply`, or an inline script that writes, and that path demands the plan first too. A third tool call after the plan still hands over, for a planner that writes in a way the check cannot see. An edit under the temp dir is scratch and swaps nothing.
 
-After each edit the extension matches the edited path against the plan steps and advances a step pointer, walking forward from the current step so batched edits and missed results catch up instead of freezing the count. A short footer is appended to the edit result: what was done, what comes next, the anchor, and the verify command. No model cooperation is needed.
-
-The badge reads `prewalk route` between tasks, `prewalk plan` or `prewalk run` on the first turn of one, `prewalk exec 3/7` while the plan runs, and `prewalk done 7/7` at the end.
+## When the executor is stuck
 
-A planner that commits a plan but ends the turn without an edit still gets the swap, and the executor is nudged to start step 1. An executor that settles with steps open gets one steer to resume. Your input or progress re-arms it, so at most one nudge is spent per stall.
+Three failed tool results in a row are a wall. One miss does not hand the task back, any success resets the count, and the third failure appends a brief naming the step. The planner takes the task back on the next request, until its next edit.
 
-## Cache
+A task buys two upgrades, because each swap re-reads the whole prefix at the new model's input rate and a task cannot ping-pong between the models. When the executor finishes the plan or stalls after its nudge, the planner returns once per plan: it reads the edits already in the transcript, runs the final check, and fixes what is wrong. Work the plan did not cover gets a new plan, so a long task runs in phases of up to 20 steps. `"review": false` in `prewalk.json` turns that off.
 
-A prompt cache belongs to one model, so the swap is the only thing that has to be paid for, and a task pays it at most once: the executor meets a prefix it has never seen, at the cheap model's input rate.
+## The step counter
 
-Prompts are never rewritten. There is no wrapper on your message and no message is edited afterwards, so both models read the transcript you wrote and each keeps its cache warm across its own turns. The one message prewalk writes is the plan tool's result, at the swap.
+After each edit the extension matches the path against the plan steps and advances a pointer, walking forward from the current step so batched edits and missed results catch up instead of freezing the count. The edit result gains a short footer: what was done, what comes next, the anchor, and the verify command.
 
-`prewalk_plan` stays in the active set for as long as prewalk is armed in plan mode, because a toolset change rewrites the system prompt and the tool list, and the claude provider answers that by opening a new session that replays the whole transcript.
+The badge reads `prewalk route` between tasks, `prewalk plan` or `prewalk run` on the first turn of one, `prewalk exec 3/7` while the plan runs, and `prewalk done 7/7` at the end.
 
-## Model chains
+## Chains
 
-Each role is an ordered list, walked until one model resolves against pi's registry and has credentials. Two ordinary things break a single model: a provider with no key, and a frontier model that runs out of its usage window part way through the day. The chain absorbs both without a config edit.
+prewalk walks each role's list until one model resolves against pi's registry and has credentials. That absorbs the two ordinary breaks: a provider with no key, and a frontier model that runs out of its usage window partway through the day.
 
 ```json
 {
   "planner": ["opencode-go/mimo-v2.6-pro", "anthropic/claude-opus-4-6"],
-  "executor": ["opencode-z/space-bunny-free", "z-ai/glm-5.3-flash"]
+  "executor": ["opencode-z/space-bunny-free", "z-ai/glm-5.3-flash"],
+  "mode": "plan",
+  "review": true
 }
 ```
 
-`/prewalk models` prints both chains and marks each entry `router`, `ready`, or `unavailable` against the registry `/model` reads, with the context window and input price, and the mode underneath.
+`~/.pi/agent/prewalk.json` holds the machine-wide settings, and a project's `.pi/prewalk.json` overrides `planner`, `executor` and `mode` field by field. The commands write to the project file when one exists, otherwise to the agent dir.
+
+`/prewalk models` prints both chains, marks each entry `router`, `ready` or `unavailable` against the registry `/model` reads, with the context window and input price, sorted by price. A model named with no argument opens the model dialog, each line carrying `provider/id`, window and input price, sorted by price because the executor is the tier being paid for.
+
+An armed prewalk owns the session model, since every task routes through the router, so it takes the router back on `model_select` and on every session start and branch switch and says which model it took. A switch away used to leave a session where nothing routed, silently. `/prewalk off` is how a physical model is kept.
 
 ## Commands
 
@@ -100,39 +85,16 @@ Each role is an ordered list, walked until one model resolves against pi's regis
 | `/prewalk off` | Disarm |
 | `/prewalk status` | Both chains, the mode, and where the task is |
 | `/prewalk models` | Both chains, what resolves, what it costs, and the mode |
-| `/prewalk mode off` | Nothing happens unless you ask |
+| `/prewalk mode off` | Nothing happens unless asked |
 | `/prewalk mode plan` | Every task plans (the default) |
-| `/prewalk planner <model>...` | Replace the planner chain, or pick one from a list |
-| `/prewalk executor <model>...` | Replace the executor chain, or pick one from a list |
+| `/prewalk planner <model>...` | Replace the planner chain |
+| `/prewalk executor <model>...` | Replace the executor chain |
 | `/prewalk plan [task]` | The next task plans, decided by hand |
 | `/prewalk run [task]` | The next task runs on the cheap model, decided by hand |
-| `/prewalk <executor> [task]` | Set the executor. A task given here starts on the planner |
+| `/prewalk <executor> [task]` | Set the executor |
 | `/prewalk <planner> <executor> [task]` | Set both roles and, with a task, start it |
 
-A role named with no model opens the same dialog pi's own model list is built from, each line carrying `provider/id`, the context window, and the input price per million, sorted by price because the executor is the tier you pay for.
-
-Slash commands and skill blocks are left alone, so skill expansion still works.
-
-An armed prewalk owns the session model, because every task routes through the router. A switch away from it leaves a session where nothing routes for the rest of its life, and one press of the model cycle key used to do that silently: the `12:20` model change in one session left 130 assistant messages on a cheap model with no routing at all. prewalk now takes the router back on `model_select` and on every session start and branch switch, and says which model it took. `/prewalk off` is how a physical model is kept.
-
-Model naming is a bare id (`deepseek-v4-flash`) or provider/id (`google/gemini-3-flash`). Resolution is exact provider/id, then exact bare id, then unique id suffix, and a bare id that several providers carry is an error rather than a guess.
-
-## Configure
-
-`~/.pi/agent/prewalk.json` holds the machine-wide settings. A project's `.pi/prewalk.json` overrides `planner`, `executor`, and `mode` field by field. The commands write to the project file when one exists, otherwise to the agent dir.
-
-```json
-{
-  "planner": ["opencode-go/mimo-v2.6-pro"],
-  "executor": ["opencode-go/mimo-v2.6-flash"],
-  "mode": "plan",
-  "review": true
-}
-```
-
-`mode` decides how a task gets its model. `plan` is the default: every task starts on the frontier model and the executor carries the steps it was given. `off` plans nothing unless you ask, so every task runs on the executor. A file written before the score was removed, with `mode: "auto"`, reads as `plan`.
-
-The router must be selected for any of this to run. A string is still accepted for either role, so a file written before the chains existed reads the same. A missing, unparseable, or wrongly shaped file costs its settings and not the session.
+Model naming is a bare id (`deepseek-v4-flash`) or `provider/id`. Resolution is exact `provider/id`, then exact bare id, then unique id suffix, and a bare id that several providers carry is an error rather than a guess. Slash commands and skill blocks are left alone, so skill expansion still works.
 
 ## Install
 
@@ -141,3 +103,12 @@ pi install npm:@tduyng/pi-prewalk
 ```
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-prewalk`
+
+Then select the router and write the chains above. Nothing routes until `prewalk/auto` is the session model.
+
+## Limits
+
+- Plan steps cap at 20, and a fourth phase needs a new plan.
+- A prompt under 8 characters never opens a task.
+- `"mode": "auto"` in an older file reads as `plan`.
+- A missing, unparseable or wrongly shaped `prewalk.json` costs its settings, not the session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tduyng/pi-prewalk",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Plan on the frontier model, execute on the cheap one. The session model swaps the moment the first edit lands.",
   "keywords": [
     "pi",