pi-blitz-handoff

For agents: LLM counterpart.

Steer your context. Hand off what matters.

This extension is designed for one purpose: to capture a session’s continuation context more precisely than compaction and make it available to a fresh, natively linked Pi session through a local handoff file referenced by its first prompt. How work continues is determined by the user’s existing instructions, workflow, and templates.

[!NOTE] 2.0.0 — GitHub release

npm publication is handled separately by the maintainer; this GitHub release does not establish npm availability of 2.0.0.

The product specification is the sole product authority. The implemented request → template retrieval → drafting → Finish contract has passed local checks and bounded real Pi 1.5/model validation described below. Package version 2.0.0 marks the breaking protocol and settings changes; it is independent of the supported Pi version. See the release notes.

The “Blitz” in the project name is the author's surname, not a speed claim. Do not expect a handoff to be faster than compaction; its purpose is more precise context transfer, not speed.

Automatic handoff describes only how the transfer is triggered, not how the replacement session must work. Autonomous execution, interactive clarification, answering, research, and waiting are equal continuation modes. The extension transfers their existing instructions and authorization boundaries; it does not choose a workflow or grant new permission.

Why V2 is the default

V2 has worked better in practice than the previous templates. It focuses the dossier on what the replacement session needs to continue, rather than accumulating session history and every past skill read. The template instructs the writer to:

• record the actual continuation mode, userfacing or autonom;
• preserve commissioned work, continuing grants and conditions, dirty state, blockers and evidence limits;
• list active skills by name, purpose and scope rather than accumulate every past read;
• keep the continuation core inline and reference known detail sources only for concrete retrieval needs; and
• apply deferred prompts first, then resume the dialogue or perform authorized autonomous work without a previous-session recap.

The default separates history from the context needed to continue. One short historical paragraph contains only topic/task labels, session IDs and known entry points, with starting lines only when established. It tells the receiver to load that history only for a concrete unresolved need. Everything still relevant follows as positive context, including constraints, active skills, evidence limits and current consequences of completed work. Both parts stay in the same handoff file.

The transfer protocol is deterministic; the dossier and continuation are model-generated. V2 is an improved default, not a guarantee of lossless transfer. Results still depend on the model and available source context.

Successful autonomous handoff

These two screenshots document an earlier continuous autonomous run, before V2 became the default. The fresh linked session receives the handoff with Continue authorized autonomous work and begins the recorded next action:

The same replacement session then validates the working state and dispatches the next authorized reviewer without another user prompt:

Requirements

• Node.js 22.19.0 or later
• @earendil-works/pi-coding-agent 1.5.0 or later
• Pi's interactive chat surface
• A persisted source session
• Pi's native write tool, and a writable .pi/ directory under the current Pi working directory

--no-session and other in-memory sessions cannot start a handoff because there is no source transcript path or native parent lineage.

Installation

Install the version currently available on npm (2.0.0 publication is handled separately by the maintainer):

pi install npm:pi-blitz-handoff

Try it for one run without installing it globally:

pi -e npm:pi-blitz-handoff

Or install directly from GitHub:

pi install git:github.com/MircoBlitz/pi-blitz-handoff

Pi reads the extension entry point from package.json. Review third-party extensions before installing them: Pi extensions run with the permissions of the Pi process.

Public interface

Commands

Only /sh is registered publicly. The former hyphenated commands and /sh config are no longer accepted.

There is no public retry command, cleanup command, or public transition command.

Overlay dialogs

In Pi's terminal UI, /sh opens a themed overlay above the conversation. Its first action is Start handoff, or Cancel handoff while a handoff is active. The remaining actions open Recovery, Settings, Project templates and Help. Opening the menu does not start a handoff; Pi's cancel key (Escape by default) closes it without action.

All interactive handoff dialogs use the same overlay presentation, including setting inputs, directory confirmations and recovery-file inspection. There is no separate Ready / Wait / Cancel choice. Clear headings, short descriptions and keyboard hints reflecting your Pi keybindings keep the controls discoverable. Recovery inspection is scrollable so the complete stored prompts remain accessible.

Type /sh to see all subcommands with short descriptions; keep typing to narrow the list. Direct commands remain available when you already know what you need.

Overlays are terminal-only. RPC clients retain Pi's native selection, input and confirmation dialogs; they do not receive a simulated overlay. Dialog answers do not enter model context. Overlays preserve the lifecycle and immediate settings-persistence contracts.

Model-callable tool

The blitz_handoff tool has two actions:

• status — report context usage, warning and automatic thresholds, the one-time readiness reminder delay, and current handoff status.
• start — request a handoff only when the user explicitly requested one.

Discussion, questions, criticism, testing, or a mention of handoffs are not start requests.

How a handoff works

1. Request a transfer. Use /sh start or the menu, explicitly ask the model to call blitz_handoff start, or enable automatic initiation. These are the three initiation routes. Explicit starts ignore thresholds. Manual/model instructions normally wait for native idle with no pending messages; automatic instructions steer at a completed turn boundary. If the model retrieves the template earlier, the successful GET response includes the still-pending Call instruction once and starts its one-shot reminder, without an extra model round.
2. Retrieve the template before writing. The compact Call Template defines the next safe checkpoint, not whole-task completion. Finish only tightly coupled in-flight work needed for safe transfer; independent terminals/background jobs can continue and must not delay it. Start no extra task work to postpone transfer. The initial instruction includes neither a transport path nor a Finish ID. The model must call session_handoff_get_template({}) before writing or inventing a handoff path.
3. Draft with existing tools. Retrieval returns the selected Handoff Template, exact reserved file path, source transcript locator and fresh Finish correlation ID. This is not the native session ID. Early retrieval/drafting is allowed. Repeated retrieval within the active request shares the template snapshot, path and ID; no second writer prompt is needed. Native write must already be available. The extension leaves source tools unchanged; it introduces neither isolation nor a persistent tool snapshot.
4. Capture input at the configured boundary. deferPromptsFrom selects accepted request or successful template retrieval, including early retrieval; the default is retrieval. The active request keeps its selected mode. Failed/aborted retrieval does not start Writing deferral or authorize Finish. Captured interactive/RPC prompts remain unchanged, ordered and separate, in memory and one atomic recovery Markdown file. Extension inputs pass through; slash commands retain native dispatch.
5. Finish at the safe checkpoint. Refresh consequential facts, results, permissions and the exact next action. With the complete file ready, call session_handoff_finish({ id }) once using the returned ID only, never content or path. Missing-template, stale and duplicate Finish calls fail. GET and Finish are native sequential tools. There is no separate GO, user-choice round, automatic writer retry or redundant template delivery. The model owns semantic completeness and safe-checkpoint judgment; a native batch termination hint does not establish that unrelated work settled.
6. Start the native replacement. Only valid Finish plus idle/no-pending settlement permits the private correlated command bridge to ctx.newSession(). No additional assembly model call runs. The extension checks a nonempty regular file without reading the dossier and synchronously appends the latest deferred snapshot before cutover. The short first prompt supplies the absolute path, startup and cleanup instructions. Native parentSession normally preserves lineage; the chain limit starts an independent master with the same file reference.
7. Ingest and complete. The receiver follows normal startup/basic skills and reads the entire file, continuing past truncation. Only complete successful ingestion permits the configured exact deletion or unchanged retention; failed/incomplete reading leaves it unchanged and reports the blocker. Finished and associated recovery-file deletion require native completed from the concrete recipient turn actually receiving the bootstrap input, not necessarily the first recipient turn. Error, abort, rejection or unobserved delivery retains recovery. Completion proves neither ingestion nor receiver cleanup and does not await later work. No extra stop-reason/tool-error veto, queue or retry is added; late sender settlement cannot overwrite an observed recipient outcome.

Input deferral and one-shot reminder

Defer prompts from offers Request and Writing (template retrieved), defaulting to Writing. Successful retrieval is the observable writing boundary, not the first filesystem write. Changes apply to the next request, not the active one. An aborted retrieval may leave a reservation for the next retrieval to reuse, but is not successful retrieval. Cancelled or superseded asynchronous retrieval cannot reserve a late file or return a live ID.

When no prompt is captured, no recovery file is needed. Otherwise one file covers the whole window, using <filesystem-safe UTC timestamp>-<normalized source session ID>.md with millisecond precision and letters/digits/hyphens in the session component. Prompt strings are not parsed, classified, summarized or rewritten; --- Deferred Prompt N of M --- boundaries preserve separation. The latest snapshot remains visible until replacement begins, without a second delivery protocol.

One visible reminder after readinessRetrySeconds prompts completion of the current template/Finish flow. It does not regenerate IDs, files or templates, schedule polling, or add retry model turns. Ordinary user prose is not parsed into lifecycle decisions.

90% emergency limit

An already requested handoff receives one urgent steering instruction at the first completed turn reporting at least 90% context use. This fixed emergency limit is separate from configured warning and automatic thresholds.

The instruction stops source-task work and further context gathering, fetches the template if missing, finalizes the supplied file and submits Finish. Independent terminals/subagents must not delay it. It cancels the normal reminder and preserves the current request, file and ID rather than starting another attempt. Cancelled or already submitted handoffs are not escalated.

With no request, disabled automatic initiation stays disabled. This is model guidance, not forced abort or compliance proof. Large responses/tool results can cross the limit before the next boundary; remaining transfer capacity is not guaranteed.

Automatic initiation

Automatic handoff is off by default. When enabled with a nonzero threshold, the first native completed turn at or above that threshold inserts the request as steering before the next model turn without interrupting completed tool work. Error/aborted turns do not initiate, spend the attempt budget or escalate. Automatic initiation chooses neither continuation mode nor permission.

If the first automatic attempt fails or is cancelled, one final attempt becomes eligible at the critical-warning threshold. A second unsuccessful attempt is not repeated. Native session metadata preserves this budget across /reload. Successful manual, threshold or overflow compaction resets it; failed or aborted compaction does not.

The dossier’s first line is a model-written, task-specific Markdown title, inside the file rather than the replacement's initial prompt. Finish validates its correlation. Before cutover, the extension checks file metadata, not Markdown structure, title meaning, NUL absence or semantic completeness.

At most one handoff is active. A second start is rejected without replacing the active state. Once native cutover has been invoked, cancellation is no longer available.

Status and cancellation

The activity line is rendered as a Pi widget directly above the input editor. It does not depend on the configured footer or powerline. The persistent status uses these factual states:

• Waiting for Session Handoff in yellow;
• Writing Session Handoff with an indeterminate activity indicator;
• Session Handoff Finished.

Failure and cancellation override those states. Finished remains until the replacement's next agent run, ordinary input or another handoff. Its second line reports Wait Time from request to successful template retrieval and Handoff Time from retrieval to successful recipient-turn completion. Whenever configured capture is active, show Inputs deferred (0) and increment per prompt, including Request mode while still waiting. The widget advertises /sh cancel, uses the current native theme and remains width-safe; rendering/theme changes do not advance recorded durations. There is no Awaiting User GO state or numbered/fractional progress.

Canonical /sh cancel and menu cancellation invalidate the request, Finish ID, reminder and in-flight retrieval immediately. Before newSession() invocation, even after Finish, they delete only this runtime's exact owned reservation, independently of receiver deletion settings. Foreign collisions remain untouched; a missing owned file is harmless and other errors name the path.

Source tools stay unchanged and cancellation does not abort unrelated source work. Reservation ownership remains until native writes settle, then exact cleanup runs. Command cancellation may await native waitForIdle(); tool/event paths return first and finish at settlement, never waiting on themselves. Cleanup blocks new starts and stale callbacks. One visible follow-up releases the model from the request after cleanup; errors are reported without claiming clean success. Recovery files remain for explicit action, never automatic replay. Normal response abort/Escape adds no pause or cancellation meaning.

From the configured deferral boundary through terminal completion/cancellation, user replacement, fork and compaction are blocked; accepted Finish is also protected while awaiting transition. Cancellation cleanup additionally guards tree navigation, even before retrieval. Before protection begins, navigation may discard a pending request. Native newSession() invocation commits cutover and cannot be cancelled. Late results/callbacks cannot revive old work. Reload/interruption may end in-memory state and leave partial files; no crash restoration or automatic leftover execution/removal is added.

Recovery

/sh recover lists remaining top-level recovery Markdown files with their dates. For one selected file at a time, the dialog can:

• inspect the complete contents without changing the file;
• execute all stored prompts in the current session as one combined user turn that preserves their order and boundaries;
• discard exactly that file;
• return to the list or cancel.

Recovery is always explicit. It never automatically executes leftover prompts. Execution deletes the file only after the concrete turn receiving that recovery input returns native completed. A void send return is not delivery confirmation. Error, abort, rejected or unobserved delivery retains it; a later successful turn cannot change that failed result. The existing no-queue-option dispatch is unchanged, so a busy target can reject execution without losing the file. Native completed remains the success boundary even if the turn contains a tool error or a length stop; no semantic ingestion check is added. Unreadable files are reported and retained.

Settings

Run /sh settings in an interactive UI. Each confirmed setting change validates the complete resulting configuration, persists atomically, and takes effect immediately without /reload. Invalid input, rejected directory creation, or persistence failure retains the previous value and shows a concrete correction message. A missing configured directory is created only after confirmation of its exact path.

There is no overall draft, Save, or Cancel action. Escape discards an unconfirmed setting input; Escape from the setting list closes the dialog without undoing changes already persisted. Configuration cannot overlap an active handoff or recovery dialog, and a handoff cannot start while configuration is open.

Call and handoff template settings list the available, readable, nonempty templates for their role: call_*.cmpl for Call Templates and handoff_*.cmpl for dossier templates. Enter another filename remains available for manual .cmpl filename entry.

Persisted configuration updates the currently loaded extension directly.

The warning threshold produces one advisory warning. Critical warnings may repeat on settled turns. After an unsuccessful first automatic handoff, criticalWarningPercent is also the threshold for one final automatic attempt. Neither warning threshold nor the automatic threshold gates explicit starts.

Subagents

pi-subagents normally starts foreground child agents with --no-session. The extension therefore rejects a handoff in those children because there is no persisted source session. Persisted children (for example, runs configured with a sessionFile or sessionDir) can load this extension and run their own independent handoff; that replacement affects only the child session and does not replace or transfer the parent session.

Automatic session handoff is disabled by default. When using persisted subagents, leave it disabled unless child-session handoff is deliberate, or configure those child agents not to load this extension. This avoids an unplanned child replacement that the parent orchestration does not automatically follow.

Managed paths and templates

The extension manages:

<getAgentDir()>/pi-blitz-handoff/
├── config.json
├── project-templates.json
├── recovery/
└── templates/
    ├── backups/
    ├── call_default.cmpl
    └── handoff_default.cmpl

Missing managed directories are created during load. The package installs its two default templates into the managed template directory. If same-name managed content differs, the old file is moved into the managed templates/backups/ subdirectory with a timestamped filename before the package template is installed. Catalogue scans are nonrecursive, so backups do not appear in template selection. Other managed templates are retained. Deliberately configured directory symlinks are supported.

Project-local handoff files

Successful template retrieval supplies an exclusively reserved owner-only file under the current Pi working directory:

.pi/handoff_SESSID.md

SESSID is the native source-session ID. The file sits directly under .pi, without a timestamp. An existing same-name file is never overwritten by reservation; a collision fails visibly. A leftover file therefore blocks another handoff from that same source session until explicitly removed. Repeated retrieval within the active handoff reuses its reserved path and template/ID snapshot. An aborted retrieval can reuse its reservation on the next retrieval; it is not permission to Finish.

Delete handoff after reading (deleteHandoffAfterReading) is a boolean setting in /sh settings or config.json, enabled by default. After complete successful ingestion, it tells the receiver to delete the exact file. When disabled, the file stays unchanged at its current path; there is no archive move. The extension does not read the dossier, perform receiver cleanup or verify ingestion. Interrupted or failed handoffs, and cancellation cleanup errors, can leave empty or partial files at the supplied path for manual inspection.

These files contain plaintext conversation context and should remain outside version control and publication. Exclude .pi/handoff_*.md using your project's local Git exclude or ignore policy; the extension does not change that policy automatically. Disabling deletion increases local retention. The file transport avoids placing the entire dossier in the submission tool or initial prompt, but file writing and reading still depend on the model, native tools and their output limits.

Shipped defaults

There are no packaged Fast, Balanced or development variants. Custom managed and addendum templates remain available.

Upgrading to the V2 default

The package synchronizes the managed handoff_default.cmpl to V2, backing up different same-name content first. It does not delete other user-owned templates or change existing selections.

If you previously selected another Handoff Template, choose handoff_default.cmpl in /sh settings to use V2 globally. A project assignment can override that choice: select <Default> for the Handoff role in /sh project-template to use the default explicitly, or <Autodiscover> to inherit the nearest ancestor or global selection. A configured addendum directory can still shadow the managed default with a same-name file.

Clean up unchanged legacy templates manually. If you have not customized them, delete obsolete default.cmpl, call_fast.cmpl, handoff_fast.cmpl, call_balanced.cmpl, handoff_balanced.cmpl, call_next.cmpl and handoff_next.cmpl from your local managed template directory. An unchanged handoff_v2.cmpl can also be deleted: V2 is now shipped as handoff_default.cmpl. First switch any global or project selections that still reference these files to the current defaults. Keep customized templates and both current defaults (call_default.cmpl and handoff_default.cmpl). This is a manual cleanup recommendation, not automatic deletion by the extension; retained legacy .cmpl files can still appear in template selection.

The previous supported saved-config shape is narrowly normalized in memory. Recognized retired prepareWhileWaiting, writerAttempts and writerRetryDelaySeconds values are validated, then removed; missing deferPromptsFrom defaults to writing. Recognized omissions also receive deleteHandoffAfterReading: true, maxSessionChainLength: 25 and callTemplate: call_default.cmpl. Retained values must validate; unknown keys and invalid shapes remain errors. Loading never rewrites personal configuration; an explicit settings save writes only the new supported schema. This does not preserve old GO/runtime behavior. debugging and speedMode remain unsupported. The limit is configurable through /sh settings and applies immediately. Chain length comes from Pi's persisted parent-session headers, so /resume and /reload do not reset it. A new independent master starts at one. If a required ancestor cannot be read, cutover fails visibly rather than guessing a length.

Project template assignments

Run /sh project-template to configure the current Pi working directory. The extension shows separate Call and Handoff selection boxes. <Autodiscover> leaves that role without a local override, <Default> selects its existing role-default filename directly, and the remaining choices are readable, nonempty role-specific templates. The default filename is not duplicated in the catalogue choices.

Each Enter persists that role immediately. If no exact assignment exists, the other role begins as <Autodiscover>. Escape discards only the currently unconfirmed choice, so a role confirmed earlier in the dialog remains saved. There is no separate Save action. Selecting <Autodiscover> for both roles removes the exact assignment: an existing assignment is reported as removed; when none exists, no file is written and the dialog reports that fact.

At each handoff, the extension reads project-templates.json and resolves Call and Handoff independently while walking upward from the current Pi working directory. Each role uses the nearest concrete selection; an unresolved role uses its global setting. <Default> bypasses further project and global selection for that role while using the unchanged template resolver. Assignments below the current directory are never considered.

If the project settings file is unreadable, invalid JSON, or fails validation, the start continues only when both role defaults genuinely resolve. One concise warning states the category, that role defaults are active for this handoff, and that the user may ask Pi to inspect the file. The extension does not repair or rewrite the file automatically.

You can customize the Call and dossier templates to make handoffs shorter and faster or more precise for your particular purpose. The extension still owns and appends the deterministic correlation, tool, and interaction rules.

Template discovery is nonrecursive. An optional addendum directory shadows a managed template with the same filename. Call and dossier templates use separate configuration fields but the same simple resolver. Each resolution attempts:

1. the selected addendum template, when configured and present, otherwise the selected managed template;
2. the role-specific addendum default (call_default.cmpl or handoff_default.cmpl), when configured;
3. the corresponding managed role-specific default.

A candidate must be a readable, nonempty .cmpl file. Both configured roles are checked at startup and whenever /sh settings opens. A failed non-default selection falls back to its role default with a visible warning that names the failure and actual fallback; selecting the role default does not itself warn. If the role default cannot resolve, startup or configuration opening fails visibly. There is no placeholder engine or embedded template fallback. Deterministic code appends the mandatory retrieval/Finish protocol to the editable Call Template; it does not expose the path or Finish ID before retrieval. Custom templates cannot remove those invariants. Each physical fallback candidate is attempted at most once, and every failed candidate is reported; there is no fourth fallback.

Data and security

Handoff dossiers may contain sensitive project and conversation context. Handoff files are plaintext at .pi/handoff_<Session-ID>.md; deferred-prompt recovery files are plaintext in the configured recovery directory and contain prompt text unchanged, plus extension-owned boundaries. project-templates.json stores absolute directory paths and template filenames. New managed directories and files use restrictive creation modes, but the extension is not a sandbox and does not provide secret detection, encryption, inode tracking, or a general filesystem-adversary policy.

See SECURITY.md for the security and data-handling model.

Agent documentation: README, Security, Changelog.

Package development

Clone the repository and install its development dependencies:

npm install

Development dependency ranges remain ^1.2.0, and the lockfile currently resolves Pi 1.2.0. Pi-provided host packages use wildcard peers and are not bundled. Handoff requires Pi 1.5.0 or later; tests against older development copies do not establish compatibility with that runtime.

Functional tests are local maintainer checks. Their files are ignored and are not distributed in the public repository or npm package. Local Pi working documents and private checkpoint history are also excluded from the new public release. The earlier public history is unchanged. The shared layout and logo conventions are documented in the pi-blitz standard.

After cloning, source and package checks are available with:

npm run typecheck
npx tsc --noEmit --noUnusedLocals --noUnusedParameters
git diff --check
npm pack --dry-run

Maintainers with the local functional checks also run npm test before release. The corrected source/local candidate passed 197 tests, typecheck, no-unused checks, whitespace checks, package dry-run and specification checksum verification. Existing adapter and file tests do not establish Pi 1.5 static compatibility: development dependencies still resolve Pi 1.2.0. Required deterministic coverage is defined in the specification.

Real Pi 1.5 runs with the configured model and Handoff as the only loaded extension exercised command/manual and model-initiated starts, early and repeated GET with stable paths/IDs, native writes and Finish, parent-linked replacements, full dossier reads and configured retention (deleteHandoffAfterReading: false). They also exercised cancellation reservation cleanup and same-source restart, Writing-mode capture of two prompts, unchanged ordered append with the later prompt taking precedence, the existing one-shot reminder, and explicit native Recovery inspection, execution and completed-turn deletion. These observations cover those runs, not universal model compliance or extension-verified ingestion.

A separate test called actual Pi 1.5 SDK-bound tools directly with real contexts and no doubles or model run. Invalid and stale Finish IDs were rejected; the active request, reserved path, dossier and session stayed unchanged. This was not agent-loop interception or model-compliance evidence.

A bounded Pi 1.5.2/configured-model smoke loaded the unchanged prepared package and observed GET/repeated GET, native write/Finish, parent-linked replacement, full reading and deletion enabled, ordered Writing-mode prompts with later-prompt precedence, cancellation/restart, the active-session switch guard and explicit Recovery with completed-turn cleanup. This is not a full compatibility matrix. The first isolated startup unexpectedly downloaded an rg helper; that copy was removed and the existing native helper reused. No Pi or dependency version changed.

Real-model cases not run include the >=90% emergency, automatic initiation, Request-mode deferral, chain-limit rollover and broad UI scenarios. These paths retain deterministic coverage; no real-model result is claimed for them. Further host/model/session tests require their own authorization. Historical results and screenshots remain historical, not current-candidate verdicts.

On 2026-09-30, a Real-Pi handoff at the end of an existing 10-session chain, using an isolated test limit of 10, created an independent master with no native parent reference. The replacement continued with its re-entry summary and waited as instructed. The default 25-session boundary is covered by deterministic tests, not that Real-Pi run. See session-chain validation for evidence and scope.