@tduyng/pi-prewalk0.0.4

@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 returns only when the executor hits a wall.

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.

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.

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.

One context, two models

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.

Prompts are never rewritten and no message is edited afterwards. Rewriting one message invalidates the prefix for both.

On SWE-bench this reached 92 to 97 percent of the frontier pass rate for 53 to 61 percent of its cost.

The router

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.

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.

Input	What happens
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, so nothing moves

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.

The plan is a tool call

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
summary	One-line goal
facts	Findings from exploration the executor cannot re-derive, each with file:line
steps	{ file, change, anchor?, verify? } in order, up to 20
check	Final verification command
outOfScope	Files the executor must not touch

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.

When the executor is stuck

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.

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.

The step counter

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.

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.

Chains

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.

{
  "planner": ["opencode-go/mimo-v2.6-pro", "anthropic/claude-opus-4-6"],
  "executor": ["opencode-z/space-bunny-free", "z-ai/glm-5.3-flash"],
  "mode": "plan",
  "review": true
}

~/.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

Command	Effect
/prewalk	Status while armed, arm from prewalk.json when not
/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 asked
/prewalk mode plan	Every task plans (the default)
/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
/prewalk <planner> <executor> [task]	Set both roles and, with a task, start it

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

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.