Repository navigation
Product Book Handoff
Part of the Product Book. Observable product behaviour at
pi-schematic@36bd569(main, 2026-10-12).
A long Pi coding-agent conversation can become crowded with old tool results and past decisions. Handoff is pi-schematic’s deliberate restart: it replaces the working transcript with a small continuation frame while keeping selected notebook pages for the same work stream. Unlike automatic compaction near a token limit, it separates the next instruction, reusable knowledge, and immediate context before the cut.
Pi is the coding-agent host; pi-schematic is an extension that adds workflow tools to it. Automatic compaction typically makes a lossy summary of a long conversation, often late in the context window without knowing which task boundary matters. Handoff instead occurs at a deliberate boundary. Old messages do not remain in the successor’s model context, which begins with a fixed continuation frame rather than a recap of the old run.
The notebook is pi-schematic’s short-lived store of named pages for this work stream. It retains guidance and decisions across handoff without pasting page bodies into the next prompt. A handoff clears the active notebook topic—the label framing current work—so the successor can assign a fresh topic. Pages may be discarded as part of the cut; otherwise the notebook survives.
A person can type /handoff <direction> to specify what the successor does next. An empty direction produces a usage error and queues nothing. A valid direction takes precedence over any nextInstruction supplied by the model to the handoff tool: there is no merge. pi-schematic trims the selected instruction at its edges but preserves its internal wording. A new command invalidates queued work from an earlier request before replacing its intent.
The model’s other job is preparation. It curates the notebook and passes context for state pages do not capture—a blocker, unresolved question, failed path, or concrete next step. The tool accepts optional nextInstruction, context, and discardPages parameters; it removes duplicate page names in discardPages before staging. When a human direction is pending, the model is asked to call the tool with only the remaining context. For example, a person directs a switch from investigation to implementation while the agent records an investigation finding in a page and gives the successor the immediate blocker in context.
Neither command nor tool call asks the old context to begin that next instruction. The tool describes itself as preparation; its sequential call starts handoff, terminates the agent turn, and leaves work to the successor. The handoff tool rejects a second call during in-flight compaction. A requested handoff remains a sticky contract, but after five eligible turns without a tool call the watchdog cancels it with a warning. The TUI (interactive terminal) footer uses 🤝 for a request waiting for eligible context, one ready to compact, or a handoff in progress; it clears after completion or cancellation.
Handoff requires a nonempty resolved instruction and measurable context usage. The tool rejects an empty instruction with a reminder to save findings first; missing usage data also blocks the cut. A session below 30,000 tokens is too small. If Pi reports token usage directly, the extension uses that count; otherwise it estimates it from context-window size and percentage. Rejections surface as failed tool calls and queue retry guidance. A compaction failure reports that the handoff can be retried and preserves the pending request.
Page removal is coupled to a successful cut: pages marked for discard are staged and committed only after compaction succeeds. A failed discard commit leaves pages retained and reports a warning. On success, a notebook report shows how many pages were kept and, when applicable, discarded. The cut also starts a new input prefix for billing and caching because the dropped transcript is no longer in the successor’s prefix. The extension does not set provider cache lifetimes or breakpoints.
The compaction summary holds only a fixed continuation frame and an identity marker for this cut. It contains no session-specific instruction or frozen mutable posture. The successor receives one real user message headed ## Next instruction, followed by the carried instruction, then ## Context and trimmed situational context if nonempty. Pi can identify the correct handoff in session history.
In a TUI session, the operational handoff report has already been shown, so it is omitted from that user message. In a headless session, the report follows a ## Handoff report delimiter. Successor and failure-guidance messages use Pi’s follow-up queue, waiting behind an active run. pi-schematic stores the exact instruction and context on the compaction entry, giving recovery a durable copy rather than a summary to reinterpret.
Pi’s send operation offers no delivery acknowledgement. If the successor message silently disappears, pi-schematic checks persisted session history rather than assuming a successful send meant delivery. Recovery checks run at session start, after navigating the session tree with /tree, and when an agent run settles. A lost delivery can heal on a later trigger, including the next user-triggered turn. It resends the bare successor message; even in a headless session it omits the operational report.
Recovery considers only the newest handoff cut. If its stored payload cannot be read, it does not resurrect an older instruction. Any user turn after the cut ends recovery, whether the delivered successor or newer intent. Recovery attributes each successor to the nearest handoff cut in its session-parent chain, so two cuts with identical wording remain distinct. Recovery coalesces repeated triggers for one cut; a settled run can retry a genuinely absent delivery, but recovery does not resend a delivered or queued successor. In-flight cuts and already queued messages block recovery attempts. The frame itself holds no old instruction, so /tree cannot replay one from a rolled-back summary.
Readonly is pi-schematic’s research posture guarding against edits. The readonly guard blocks a direct handoff tool call with an explanation and a suggestion to use spawn for same-topic delegation. spawn runs a focused child agent in a separate context, but children have neither handoff nor spawn tools; the parent retains orchestration. Running /handoff <direction> is the narrow exception that lets the requested cut complete under readonly. An eligible human topic boundary can activate the same bypass; an ineligible one stays advisory.
Readonly is not frozen into the summary. Enforcement remains live, and the branch is read again so the posture can resume after compaction. If readonly is ON, a live nudge announces it on the first post-handoff turn; an OFF-to-OFF cut makes no such announcement. The successor begins with a clean context while the applicable tool guard remains in force.
PB-HANDOFF-01 … PB-HANDOFF-46 — 46 atomic behaviour rows
| ID | Behaviour | Evidence |
|---|---|---|
| PB-HANDOFF-01 | A handoff tool is registered with the label Handoff; calling it deliberately clears the current context, keeps the notebook, and clears the active topic. |
handoff/tool.ts:261-263 |
| PB-HANDOFF-02 | The tool takes an optional nextInstruction string: the instruction the successor must execute, verbatim. |
handoff/tool.ts:285-291 |
| PB-HANDOFF-03 | The tool takes an optional context string: the model-owned situational remainder (current state, blockers, unresolved questions, failed paths, concrete next step) still missing from the notebook. |
handoff/tool.ts:292-298 |
| PB-HANDOFF-04 | The tool takes an optional discardPages array of notebook page names to discard during the handoff (names are de-duplicated before staging). |
handoff/tool.ts:299-306, handoff/tool.ts:323
|
| PB-HANDOFF-05 | The tool runs in sequential execution mode and returns { content: "Handoff started.", terminate: true }; the agent turn terminates after the call. |
handoff/tool.ts:282, handoff/tool.ts:352-356
|
| PB-HANDOFF-06 | A second handoff call while a compaction is already in flight is rejected with "Handoff compaction already in progress; retry after it completes." | handoff/tool.ts:309-311 |
| PB-HANDOFF-07 | The tool advertises itself as preparation only and states the instruction must never be performed in the current context, which is discarded at compaction. |
handoff/tool.ts:276-278, handoff/tool.ts:289
|
| PB-HANDOFF-08 | A /handoff <direction> command is registered; its handler stores direction as the successor's instruction, then asks the model to curate the notebook and supply the remaining context. |
handoff/command.ts:20-23, handoff/command.ts:39-43
|
| PB-HANDOFF-09 |
/handoff with an empty or whitespace-only direction is rejected with the user-visible error "Usage: /handoff " and returns without queuing anything.
|
handoff/command.ts:26-30 |
| PB-HANDOFF-10 | A pending human /handoff <direction> wins over any model-supplied nextInstruction; when one is pending, the tool's nextInstruction parameter is ignored. |
handoff/tool.ts:67-76 |
| PB-HANDOFF-11 | The resolved instruction is whitespace-trimmed before delivery; inner bytes are preserved (no paraphrase). | handoff/tool.ts:70-75 |
| PB-HANDOFF-12 |
/handoff starts a new request generation, invalidating any queued work from an earlier request before replacing its intent. |
handoff/command.ts:33-38, state.ts:50-52
|
| PB-HANDOFF-13 | Where a human direction is pending, the model is told to supply only the remaining context to the tool; the watchdog nudge phrases the call as "call handoff with only the remaining context." |
handoff/command.ts:72-77, watchdog.ts:35-45
|
| PB-HANDOFF-14 | The /handoff prompt tells the model explicitly: "Do NOT start this instruction. This context is discarded at compaction." |
handoff/command.ts:69 |
| PB-HANDOFF-15 | A queued /handoff request is a sticky contract; after 5 eligible turns without the tool being called it is cancelled with a warning ("Required handoff cancelled after 5 turns without completion."). |
watchdog.ts:106-124, watchdog.ts:24
|
| PB-HANDOFF-16 | An empty resolved instruction is rejected; the error names the current context percentage and tells the model to save findings to the notebook first. | handoff/tool.ts:36-42 |
| PB-HANDOFF-17 | Missing context-usage data is rejected with "Context usage unavailable; handoff rejected. Continue working and retry." | handoff/tool.ts:44-48 |
| PB-HANDOFF-18 | A session below the 30,000-token minimum is rejected with a message showing the token count and approximate percentage. |
handoff/tool.ts:49-55, handoff/eligibility.ts:2
|
| PB-HANDOFF-19 | Token usage is taken exactly when usage.tokens is supplied, otherwise estimated from contextWindow × percent / 100; eligibility is tokens >= 30000 (finite, non-negative overflow accepted). |
handoff/eligibility.ts:22-39 |
| PB-HANDOFF-20 | A rejected tool call throws (Pi sees a rejected tool call) and also sends a queued follow-up with the actionable reason and retry guidance. |
handoff/tool.ts:315-320, handoff/tool.ts:130-136
|
| PB-HANDOFF-21 | If compaction itself fails, the failure is reported ("Handoff compaction failed: … The handoff can be retried.") and a queued follow-up preserves the pending-request state for retry. | handoff/tool.ts:108-128 |
| PB-HANDOFF-22 | After a handoff, the LLM context contains only the fixed continuation frame — no pre-handoff message is retained — so the successor starts from a minimal context. |
handoff/format.ts:21-38, handoff/compact.ts:36-38
|
| PB-HANDOFF-23 | The frame carries no session-specific instruction or mutable posture, so a /tree rollback cannot replay a stale instruction or stale posture. |
handoff/format.ts:12-20, handoff/compact.ts:31-34
|
| PB-HANDOFF-24 | Each handoff cut is individually identifiable in session history, so Pi reports the correct cut and recovery can attribute a successor to it. |
handoff/format.ts:40-42, handoff/compact.ts:37
|
| PB-HANDOFF-25 | The successor receives exactly one real user message: ## Next instruction followed by the verbatim instruction, then ## Context followed by the trimmed context when non-empty. |
handoff/format.ts:49-55 |
| PB-HANDOFF-26 | The exact successor payload (nextInstruction, context) is retained on the compaction entry, so a lost delivery can be restored without paraphrasing. |
handoff/format.ts:7-11, handoff/compact.ts:40
|
| PB-HANDOFF-27 | In a TUI session the successor message is sent without the operational report (the TUI already showed it); headless sessions append the report after the delimiter \n\n## Handoff report\n\n. |
handoff/tool.ts:90-105, handoff/format.ts:4
|
| PB-HANDOFF-28 | On success the notebook retention outcome is observable ("Handoff complete. Notebook: N pages kept[, M discarded]."); a discard whose commit failed is reported as retained with a warning. |
handoff/tool.ts:238-246, handoff/tool.ts:230-238
|
| PB-HANDOFF-29 | Post-compaction messages (successor, failure guidance, recovery) are delivered with deliverAs: "followUp", so they queue behind an active run instead of being rejected. |
follow-up.ts:13, handoff/tool.ts:98-105
|
| PB-HANDOFF-30 | Delivery is fire-and-forget: Pi exposes no delivery acknowledgement, so a failed send is detected from the persisted branch, not from an error. |
handoff/recovery.ts:4-13, handoff/tool.ts:197-199
|
| PB-HANDOFF-31 | Recovery is trigger-driven and runs on session_start, session_tree, and agent_settled — a silently lost send heals on the next user-triggered turn. |
index.ts:958-961, index.ts:977-979, index.ts:988-991
|
| PB-HANDOFF-32 | Only the newest handoff cut is considered; an unreadable payload there recovers nothing, so an older superseded instruction is never resurrected. | handoff/recovery.ts:115-121 |
| PB-HANDOFF-33 | Any user turn after the cut ends recovery (the delivered successor or newer user intent); a missing successor is not resent after newer input. | handoff/recovery.ts:128-131 |
| PB-HANDOFF-34 | Delivery is attributed by session lineage: a successor belongs to the nearest handoff cut on its parentId chain, so identical payloads on different cuts can neither mask a loss nor provoke a duplicate resend. |
handoff/recovery.ts:86-103, handoff/recovery.ts:132-135
|
| PB-HANDOFF-35 | Recovery resends only the bare successor message; a recovered headless delivery deliberately drops the operational report. | handoff/recovery.ts:136-141 |
| PB-HANDOFF-36 | Repeated recovery triggers for the same cut are coalesced, so a lost successor is never delivered twice. |
index.ts:540-548, state.ts:55-66
|
| PB-HANDOFF-37 | Recovery retries after a run settles, so a genuinely lost successor is eventually delivered, while a successor already delivered or queued is never re-sent. |
index.ts:988-991, state.ts:268-270
|
| PB-HANDOFF-38 | Recovery never fights an in-flight cut and never resends while messages are already queued. | index.ts:529-534 |
| PB-HANDOFF-39 | Under readonly, the handoff tool call is blocked at call time with a reason explaining that handoff needs the temporary exception and suggesting spawn for same-topic delegation. |
index.ts:593-598, notifications.ts:57-58
|
| PB-HANDOFF-40 | Running /handoff is itself the exception: it activates a narrow temporary bypass for that request even under readonly, so a real handoff can complete. |
handoff/command.ts:45-51, notifications.ts:84-85
|
| PB-HANDOFF-41 | In readonly, an eligible human topic boundary is equivalent to /handoff: it promotes the sticky handoff bypass only when context usage is eligible; an ineligible boundary stays advisory. |
index.ts:849-864, index.ts:862
|
| PB-HANDOFF-42 | The readonly posture is not frozen into the summary: a live nudge re-announces the ON posture on the first post-handoff turn, tool_call enforcement stays live, and readonly state is re-read from the branch so readonly can resume after compaction (OFF-to-OFF stays silent). |
handoff/tool.ts:161-165, index.ts:587-598, index.ts:562-569
|
| PB-HANDOFF-43 | The active notebook topic is cleared on a successful handoff, so the next context assigns a fresh one. |
handoff/tool.ts:161, docs/architecture.md:54
|
| PB-HANDOFF-44 | Spawned children never inherit the handoff tool (or spawn), preventing recursion; orchestration stays with the parent. |
spawn/index.ts:239, spawn/index.ts:7
|
| PB-HANDOFF-45 | Compaction starts a new input prefix (the dropped history is no longer in the successor's prefix for billing/cache); the extension creates cache-aware boundaries but does not configure provider cache TTLs or breakpoints. |
docs/architecture.md:56, README.md:150
|
| PB-HANDOFF-46 | Handoff status is shown in the TUI footer: "🤝 Handoff requested — waiting for eligible context", "🤝 Handoff required — ready to compact", and "🤝 Handoff in progress"; the status clears on completion or cancellation. |
handoff/copy.ts:4-8, handoff/tool.ts:86-88, watchdog.ts:120-123
|