@felan-ai/ext-prewalk

Same-session Prewalk for Felan's complex repository work: approved entry establishes a capable same-provider high-effort planner, which explores and plans the work in the session task graph, optionally submits that plan for user review, then makes one focused mutation after approval. Felan switches the next model request to the low model tier at exact medium thinking by default, which finishes and verifies the task with the full conversation and tool history intact. Tier resolution stays on the planner's provider and prefers that provider's matching model family. If the planner provider has no model in the target tier, Prewalk keeps the planner model and only applies the configured implementation thinking level. An explicit provider/model-id target may still cross providers.

After the run settles, Prewalk restores the original pre-entry model and thinking level by default. All of these automated changes are scoped to the active session and do not change the user's or project's default model or thinking preference.

When a savings reporter is available, Prewalk reports each implementation turn as a model-routing saving. The observed target-model usage is the actual outcome; the estimated planner-model baseline uses two thirds of each observed input, output, and cache token class (rounded to whole tokens). The host prices both outcomes and records the dollar difference as estimated savings. Planning turns, same-model handoffs, and failed or aborted turns are not reported. Savings reporting is optional and never interrupts the Prewalk lifecycle.

For complex repository work that benefits from substantial exploration, coordinated multi-file changes, dependency-aware planning, or broad verification, the model can request Prewalk by calling enter_prewalk for a new file-changing task. Conversation or repository activity from earlier requests does not prevent entry. The model should prefer to enter before exploring the current task; if its complexity becomes clear after read-only exploration, it can still enter before the task's first mutation. Model-requested entry asks for user approval by default. Small localized edits and routine one-file fixes should normally stay on the regular path. /prewalk remains available when the user wants to enter explicitly and does not ask for redundant approval. Read-only requests do not use Prewalk.

Requirements

• An authenticated, scoped high/xhigh planner model on the current provider supporting high effort or above. A same-provider model in the configured target tier is used when available; otherwise Prewalk keeps the planner model and applies the configured implementation effort. An explicit target requires that exact authenticated model
• At least one explicit mutation tool: Pi's edit or write, or the Codex extension's apply_patch

Prewalk refuses to arm when no explicit mutation tool is active. Shell tools such as bash and Codex exec_command do not qualify because they are also used for exploration and verification. When both TaskCreate and TaskUpdate are active, handoff also waits for successful task creation and an in-progress task claim; if those tools are unavailable, mutation-only handoff remains available. Prewalk does not inspect TaskList, TaskGet, todo, or Beads activity.

Commands

/prewalk <task>  Arm Prewalk and start the task immediately
/prewalk         Arm Prewalk for the next ordinary prompt
/prewalk status  Show the phase, target model, and restoration setting
/prewalk exit    Exit Prewalk
/prewalk off     Alias for exit
/prewalk cancel  Alias for exit

status, exit, off, and cancel are handled locally and do not make a provider request. In TUI mode, an inline task is submitted as a user message. In JSON and print modes, it is submitted as a visible custom message and the command waits for the run to become idle. Exiting during active inference defers original-selection restoration until the run settles; exiting while idle restores immediately. Exit does not trigger an implementation handoff, and it does not abort the current provider request or the underlying task. A manual model selection cancels Prewalk and keeps the model selected by the user.

Model entry tool

enter_prewalk {}  Enter Prewalk for complex repository work

The no-argument tool requests a transition of the current run into planning, so it works while the agent is active. With the default ask policy, the package root requests explicit entry approval through pi.ui, independently of Pi mode. A denial or unavailable interaction returns a tool error that directs the model to continue normally. Hosts can initialize the extension with allow for unattended environments such as a cloud platform, or deny to reject model-requested entry. Use the tool for complex repository work rather than small localized edits or routine one-file fixes. It must be called once and by itself. Conversation or repository activity from earlier requests does not prevent entry. Prefer entry before exploring the current task; if its complexity becomes clear after read-only exploration, call the tool before its first mutation. A mutation in the same model turn as a successful entry call cannot trigger handoff; the planning guidance must reach a later model turn first.

The successful entry call and result are orchestration controls. They remain in the stored session transcript but are removed from model context. The exit_plan_mode call remains in context so the implementation model receives the approved plan argument. Current phase guidance is transient and replaced at the phase boundary, so the target receives the useful exploration, task graph, approved plan, and first valid change with implementation guidance rather than an instruction to keep planning.

Plan review

When plan review is active, the planner calls the following tool after preparing the task graph:

exit_plan_mode { plan: "<complete concise plan>" }

The plan must be non-empty and no longer than 32,000 characters. The package root sends its complete display copy in a generic UI form through pi.ui.request, with Approve plan, Provide feedback, and Cancel Prewalk actions. The form includes an optional multiline feedback field bounded to 16 KiB. Approval returns control to the planner, whose first focused mutation triggers the existing model handoff. Feedback returns to planning so the planner can update the task graph and call exit_plan_mode again with the complete revised plan. Explicit cancellation exits Prewalk without implementation. Dismissed, deferred, or unavailable interactions leave the plan unapproved. Empty feedback also leaves it unapproved. Prewalk does not create a separate plan file or persisted plan record.

Untrusted HTML, links, and control characters are escaped in the display copy; the original plan argument remains in model context. An escaped plan exceeding the 128 KiB Markdown or 256 KiB aggregate form budget is rejected rather than truncated. The optional plan-review hint changes layout only. Tool cancellation and session shutdown abort pending interactions, and shutdown waits for owned requests to settle.

Mutation tools remain available during review, so the non-mutation boundary is guidance enforced rather than a security sandbox.

The default entry never auto-approves because a client lacks interactive input. The named createPrewalkExtension(host?) factory accepts an explicit PrewalkHost. The package exports neither a TUI entrypoint nor a feature-specific UI service; optional native rendering belongs to apps/felan.

A custom PrewalkHost must explicitly set autoApproveWithoutUi: true to request that fallback; without it, the host's review result remains authoritative. The common-UI host never enables it.

Lifecycle

1. Approved entry establishes a capable high-effort planner before planning inference. It builds on findings already in the conversation, inspects what is still missing, and determines the complete implementation scope.
2. When the task tools are available, the planner creates a concise graph of at most nine outcome-oriented tasks with TaskCreate, includes concrete validation in their acceptance criteria, links them with blocked_by dependencies that encode the execution order, and claims the first ready task with TaskUpdate.
3. When plan review is active, the planner passes a concise numbered plan to exit_plan_mode. The tool displays it and either records approval, returns feedback for another planning iteration, or cancels Prewalk.
4. When both task tools are active, successful TaskCreate and TaskUpdate calls claiming in_progress work open the task gate. The planner then performs one focused successful edit, write, or apply_patch.
5. At that turn boundary, Felan resolves a same-provider model in the configured target tier, or an exact target model. If the planner provider has no target-tier model, it keeps the planner model and applies the configured thinking level.
6. The target model completes the existing session task graph and runs the relevant verification. Without a classifier it launches one high-tier reviewer child and ends with a pending-review status; the review completion notice resumes the session. With a classifier, the completion check below decides whether more work or a review is needed. Prewalk does not check whether Agent is active; a host without it must enable the tool to satisfy reviewer requests.
7. Once the work is verified and any required reviewer has returned, Felan restores the original pre-entry model and thinking level after the agent run settles. An unchecked or aborted implementation, or an outstanding review, keeps Prewalk active until the work resumes or the user exits it.

When both task tools are active, successful TaskCreate and TaskUpdate calls claiming in_progress work are required before a successful mutation qualifies the turn for handoff. Failed or unrelated task calls do not open that gate. If the task tools are unavailable, a successful explicit mutation qualifies directly. Failed mutation calls never qualify. If the planner stops after prose or partial tool progress, Prewalk can append a compact hidden continuation that directs the next tool action without repeating the full planning instructions. It sends at most one continuation per no-progress stretch and three per run.

The handoff does not fork, summarize, or replace the session. Planning and implementation guidance are transient context messages. Within a phase, the current guidance stays at one stable context position while assistant responses, tool results, and compact continuations append after it. At the phase boundary, Prewalk replaces that guidance once; after the run, it removes all Prewalk controls. User messages, assistant responses, task-tracking results, mutations, and verification results remain in one trajectory.

This follows the Prewalk design described by Stencil: transfer the grounded exploration, bounded work list, and first valid move rather than handing a detached plan document to a second reader.

The extension also registers concise static prewalk capability guidance during initialization. Phase-specific planning and implementation instructions remain transient, stable-position context messages.

Classifier guidance

When the host runtime provides a classifier, root-session Prewalk contributes entry and conditional planner-profile questions to the shared root pass, with separate later workflow decisions. Each uses bounded state: the request, up to 24 recent conversation items, up to 40 recent tool calls with short inputs and error flags, the submitted plan, and recorded TaskCreate titles and acceptance criteria. Conversation and tool summaries use Agent Core's shared bounded classifier session evidence; Prewalk retains its own task and verification judgments.

• Entry: Classification starts on Pi's input event for idle turns when enter_prewalk and a mutation tool are active and entryApproval is not deny. Agent Core's registered shared root-turn preflight may expire before the answer; in that case no entry guidance is added. If the request should use Prewalk, a hidden conversation message tells the model to call enter_prewalk before exploring. It does not change the system prompt; the message is removed from subsequent model context. The tool stays available and entry approval is unchanged.
• Planner profile: Conditional on entry, choose among authenticated, scoped same-provider high/xhigh model profiles with supported high/xhigh/max effort. Approved entry validates the selection again; absent an answer, it uses a deterministic capable profile. Missing capabilities refuse entry explicitly.
• Exploration depth: When a run starts from enter_prewalk or /prewalk, the classifier judges how much the session already covers. The result appends one sentence to the planning guidance: sufficient (plan from existing findings), targeted (inspect specific missing files), or deep (delegate discovery to explore children and wait for their summaries).
• Implementation advice: For tier targets, the classifier can recommend requirements from the approved plan and tasks. A stronger recommendation is reported, but targetModel/targetThinking remain authoritative. Exact model targets retain their existing path.
• Completion: Implementation guidance asks for a concise summary with the verification results instead of a mandatory review. Once the agent run is ready to settle, the classifier judges its final assistant response and verification evidence, not an intermediate text-only turn. done lets the run settle. gap queues a hidden prewalk-completion-check follow-up that asks the implementer to finish and verify missing work. unsure queues one follow-up requesting a single high-tier reviewer, subject to the user's review restrictions, and stops automatic checks until that review ends. A second gap also requests that review instead of silently accepting unfinished work. At most two checks run before requesting review. A failed completion check also requests review rather than treating an unverified implementation as done. A done decision is accepted only when session activity shows a successful verification after the last successful mutation; the classifier receives bounded tool outcome metadata, not raw command output. Prewalk waits only for actual pending reviewers. A successful reviewer is terminal, but review completion alone is not proof of verification: the next normal final response receives a fresh completion check. If that post-review check is inconclusive or fails, Prewalk exits at settlement with a warning that automatic verification could not confirm completion; this is not a success claim. A cancelled or failed review is not proof of verification and never automatically requests a replacement reviewer; Prewalk remains available for explicit verification or /prewalk off. If the classifier requests more work, the hidden message continues the same run before settlement and is removed from model context after the next assistant turn.

A missing classifier leaves model judgment, capable static planning and the configured implementation target in place. Failed entry/depth decisions add no optional guidance; implementation advice never escalates the configured target. Entry/profile answers are logged in the shared turn-classification record; later decisions use prewalk-classifier, without request text.

Thinking levels

Planning uses a capable high-effort profile; static fallback preserves higher current effort when supported. Temporary selection ownership prevents ordinary dynamic thinking from competing with active planning or implementation. The implementation handoff requests exact medium thinking by default, rather than carrying a planner's potentially expensive max effort to the cheaper target. The request is clamped by Pi to the target model's supported levels, so a non-reasoning model receives off. Configure another target level when the task needs a different quality/cost balance. A same-model target with a different effective level is still a real effort handoff; only matching model and effective effort are a no-op. After the run settles, Prewalk restores the original pre-entry model before its original thinking level. Internal automated changes do not permanently pin dynamic thinking; manual model/effort choices remain authoritative.

Subagents

enter_prewalk is loaded into mutation-capable general and custom child sessions whenever Prewalk is enabled. Each child owns an independent lifecycle and snapshots its own selected model and thinking level. Child handoffs honor the root session's configured model scope. Inspection-only explore and reviewer children do not receive the entry tool because their mutation tools are intentionally disabled.

Configuration

Prewalk declares typed settings. Felan exposes them through extensionConfig.prewalk in settings.json, generated CLI options, /settings, and Agent Core's programmatic configuration API.

--prewalk-target-model <xhigh|high|medium|low|provider/model-id>
--prewalk-target-thinking <off|low|medium|high|xhigh|max>
--prewalk-restore-planner
--no-prewalk-restore-planner
--prewalk-entry-approval <ask|allow|deny>
--prewalk-plan-review <inherit|ask|skip>

targetModel defaults to low, targetThinking defaults to exact medium, restorePlanner defaults to true, entryApproval defaults to ask, and planReview defaults to inherit. inherit resolves to ask when entryApproval is ask, and to skip otherwise. An explicit ask reviews every Prewalk run, including /prewalk; skip preserves the automatic planning and focused-mutation flow. An explicit xhigh target is available for unusually complex work, but does not change the low default. The local CLI equivalent is felan --prewalk-entry-approval allow. This policy applies only to model-called enter_prewalk; /prewalk is already explicit user intent.

Failure behavior

• A target tier with no same-provider candidate keeps the planner model and applies the configured implementation thinking level.
• A missing exact target model or authentication clears the handoff and keeps the existing trajectory.
• A target that already matches the active planner model and effective target thinking clears Prewalk without performing a handoff.
• A same-model target with a different effective thinking level changes effort without changing models and then enters implementation.
• An exact target outside a nonempty session model scope is rejected before switching.
• A failed target-model switch clears Prewalk and reports the failure once.
• A failed planner restoration clears Prewalk, reports the failure once, and keeps the current model.
• A manual model change cancels Prewalk without restoring over the user's selection.
• Repeated entry calls do not replace the active run or its planner snapshot.
• exit_plan_mode calls outside active unapproved planning, with an empty plan, or before the required task gate is ready are rejected without changing the run.
• A successful mutation before required plan approval does not trigger handoff; Prewalk relies on planner guidance rather than disabling mutation tools.
• Exit requests during active target inference restore only after the run settles.
• Session quit, reload, replacement, or fork while the target is active attempts planner restoration as a graceful shutdown backstop.
• Reaching the automatic continuation limit lets the agent run settle. Required review remains in planning so a later exit_plan_mode call can recover; other incomplete planning clears normally.

Attribution

This package adapts the MIT-licensed packages/pi-prewalk implementation from mslavov/pi-extensions at commit 7e72e509fe45a5a87c4c2e176cb711de994a8c1d. See NOTICE and LICENSE.

Composition and package boundary

import { configureExtension } from '@felan-ai/agent-core';
import prewalkExtension, { PREWALK_CONFIG } from '@felan-ai/ext-prewalk';

const extension = prewalkExtension;
const cloudConfig = configureExtension(PREWALK_CONFIG, {
  entryApproval: 'allow',
  planReview: 'skip',
}, 'cloud runtime');

Pass cloudConfig through Agent Core's extensionConfigOverrides when composing the cloud session.

The extension owns the same-session state machine, explicit mutation qualification, stable-position transient planning/implementation guidance, target selection, and restoration lifecycle. Agent Core supplies model tiers and the host supplies authenticated model scope, session lifecycle, and active tools. Prewalk does not inspect or execute the task graph beyond the successful TaskCreate/TaskUpdate handoff gate described above. Entry approval controls only whether a model may start Prewalk. Plan review is a tool-driven approval checkpoint, not a sandbox or a tool-level mutation restriction.

The package requires compatible Agent Core and Tasks peers plus an explicit edit, write, or Codex apply_patch tool in the composed session.

Development

Source: packages/ext-prewalk in https://github.com/felan-ai/felan.

corepack enable
pnpm install --frozen-lockfile
pnpm --filter @felan-ai/ext-prewalk build
pnpm --filter @felan-ai/ext-prewalk type-check
pnpm --filter @felan-ai/ext-prewalk test

Related documentation

• Agents, tasks, and Prewalk
• Architecture
• Extension catalog