# Oh My Pi Workbook State\, memory\, tangent subagents\, permissions\, and extension design A complete practical guide to OMP sessions\, memory\, tangent subagents\, tool permissions\, and extensions\, with fictional labs\, intact examples\, and explicit evidence boundaries\. ## Contents ### Start here A complete practical guide to OMP sessions\, memory\, tangent subagents\, tool permissions\, and extensions\, with fictional labs\, intact examples\, and explicit evidence boundaries\. - [Start here]() ### Sessions\, resets\, and reviewable history Choose the intended conversation\, change only the intended session boundary\, and inspect the full representation before considering disclosure\. - [Sessions\, resets\, and reviewable history]() - [Orientation]() - [Start here]() - [The continuity ledger]() - [Return Desk lab setup]() - [Return Desk resume selection]() - [Return Desk continuation]() - [Return Desk missing\-directory decisions]() - [Decision Desk forking]() - [Decision Desk resetting deliberately]() - [Decision Desk refusals and failures]() - [Review Packet choosing a snapshot]() - [Review Packet local HTML export]() - [Review Packet reading the whole packet]() - [Sharing is a separate disclosure decision]() - [Operation decision matrix]() - [Recovery and safe disclosure checklists]() - [Evidence and limitations]() - [Sessions\, resets\, and reviewable history\: next steps]() ### Memory and reusable knowledge Distinguish current context from retained evidence and reusable procedures\, then inspect scope and outcomes instead of trusting memory acknowledgements\. - [Memory and reusable knowledge]() - [Orientation]() - [Start with a read\, not a setting change]() - [Four places knowledge can live]() - [The configuration this workbook teaches]() - [Five fictional lab stories]() - [The automatic lifecycle]() - [The command desk]() - [Privacy and costs]() - [Troubleshooting]() - [Your checkpoint]() - [Browser agent interface]() - [Sources\, method and limitations]() - [Memory and reusable knowledge\: next steps]() ### Tangent work and live control Find the exact tangent\, address its current conversation\, and separate view changes\, turn interruption\, job cancellation\, revival\, and terminal intent\. - [Tangent work and live control]() - [Orientation]() - [A tan is already running]() - [1\. Understand the fork]() - [2\. Start from Main]() - [3\. Find and focus the right tan]() - [4\. Steer and queue work]() - [5\. Leave and switch safely]() - [6\. Observe jobs and read results]() - [7\. Continue a finished tan]() - [8\. Interrupt\, cancel\, or kill]() - [9\. Coordinate several tans]() - [10\. Protect context and recover]() - [11\. Operate through Main]() - [12\. State and control reference]() - [Evidence and method]() - [Tangent work and live control\: next steps]() ### Tool permissions and approvals Explain why a particular tool call is allowed\, prompted\, or denied by following its operation\, tier\, policy identity\, host capabilities\, and actual effect boundary\. - [Tool permissions and approvals]() - [Orientation]() - [Start with the operation]() - [Read\, write\, and exec are tiers]() - [Approval Desk\: modes and policies]() - [Approval Desk\: ordered shell rules]() - [Dispatch Desk\: device and path gates]() - [Boundary Desk\: one call at a time]() - [Boundary Desk\: when the host can ask]() - [Configuration and launch precedence]() - [Subagents and inherited policies]() - [Approval is not a sandbox]() - [Recovery without widening permission]() - [Evidence and limitations]() - [Tool permissions and approvals\: next steps]() ### Extensions inside those boundaries Build explicit human and machine capabilities whose permissions\, state lifetimes\, delivery\, loading\, and verification match the host that actually runs them\. - [Extensions inside those boundaries]() - [Orientation]() - [Choose what to build]() - [Prepare a reversible lab]() - [Seed Desk\: welcome and inventory]() - [Seed Desk\: reservations on the active branch]() - [Review Desk\: edit and decide locally]() - [Review Desk\: a native panel and portable dialogs]() - [Editors\, themes and composer shapes]() - [Package Lab\: one file to an embedded host]() - [Discovery\, installation and reload]() - [Tools\, interception and native delegation]() - [Session navigation and event\-driven behavior]() - [Background work and owner\-addressed delivery]() - [Models\, providers\, credentials and memory]() - [Resources\, event buses\, MCP and Gemini manifests]() - [Permission\-denied file fallbacks]() - [Public feature reference]() - [All 46 extension events]() - [Debugging and verification]() - [Build and distribution checklist]() - [Evidence and method]() - [Extensions inside those boundaries\: next steps]() ### Connections and next steps Connect the boundaries\, resolve shared terminology\, and choose a safe next step\. - [An empty context is not an empty history or memory store]() - [A conversation fork is not a worktree or a cloned runtime]() - [Changing focus\, stopping work\, and cancelling disclosure]() - [Permission belongs to an operation\, a revision\, and a lifetime]() - [A result\, a receipt\, and permission to share are different facts]() - [Match each claim to the layer that was checked]() - [Shared glossary]() - [Next steps]() ## Reading paths ### Return to a known conversation without restoring old files Use this route when a history is missing\, the newest conversation is the wrong one\, or a project directory has moved\; establish identity and scope before adding work\. - [Start here]() - [The continuity ledger]() - [Return Desk lab setup]() - [Return Desk resume selection]() - [Return Desk continuation]() - [Return Desk missing\-directory decisions]() - [Decision Desk refusals and failures]() - [Four places knowledge can live]() - [Troubleshooting]() - [Recovery and safe disclosure checklists]() ### Understand why an old fact returns after a reset Separate retained history\, cached injection\, scoped memory\, and reusable skills\; work through the fictional inspection stories without disclosing real memory\. - [The continuity ledger]() - [Four places knowledge can live]() - [The configuration this workbook teaches]() - [Five fictional lab stories]() - [The automatic lifecycle]() - [The command desk]() - [Decision Desk resetting deliberately]() - [Privacy and costs]() - [Troubleshooting]() - [Sources\, method and limitations]() ### Find\, redirect\, and leave an already\-running tangent Start with the current recipient\, then distinguish steering\, follow\-up\, observation\, revival\, cancellation\, and explicit kill\; do not substitute a Main session reset for a focus change\. - [A tan is already running]() - [1\. Understand the fork]() - [3\. Find and focus the right tan]() - [4\. Steer and queue work]() - [5\. Leave and switch safely]() - [6\. Observe jobs and read results]() - [7\. Continue a finished tan]() - [8\. Interrupt\, cancel\, or kill]() - [10\. Protect context and recover]() - [11\. Operate through Main]() - [12\. State and control reference]() - [Decision Desk resetting deliberately]() ### Give an agent a capability without giving it a blanket grant Follow the smallest\-surface decision through shared human\/tool behavior\, branch\-aware state\, one\-action authority\, portable UI\, and realistic verification\. - [Choose what to build]() - [Prepare a reversible lab]() - [Seed Desk\: welcome and inventory]() - [Decision Desk forking]() - [Seed Desk\: reservations on the active branch]() - [Review Desk\: edit and decide locally]() - [Review Desk\: a native panel and portable dialogs]() - [Tools\, interception and native delegation]() - [Discovery\, installation and reload]() - [Debugging and verification]() - [Build and distribution checklist]() ### Keep delayed results with the conversation that requested them Use this route when a result arrives twice\, disappears from later job snapshots\, or reaches the wrong branch\; distinguish work lifetime\, owner identity\, committed body\, and wake\-up\. - [The continuity ledger]() - [Decision Desk forking]() - [Decision Desk resetting deliberately]() - [6\. Observe jobs and read results]() - [7\. Continue a finished tan]() - [Prepare a reversible lab]() - [Package Lab\: one file to an embedded host]() - [Session navigation and event\-driven behavior]() - [Background work and owner\-addressed delivery]() - [Debugging and verification]() ### Inspect a complete packet without a live share Choose the correct snapshot\, inspect older and nested fictional history\, and separate local acceptance\, external script loading\, redaction\, encryption\, and disclosure authorization\. - [Start here]() - [Review Packet choosing a snapshot]() - [Review Packet local HTML export]() - [Review Packet reading the whole packet]() - [Sharing is a separate disclosure decision]() - [Privacy and costs]() - [10\. Protect context and recover]() - [Review Desk\: edit and decide locally]() - [Recovery and safe disclosure checklists]() - [Evidence and limitations]() ### Explain and repair a blocked or unexpectedly unprompted tool call Identify the exact operation and current scope\, trace the effective policy through modes\, rules\, dispatch\, launch inputs\, and child construction\, then choose a bounded recovery without making yolo the default fix\. - [Start with the operation]() - [Read\, write\, and exec are tiers]() - [Approval Desk\: modes and policies]() - [Approval Desk\: ordered shell rules]() - [Dispatch Desk\: device and path gates]() - [Boundary Desk\: one call at a time]() - [Boundary Desk\: when the host can ask]() - [Configuration and launch precedence]() - [Subagents and inherited policies]() - [Approval is not a sandbox]() - [Recovery without widening permission]() - [Evidence and limitations]() ## Start here OMP work continues through more than a transcript\. A conversation can be reopened while its workspace has changed\. A remembered preference can return after live context was cleared\. A tangent can finish its first job yet remain available for another conversation\. A tool can be enabled but denied for a particular call\, or run without asking under a policy the visible mode alone does not explain\. An extension can keep a selection across a session switch without having saved that selection anywhere\. These are not contradictions\. They are different state and authority boundaries\. This workbook teaches one operating habit\: **name the target\, identify the state and authority involved\, and check the result at the layer where the effect should occur\.** That habit connects returning to yesterday’s work\, retaining useful knowledge\, coordinating another agent\, understanding a tool decision\, building a capability\, and preparing material for review\. ### Read as one book The five parts form a progression\: | Part | Central question | What it prepares you to understand | | --- | --- | --- | | [Sessions\, resets\, and reviewable history]() | Which conversation and which representation of it am I using\? | Persistent identity\, live context\, provider\-facing state\, workspace scope\, and exported copies\. | | [Memory and reusable knowledge]() | What can return beyond the current conversation\, and why\? | Memory scope\, retrieval\, correction\, managed skills\, automation\, privacy\, and costs\. | | [Tangent work and live control]() | Which worker am I addressing\, and what exactly am I stopping or continuing\? | Focus\, agent identity\, background jobs\, shared files\, result delivery\, and revival\. | | [Tool permissions and approvals]() | Why is this exact operation allowed\, prompted\, or denied\? | Tiers\, policy precedence\, ordered shell rules\, device identity\, one\-call decisions\, UI capability\, launch inputs\, and host authority\. | | [Extensions inside those boundaries]() | How can a capability expose useful actions without hiding its lifetime or authority\? | Human and machine interfaces\, persistence\, permission\, UI modes\, delivery\, loading\, and verification\. | All **65 original catalogued source reading sections remain in full**\, alongside the **complete new permissions part**\. The original code\, exercises\, failure cases\, references\, and evidence chapters remain part of this book\. The retained Orientation chapters establish each source’s scope\; the part introductions explain how that material fits together\. Repeated warnings are not silently discarded\: a warning about memory deletion\, a warning about conversation reset\, and a warning about widening tool permission protect different boundaries\. Read front to back for the complete progression\, or choose a reading path for a concrete problem\. The connection chapters bring the parts together without replacing their detailed contracts\. The [shared glossary]() explains terms that recur with different meanings\. ### Prerequisites and practice modes You can read the entire book without an OMP installation\, account\, credentials\, or provider access\. | Activity | Prerequisites | Boundary | | --- | --- | --- | | Read chapters and the complete Markdown edition | A browser or Markdown reader | Reading does not operate OMP\. | | Use the [Memory lab]() | A JavaScript\-capable browser for its controls | The stories and selectable illustration are fictional\; no memory backend is connected\. | | Inspect downloaded continuity fixtures | A shell\; `jq` for the supplied JSON queries\; Bun for the Return Desk helper\; `shasum` for the optional comparisons | Read or prepare only disposable fictional material\. | | Rehearse native continuity commands | A compatible installed OMP and an interactive terminal\, using the complete generated lab environment | Stop at model or authentication setup\. No provider prompt is part of that route\. | | Work through permissions cases | Read the fictional JSON and recorded outcomes | No OMP launch\, policy change\, shell execution\, or live approval is required\. | | Work through extension examples | Basic TypeScript\, Bun\, a compatible custom OMP host\, and the matching dependencies named by the example | A matching version string alone does not prove API compatibility\. | The [combined example archive]() preserves the supplied directory structure and contains the Extension and Continuity examples\, plus the Permissions case fixtures\. Permissions practice uses [Approval Desk]()\, [Dispatch Desk]()\, and [Boundary Desk]()\. These three files are inert cases\, not a live simulator or configuration to install\. Memory’s practice material is in its chapters and interactive lab\; Tan’s Lantern Library fixtures are printed in its chapters\. There is no invented Memory or Tan download package\. A disposable directory is useful data separation\, not an operating\-system sandbox\. Likewise\, `--no-extensions`\, an in\-memory session\, or a clean profile does not establish that every startup activity is offline\. A read tier is a declaration\, not a universal promise of read\-only behavior or zero network activity\. The source chapters explain the narrower controls they actually use\. ### Keep the input surface attached to the instruction The original captions identify where an example belongs\. Preserve that distinction when reading or copying it\: - **Terminal shell\:** executable launches\, configuration inspection\, and fixture inspection\, only under the stated prerequisites and owned scope\. - **Main’s OMP composer\:** native slash commands and ordinary requests to Main\. - **Focused Tan chat\:** plain\-language messages to the verified agent\, with steering and follow\-up behavior determined by its current state\. - **Model tool interface\:** schema\-shaped arguments for a tool that actually exists in that session\. A JSON argument object is not a terminal command\. - **Extension or SDK code\:** source to inspect or load through its documented host\, not text to paste into a conversation\. - **Permissions case data\:** fictional declarations\, arguments\, responses\, and shell\-shaped strings to classify\. Do not execute those strings\, submit those fictional calls\, or install the cases as settings\. - **Workbook browser controls\:** navigation\, disclosures\, authored illustration or milestone selection\, copying\, and self\-reported lesson ticks only\. Copying a snippet does not execute it\. A slash command is not automatically a model\-callable tool\. A method documented for a command context is not made safe inside a tool by a type cast\. Selecting an approval milestone in the browser does not approve any real OMP call\. ### Fiction is the default learning environment Cedar\, Lantern Library\, Lantern Board\, Cedar Library\, Harbor Notes\, Seed Desk\, Review Desk\, Field Notes\, and the permissions part’s Cedar Seed Library are teaching fixtures\, not a shared real project\. Similar names do not establish shared files\, sessions\, or evidence\. In particular\, Tan’s Lantern Library and Continuity’s Lantern Board are separate stories\, and the recorded Decision Desk checks used a separate Cedar Library fixture\. The permissions recording tools are not the Seed Desk reservation extension\, despite the seed\-library theme\. Use the supplied fiction to predict outcomes\, inspect complete records\, and understand refusals\. Source chapters retain optional real\-use prompts and service\-integration examples\, but their inclusion is not a request to execute every snippet\. Completing this unified reading route requires **no real memory disclosure\, authentication experiment\, provider inference exercise\, live upload\, privileged\-broker exercise\, or destructive session operation**\. Do not use `/drop`\, `/memory clear`\, or `/memory reset` as workbook cleanup\. Sharing remains a decision exercise\, not an upload exercise\. A permissions refusal is not a request to change personal settings or switch to yolo\. Some source checkpoints describe actual operations a reader might later perform\. Leave those unchecked if you only read or simulated them\. Understanding an operation and having verified it in a real session are different accomplishments\. ### Read evidence at its stated strength The book distinguishes four kinds of statements\: - **Recorded observation\:** a supplied report describes a completed check under named conditions\. - **Source\-backed behavior\:** the source workbook traces a contract to the implementation or types it received\. - **Exercise or expected checkpoint\:** a result to test or reason about\, not a newly observed result\. - **Editorial connection\:** an explanation or operating recommendation derived from several chapters\, not a new API guarantee\. The sources describe custom snapshots\. Reports that name `omp/18.0.7` do not establish parity with every release carrying that version\. Memory’s Mnemopi settings are a recorded configuration snapshot\, not a statement about your machine\. The permissions source and new evidence are dated 30 August 2026\; earlier reports remain historical\. Permissions retains two runs of existing focused tests—96 passes across four files\, then 105 across two—plus a separate Main\-executed private report of 46 fictional scenarios and an isolated configuration CLI observation\. The 201 passing existing tests are not one newly rerun aggregate of the earlier books\. Combining the manuscripts does not rerun their tests\, inspect a reader’s databases or policies\, or turn SDK\, controller\, RPC helper\, recording\-adapter\, or terminal\-emulator evidence into physical TUI proof\. ### Reading with a browser agent The unified reading interface is **`window.ompWorkbook`\, version 1**\, with tutorial\-only scope\. Consult its live `discover()` and `inspect()` results and [the browser contract]() for exact controls and availability\; do not construct control IDs from labels\. It cannot observe or control a real OMP process or resolve that process’s permission policy\. Unified lesson ticks use `omp-workbook-checklist-v1` in browser storage\. They record the reader’s report\, not a test result\. The separate Memory lab retains `window.memoryTutorial` and its own checklist storage on that lab page only\. Its API is not an alias for the unified reading interface\. A navigation receipt reports a navigation request\, not a successfully loaded destination\. Inspect the destination document after navigation\; a wait on the old document cannot follow it\. For the complete distinction between tutorial observations and OMP evidence\, read [Match each claim to the layer that was checked]()\. ## Sessions\, resets\, and reviewable history Begin with the question that precedes every useful action\: **where am I\, and what state have I actually recovered\?** A saved conversation can explain yesterday’s decision without restoring yesterday’s files\. A reset can empty model context while retaining earlier journal entries\. A local export can include history that a compact transcript view does not show\. These distinctions make continuity the foundation for the rest of the book\. ### Follow the three desks **Return Desk** begins with a deliberately small disagreement\: yesterday’s Lantern Board conversation says “Ready for pickup\,” while today’s workspace says “Packed and waiting\.” The correct result is not to make those observations match\. It is to identify the intended journal and understand that the current file remains current\. Read the ledger before using the helper\, and use the complete generated environment if you rehearse native resume or continue\. **Decision Desk** separates a conversational fork from workspace isolation\, then gives fresh\, clear\, and new different jobs\. The important identity is the persistent header identity exposed by `SessionManager.getSessionId()`\. The source’s `AgentSession.sessionId` is provider\-facing and can change without a new journal being created\. **Review Packet** follows material out of the active conversation into dumps\, sidecars\, HTML\, and possible sharing routes\. The Harbor Notes parent\, Scout\, and Checklist journals make older and nested content inspectable without exposing a real session\. This is different from the later Extension part’s Review Desk\, which records local review decisions and has no publishing operation\. ### Use the lab without borrowing personal history The public starting points are [Return Desk’s fixture inventory]()\, [its lab helper]()\, [Decision Desk’s recipe]()\, and [Review Packet’s inspection recipe]()\. The helper creates owned fictional material\; it does not launch OMP\. Native resume and continue practice uses the same actual terminal tab and generated environment\. If startup asks for model or authentication setup\, stop rather than importing credentials or substituting a personal journal\. Fixture inspection remains useful even when native interaction is blocked\. The missing\-directory and failure chapters are decision exercises\. They are not instructions to delete a directory\, manufacture a live provider failure\, or force a transition past a guard\. ### Keep the evidence attached The [continuity ledger]() is the recurring reference\. The [operation decision matrix]() is a lookup aid after the worked chapters\, not a replacement for their prerequisites and failure phases\. The recorded checks include manager\, SDK\, controller\, parser\, and read\-only RPC startup paths\, plus a separate headless\-browser export check\. They do not establish physical terminal behavior\, universal rollback\, real provider repair\, or live upload cancellation\. The final evidence chapter preserves those limits in full\. ## Orientation Resume the conversation you meant to resume\. Explore an alternative without losing the original conversation\. Reset the state you intended to reset\. Prepare a review packet without treating a hidden panel\, an encrypted link\, or a cancellation message as proof of privacy\. This is an independent educational workbook for the supplied current custom implementation of Oh My Pi\. It is not official product marketing or a compatibility promise for every OMP release\. ## Start here Oh My Pi\, usually shortened to **OMP**\, is an agentic coding command\-line application\. You give it a task\; its agent can work through model responses and tools that inspect or change a project\. A session records the conversation and associated session information\. **It is not a backup of the workspace\.** Reopening a conversation that discussed an earlier file does not restore that file\. Forking a conversation does not create a separate Git worktree\. Clearing the conversation does not erase retained history or previously generated exports\. This workbook follows three fictional stories\: | Story | Fictional reader | Practical outcome | | --- | --- | --- | | Return Desk | Maya maintains Lantern Board across several sittings\. | Find the intended history\, reopen it deliberately\, and distinguish resuming from relocating a session\. | | Decision Desk | Eli wants to explore another direction for Lantern Board\. | Fork the conversation\, then choose correctly between fresh\, clear\, and new\. | | Review Packet | Noor reviews the invented Harbor Notes project\. | Inspect a local packet\, including older and nested history\, before making any disclosure decision\. | The recorded Decision Desk tests use a separate fictional Cedar Library fixture\. Those tests support the operation boundaries\; they are not a recording of Maya or Eli using the public Lantern Board recipe\. ### What you need You need basic prompting\, terminal use\, and filesystem paths—not extension or RPC programming\. For the public exercises\: - A downloaded\, disposable copy of the [complete examples bundle]()\. - A terminal shell\. - `jq` for the JSON inspection and receipt commands\. - Bun for the supplied Return Desk lab helper\. - `shasum` for the optional byte\-comparison checks\. - An already installed `omp` executable and an interactive terminal for native session exercises\. The receipt\-capture commands reproduce the supplied macOS\-style `mktemp -t` recipes\. Their exact shell behavior is not presented as a Windows or cross\-platform installation recipe\. Run commands described as “from `examples/`” in the extracted directory containing `return-desk/`\, `decision-desk/`\, and `review-packet/`\. **No installation\, login\, provider prompt\, live sharing\, or destructive session exercise is required\.** If a clean lab profile stops at model or authentication setup\, stop there\. Do not supply credentials to force the exercise onward\. ### Three kinds of evidence Throughout the book\: - **Source\-backed expectation** means the supplied implementation defines that behavior\. - **Recorded check** means a completed supplied report observed it under its stated test conditions\. - **Your observation** means something you actually inspected in your own disposable lab\. These are not interchangeable\. Printing a command is not executing it\. A component test is not a physical terminal test\. A local fake provider handle is not a real provider incident\. Some downloadable files retain preparation\-time verification labels\. The completed reports summarized in [Evidence and limitations]() supersede those older labels for the named checks—not for every possible environment or reader action\. Begin with [the continuity ledger]()\, then follow the three desks\. Keep the [operation decision matrix]() and [recovery and disclosure checklists]() nearby\. ## The continuity ledger Before choosing an operation\, name the state you want to change\. “Reset my session” is too vague\. It might mean stopping a response\, dropping conversation context\, starting a different identity\, discarding provider\-facing handles\, or deleting local history\. Those are different requests\. ### The seven boundaries | Layer | What it means | What it is not | | --- | --- | --- | | **Live and model context** | The messages currently held by the agent\, plus the transformations used to prepare model context\. | Every entry ever retained in the journal\, or an exact captured HTTP request\. | | **Durable journal** | The saved JSONL conversation record\, including messages and metadata\. It can retain older and alternative paths\. | A directory snapshot or a complete record of every unfinished streaming token\. | | **Persistent session identity** | The identity in the session header\, exposed by `SessionManager.getSessionId()`\. | Necessarily the same value as a provider\-facing session ID\. | | **Provider\-facing state** | Request identity\, local transport\/session handles\, and possibly a separate prompt\-cache key\. | A guarantee about remote retention\, remote deletion\, or cache behavior\. | | **Cwd and project scope** | The active working directory\, recorded header cwd\, and any additional workspace roots\. These can differ during fallback or failure\. | A copy of the project at the time the conversation began\. | | **Workspace files** | The files that exist now in the project\. | Files restored merely because an old conversation was reopened\. | | **Artifacts and outputs** | Session\-adjacent artifacts and nested journals\, generated HTML\, temporary dump sidecars\, and copied text\. | One automatically synchronized\, automatically deleted privacy boundary\. | The rendered transcript is another **view** of these layers\. It may collapse older context or hide some content\. A shorter display does not establish a shorter journal\. A journal’s entries have their own IDs and parent relationships\. The active leaf selects a conversation path for context rebuilding\. You do not need to learn the entire tree implementation here\; you do need to remember that **all stored entries** and **the active conversation path** are not the same thing\. ### Milestone\: Identify yesterday before opening anything **Need\.** Maya wants yesterday’s Lantern Board discussion\. **Obstacle\.** Yesterday’s conversation says “Ready for pickup\,” but today’s workspace file says “Packed and waiting\.” Both statements can be present without OMP having lost anything\. Read the public fixtures first\: - [Yesterday’s journal]() - [Today’s workspace text]() - [Return Desk exercise inventory]() **Terminal shell — read\-only inspection\, from extracted `examples/`\:** ~~~sh jq -s 'map(select(.type == "session") | {id, cwd, title})' return-desk/yesterday.jsonl jq -s 'map(select(.type == "message" and .message.role == "user") | .message.content)' return-desk/yesterday.jsonl cat return-desk/today.txt ~~~ **Structured example output — derived from the public header\, not a new terminal capture\:** ~~~json [ { "id": "11111111-1111-4111-8111-111111111111", "cwd": "/fictional/lantern-board", "title": "Lantern Board: yesterday's labels" } ] ~~~ The fixture’s user message is\: > For our fictional Lantern Board\, use the label Ready for pickup\. We will revisit it tomorrow\. The workspace file identifies its current label as\: > Current label\: Packed and waiting **What changes\?** These inspection commands change neither the fixture nor an OMP session\. **What stays separate\?** The full session identity\, the header’s recorded cwd\, the conversation text\, and today’s file contents are four different observations\. The short entry ID of a message is not the persistent session identity\. **Recorded check\.** `identity-journal-cwd-workspace` reopened a real `SessionManager` journal and retained its identity\, location\, entries\, and cwd while the fictional workspace bytes remained unchanged\. **Failure and recovery\.** If `jq` cannot read or parse the fixture\, fix the working directory or restore a clean downloaded copy\. Do not substitute a personal journal\. The `/fictional/lantern-board` path and `fictional-offline-model` label are fixture data\, not a project or provider to configure\. **Self\-check\.** After resuming yesterday\, which label should `today.txt` contain\? **Answer\:** “Packed and waiting\.” Resuming history does not reverse the file change represented by the fixture\. ### A path is not proof of persistence The current manager can allocate a session ID and transcript path before materializing the file\. New\-session persistence is lazy until assistant output or another explicit persistence reason makes the file necessary\. That means\: - An assigned filename does not prove that a resumable file exists\. - An empty new conversation can still have model or thinking metadata in memory\. - A session created with `--no-session` normally has no journal file\, but a dump can still create a temporary sidecar\. - Completed entries and in\-flight streaming text have different durability boundaries\. The supplied `SessionManager` comments describe completed\-entry writes reaching the operating system without `fsync`\: software\-crash durability is not a power\-loss backup guarantee\. **Source anchors\:** `packages/coding-agent/src/session/session-manager.ts` — `SessionManager`\, `getSessionId`\, `getSessionFile`\, `isSessionOnDisk`\, `buildSessionContext`\; `packages/coding-agent/src/session/session-context.ts` — `buildSessionContext`\; `packages/coding-agent/src/session/session-entries.ts` — `SessionHeader`\, `ResetBoundaryEntry`\. ## Return Desk lab setup The raw fixture is suitable for reading\. Native resume practice needs something more\: an existing project directory and an owned session collection\, without mixing the exercise into ordinary history\. The supplied [lab helper]() provides that preparation\. It does not launch OMP or import its SDK\. ### Milestone\: Copy fiction into an owned lab **Need\.** Maya wants to practice the real command surfaces\. **Obstacle\.** Placing a fixture in a normal session store would mix exercise data with personal history\. Opening the unre\-based fictional path would also confuse recorded cwd with a real project\. First discover the helper’s supported operations\, then create a lab\. **Terminal shell — fixture preparation\, from extracted `examples/`\:** ~~~sh bun return-desk/lab.ts '{"version":1,"op":"discover"}' RECEIPT=$(mktemp -t continuity-return-receipt) bun return-desk/lab.ts '{"version":1,"op":"act","action":"create"}' | tee "$RECEIPT" ~~~ Stop if the receipt reports `ok: false`\. Read it before continuing\. Each successful create makes a new temporary root containing\: - Dedicated home\, agent\/config\, temporary\, and XDG directories\. - A project containing the fictional `today.txt`\. - Yesterday’s copied journal\, with its cwd rebased to that project\. - A newer unrelated fictional note\. - A lab marker and receipt\. - Complete native commands with the correct paths\. Keep the following variables in this same terminal\: **Terminal shell — receipt values and executable selection\:** ~~~sh LAB=$(jq -r '.root' "$RECEIPT") SOURCE=$(jq -r '.yesterday' "$RECEIPT") SESSIONS=$(jq -r '.sessions' "$RECEIPT") PROJECT=$(jq -r '.cwd' "$RECEIPT") OMP_BIN=$(command -v omp) ~~~ `OMP_BIN` must identify the intended installed executable\. Stop if it is empty\. If your shell reports an alias or function rather than an absolute executable path\, resolve that before using the generated commands\. You can re\-inspect the existing lab through the helper’s supplied version\-1 inspection operation\: **Terminal shell — read\-only lab inspection\; this `jq` composition supplies the documented inspection request\:** ~~~sh bun return-desk/lab.ts "$(jq -c '{version:1,op:"inspect",root:.root}' "$RECEIPT")" ~~~ Inspection validates the lab marker and canonical root\. It does not inspect a running OMP process\. ### Understand the generated environment The native commands begin with `env -i`\, retain `PATH`\, and supply dedicated home\/config\/session paths\. They also include explicit `--cwd` and `--session-dir` values and flags disabling extensions\, skills\, rules\, LSP\, tools\, and title generation for the recipe\. The lab settings disable memory\, autolearn\, advisors\, skills\, secrets\, marketplace auto\-update\, and automatic resume\. **Use the whole printed command\. Do not shorten it to a bare `omp --resume …`\.** This is data separation\, not an operating\-system sandbox\. In particular\: - Native OMP startup may discover providers or refresh metadata without a model prompt\. - The helper’s synthetic `TMUX_PANE` is only a terminal\-identity fallback\. - OMP prefers stdin’s actual TTY identity when available\. - Resume and continue practice must use the **same actual terminal tab** and generated environment\. **What changes\?** The helper creates new fictional files under one owned temporary root\. **What does not change\?** It does not open or rewrite ordinary session history\, launch OMP\, or submit a model request\. **Recorded checks\.** The public helper’s discover\, create\, and inspect operations completed successfully inside the isolated proof\. A separate source\-CLI check used the generated lab for resume\, continue\, and fork with read\-only RPC inspection\. That CLI check added private disabled\-provider policy and a guarded transport\. It was not physical TUI interaction and does not make ordinary native startup network\-free\. **Failure and recovery\.** If native startup requires setup or authentication\, stop\. Do not log in\, paste a key\, copy an auth database\, or send a prompt\. You can still inspect the fictional files and study the recorded results\; record native interaction as blocked\, not passed\. **Self\-check\.** Does a successful create receipt prove that OMP resumed yesterday\? **Answer\:** No\. It proves fixture preparation succeeded\. Native execution and identity inspection are separate observations\. ## Return Desk resume selection Maya remembers the topic\, but the newest file is not necessarily the conversation she wants\. The safest approach is to name the intended identity or known file\, then inspect the resulting session before asking it to do more work\. ### Milestone\: Open the known copied journal **Need\.** Return to yesterday’s labels\, not today’s unrelated packaging note\. **Obstacle\.** A recent\-session list answers a recency question\. Maya has an identity question\. Print the exact command from the receipt\: **Terminal shell — print the generated native command\:** ~~~sh jq -r '.commands.resumeExplicitPath' "$RECEIPT" ~~~ Read\, copy\, and run the complete printed command in the same terminal\. Printing it alone is not the exercise\. If startup succeeds\, remain idle and inspect the session\. **Human OMP slash commands — inside the isolated lab\, one at a time\:** ~~~text /session info /dirs ~~~ The supplied TUI session\-info implementation displays a file and an ID\. `/dirs` lists the manager’s working directory and additional roots\. Check that\: 1. The displayed session file is the receipt’s `yesterday` file\. 2. The conversation contains the two fictional Lantern Board messages\. 3. The working directory is the copied project\, not `/fictional/lantern-board`\. 4. The workspace remains the current workspace\. Use the saved header’s `type: "session"` record as the durable identity reference\. Modern journals may have a title slot before that record\, so selecting by type is safer than assuming the first physical line is always the header\. Do not assume that every field named `sessionId` in every surface means persistent journal identity\. In the supplied implementation\, `AgentSession.sessionId` is provider\-facing\; the distinction becomes important after `/fresh`\. **What changes\?** A native process opens the selected saved conversation and rebuilds runtime context\. **What does not change\?** It is not implicitly forked\, and workspace files are not restored\. **Expected observation\.** The copied journal has persistent identity `11111111-1111-4111-8111-111111111111`\. **Recorded check\.** The separate source\-CLI resume check returned that identity\, the intended journal\, two messages\, the copied project cwd\, and unchanged workspace bytes\. It exited successfully after read\-only inspection\. **Failure and recovery\.** Stop on setup\, unexpected identity\, unexpected cwd\, or a persistence error\. Do not send a prompt to ask the model whether the switch worked\. A model’s answer would be weaker evidence than the session file and scope\. **Self\-check\.** Why inspect both identity and cwd\? **Answer\:** The right conversation in the wrong project scope is still unsafe to continue\. ### Milestone\: Inspect and cancel the in\-session picker **Need\.** Maya wants to look for another history without committing to a switch\. **Obstacle\.** Opening a selector and selecting a session are different actions\. **Human OMP slash command — inside the idle fictional session\:** ~~~text /resume ~~~ The native picker begins in **current\-folder** scope\. - **Tab** toggles between current\-folder and all\-projects scope\. - **Enter** selects the highlighted native session\. - **Escape** cancels the picker and returns to the current session\. All\-projects data is loaded lazily and cached for that picker\. Reopen the picker if you need a refreshed listing after histories change elsewhere\. “Current folder” is a session\-listing scope\, not a filesystem permission boundary\. With a custom session directory\, the list is drawn from that directory\. “All projects” searches the native global store\; it is not a disk\-wide search of arbitrary custom folders\, backups\, or every nested artifact\. The lab’s explicit session directory is separate from ordinary managed global buckets\. An empty all\-projects view in this lab does not mean the current\-folder fixtures disappeared\. For this milestone\, cancel with Escape\. Then inspect session information and directories again\. **What changes\?** The selector’s scope and presentation can change\. **What does not change on cancellation\?** No selected target replaces the active conversation\. **Recorded check\.** Actual `SessionSelectorComponent` key handling and an inert controller host confirmed cancellation\, current\-folder startup\, Tab use of preloaded global data\, and delivery of the selected record on Enter\. Physical terminal rendering was not tested\. **Failure and recovery\.** If global loading fails\, remain in the current session and retry the picker later\. Do not interpret an empty search result as deletion\. Titles\, previews\, and status labels are navigation aids\, not a complete journal audit\. **Self\-check\.** Does pressing Tab authorize switching to another project\? **Answer\:** No\. It changes the search scope\. Selection is a separate action\. ### Milestone\: Resolve a known identity deliberately The slash command can resolve a native session identity or filename prefix directly\. **Human OMP slash command — inside the idle fictional session\:** ~~~text /resume 11111111-1111-4111-8111-111111111111 ~~~ The current slash implementation searches locally first\, then explicitly allows global fallback—even when the active manager has a custom session directory\. It does **not** have the terminal command’s direct filesystem\-path branch\. Do not treat a slash argument containing a JSONL path as equivalent to terminal `--resume`\. The resolver accepts case\-insensitive prefixes of\: - The session ID\. - The filename stem\. - The ID portion after the timestamp separator in the filename\. It takes the **first matching record**\, not a guaranteed unique match\. Prefer a full known identity over a short ambiguous prefix\. **What changes\?** A successful lookup switches or reloads the matched conversation\. **What does not change\?** It does not create a fork or restore workspace files\. A same\-file reload can still rebuild runtime context\. **Recorded check\.** `local-global-prefix-and-unknown` confirmed local\-first resolution\, case\-insensitive identity matching\, filename matching\, interactive global fallback\, and startup\-directory confinement\. **Failure and recovery\.** An unknown slash identity reports not found\. Do not silently pick a different conversation\. Verify the target against the supplied header or reopen the picker\. **Self\-check\.** Is a very short prefix safer because it is easier to type\? **Answer\:** No\. Convenience does not establish uniqueness\. ### Terminal resume is a different surface The following table is a **non\-runnable syntax reference**\, not a record of execution\: | Surface | Syntax | Meaning | | --- | --- | --- | | Human\, inside OMP | `/resume` | Open the in\-session picker\. | | Human\, inside OMP | `/resume ` | Resolve a native identity\/filename prefix\, local first with global fallback\. | | Terminal | `omp --resume` | Open the startup picker\. | | Terminal | `omp --resume ` | Resolve an identity or directly open a path\-like value\. | | Terminal | `omp --session-dir --resume ` | Confine startup identifier lookup to that directory\. | The startup restriction applies to **identifier lookup**\. It is not a general prohibition on direct paths or the picker’s all\-projects scope\. The environment’s `PI_CODING_AGENT_SESSION_DIR` can also supply an explicit startup directory\. A path\-like terminal value contains `/` or `\`\, or ends in `.jsonl`\. It goes directly to `SessionManager.open`\. **Important path trap\:** an unknown identifier and a missing explicit file are not equivalent\. The supplied open\/set\-file implementation can treat an empty or missing explicit path as a fresh session and materialize a header there\. Do not use a typoed path as a guaranteed “not found” test\. ### Milestone\: Cancel startup and test an unknown identity Exit the fictional session normally\: **Human OMP slash command — inside the lab\:** ~~~text /exit ~~~ Print the startup picker command\, then run the whole printed command\. **Terminal shell — print the generated startup picker command\:** ~~~sh jq -r '.commands.resumePicker' "$RECEIPT" ~~~ Cancel that picker with Escape\. Unlike in\-session cancellation\, this cancels startup rather than returning to an already active conversation\. The source\-backed exit text is `No session selected`\. If both the current\-folder and global listings are empty\, startup instead reports `No sessions found`\. An empty current\-folder list does not automatically switch the picker to all projects\. Startup may preload the global list\, but the scope switch remains deliberate\. Next\, print and run the generated unknown\-identity command\: **Terminal shell — print the generated unknown\-target command\:** ~~~sh jq -r '.commands.unknownIdentity' "$RECEIPT" ~~~ **Expected observation\.** The native target `not-a-fictional-session` fails identifier resolution rather than silently selecting another history\. **What changes\?** A startup attempt begins and then exits or fails\. There is no successful conversation selection in either exercise\. **What does not follow\?** Do not infer that every piece of startup bookkeeping\, including breadcrumbs\, must remain untouched\. Re\-establish the intended conversation before the continuation exercise\. **Recorded boundary\.** Picker component cancellation and manager\-level unknown\-ID behavior were checked\. Physical startup picker cancellation and its terminal exit text remain source\-backed rather than physically observed\. **Self\-check\.** Which cancellation keeps a running conversation available\: in\-session `/resume`\, or terminal `--resume`\? **Answer\:** In\-session picker cancellation\. **Source anchors\:** `packages/coding-agent/src/slash-commands/builtin-lifecycle.ts` — `resume` and `dirs` entries\; `packages/coding-agent/src/session/session-listing.ts` — `sessionMatchesResumeArg`\, `resolveResumableSession`\; `packages/coding-agent/src/main.ts` — `createSessionManager`\, `runRootCommand`\; `packages/coding-agent/src/modes/components/session-selector.ts` — `SessionSelectorComponent`\; `packages/coding-agent/src/modes/controllers/selector-controller.ts` — `showSessionSelector`\, `handleResumeSession`\. ## Return Desk continuation “Continue” is convenient when you mean this terminal’s applicable previous conversation\. It is a poor substitute for an exact identity when several histories are plausible\. There is **no interactive `/continue` slash command** in this workflow\. ### Milestone\: Continue from a deliberately established breadcrumb **Need\.** Maya wants to leave yesterday’s conversation and return to it from the same terminal\. **Obstacle\.** The session collection also contains a newer unrelated note\, and earlier startup experiments may have changed bookkeeping\. Re\-establish yesterday first\: **Terminal shell — print the known resume command again\:** ~~~sh jq -r '.commands.resumeExplicitPath' "$RECEIPT" ~~~ Run the complete printed command\. If it reaches the idle fictional session\, inspect it and exit normally without prompting\. Then print and run the continuation command in the **same actual terminal tab**\: **Terminal shell — print the generated continuation command\:** ~~~sh jq -r '.commands.continue' "$RECEIPT" ~~~ After startup\, inspect again\: **Human OMP slash commands — inside the resumed lab\, one at a time\:** ~~~text /session info /dirs ~~~ **Expected observation\.** Yesterday’s intended identity and fictional conversation return\. **What changes\?** A new process adopts the selected conversation\. If continuation finds no usable history—or must honor a fresh empty boundary—it can create a new empty identity instead\. **What does not change\?** Continuation does not restore yesterday’s workspace files\. **Recorded checks\.** - A controlled manager check made an older breadcrumb beat a newer file\. - Missing breadcrumbs used most\-recent\-modified history\. - Stale breadcrumbs pointing at missing files fell back\. - Fresh\, unmaterialized boundaries did not resurrect earlier history\. - Empty history created a new identity\. - The separate source\-CLI continuation check returned yesterday’s identity and two messages with unchanged workspace bytes\. The public helper initially gives the unrelated note a newer modification time\. Native startup and shutdown can add lifecycle records\, however\, so the files’ relative modification times may change during practice\. Seeing yesterday return verifies your selected result\; it does not by itself reproduce the controlled “older breadcrumb beats newer file” test\. **Failure and recovery\.** If another conversation returns\, do not send work to it\. Use the exact known resume target\. If a new empty conversation appears\, check breadcrumb availability\, the terminal\, the generated environment\, and the session directory before assuming history was deleted\. **Self\-check\.** What should you use when you know the exact conversation you need\? **Answer\:** An exact known `--resume` identity or verified path\, not a guess based on `--continue`\. ### How continuation chooses The current `SessionManager.continueRecent` behavior can be understood as this decision sequence\: 1. **Read the terminal\-scoped breadcrumb\.** A missing or corrupt breadcrumb is not a usable selection\. A stale breadcrumb whose file is gone is normally ignored\. 2. **Honor a fresh missing\-file boundary\.** A deliberately new session whose lazy journal never materialized must not cause old history to reappear\. Continuation starts empty instead\. 3. **Recover an interactive root if necessary\.** A breadcrumb pointing into nested session artifacts is walked upward toward the top\-level interactive journal\, with an eight\-level cap\. 4. **Use an applicable same\-cwd breadcrumb\.** This can win over a more recently modified journal\. 5. **Handle a different recorded project\.** An existing different project is not simply adopted by continuation\. Ordinarily OMP falls back to history in the current scope\. A vanished source project can trigger the relocation case in the next chapter\. 6. **Use recent history when appropriate\.** “Recent” here is based on modification time of usable session files—not title\, filename date\, or your intended topic\. 7. **Create a new session if none is found\.** The nested\-artifact recovery rule is source\-backed\; it was not executed in the supplied Return Desk scenarios\. ### Terminal identity matters `getTerminalId()` prefers stdin’s real TTY device path\. Terminal and multiplexer environment variables are fallbacks\. Consequently\, the helper’s synthetic pane value does not override a real TTY\. Using another terminal tab can change which breadcrumb is applicable even when you use the same session directory\. Breadcrumbs are stored separately from the journal\. They are navigation bookkeeping\, not an additional workspace snapshot\. ### Two startup details worth recognizing - `autoResume` defaults to false\. When enabled and no explicit session choice or session directory takes precedence\, startup uses the continuation behavior and restores prior model\/thinking state when history is found\. - A compatibility normalization recognizes a full UUID in the supported `--continue ` layout\, including the sole\-positional\-message case\, and turns it into resume\. Prefer explicit `--resume ` rather than relying on that compatibility rule\. At the manager\-creation boundary\, `--no-session` wins over string resume and continue processing\. That does **not** prove that the separately routed bare startup picker or a later interactive resume can never open a file\. Do not combine flags and treat the combination as a privacy policy\. **Source anchors\:** `packages/coding-agent/src/session/session-manager.ts` — `continueRecent`\, `resolveBreadcrumbToInteractiveRoot`\; `packages/coding-agent/src/session/session-paths.ts` — `writeTerminalBreadcrumb`\, `readTerminalBreadcrumbEntry`\; `packages/tui/src/ttyid.ts` — `getTerminalId`\; `packages/coding-agent/src/main.ts` — `normalizeContinueSessionArgs`\, `createSessionManager`\. ## Return Desk missing\-directory decisions A saved conversation can outlive the project directory recorded in its header\. That is not merely another search failure\. It raises a new question\: **where should this conversation be rooted now\?** ### Milestone\: Choose relocation or fallback consciously **Need\.** Maya finds the right journal\, but its recorded project directory is gone\. **Obstacle\.** Different entry paths do not ask the same question or perform the same relocation\. This is a decision exercise\. Do not delete a directory to manufacture it\. **Exact action\:** identify which entry path you are using\, then apply the matching row below\. For an ID\-based relocation prompt\, choose Yes only when the launch directory is the intended replacement project\. | Entry path and condition | Current behavior | What to inspect afterward | | --- | --- | --- | | Startup `--resume `\; recorded cwd still exists | Open the matched journal\. Startup adopts the resumed project scope and reloads cwd\-scoped settings\/caches\. | Identity\, journal file\, active directories\, applicable project settings\. | | Startup `--resume `\; recorded cwd is gone\; Yes or default answer | Re\-root that same session into the launch directory\. The journal and its artifact namespace are relocated\, not duplicated as a fork\. | Same persistent ID\; new journal location\; updated header cwd\. | | Same ID lookup\; No | Cancel startup rather than fall through to a new conversation\. | No successful resume\; original journal remains available\. | | Same ID lookup\; consent unavailable without a TTY | Fail with an instruction to run interactively\. | No assumed relocation\. | | Startup `--resume `\; recorded cwd is gone | Direct opening bypasses the ID relocation prompt\. Active cwd falls back to the launch project without relocating the journal\. | Same journal location\; active cwd may differ from the retained recorded header cwd\. | | Runtime session\-file switch\; recorded cwd is gone | Keep the current active project instead of changing into a nonexistent directory\. | Target identity\, unchanged active cwd\, original journal location\. | | Startup picker selects a session with missing cwd | Its direct\-open path does not provide the ID\-lookup relocation consent flow\. | Launch\-cwd fallback and journal location\, rather than assumed relocation\. | | `--continue`\; breadcrumb’s source project is gone and destination lacks its own history | Can automatically re\-root the same session into the destination\. | Same identity\, relocated journal\, destination cwd\. | | `--continue`\; destination has its own applicable history | Prefer destination history rather than automatically adopting the vanished project’s session\. | Which identity actually won\. | For the ID prompt\, an empty answer means acceptance in the supplied source\. Declining produces the source\-backed startup message `Resume cancelled: session was not moved.` ### What re\-rooting does not repair Re\-rooting concerns the journal\/artifact namespace and the session’s cwd\. It does not\: - Restore a missing repository\. - Move or reconstruct the old workspace files\. - Make old tool results accurate for the new directory\. - Prove that the destination’s instructions are compatible with the old task\. - Rewrite every historical path inside conversation content\. A successful cross\-project resume can also change which project settings and instructions apply\. That is why cwd belongs in the ledger rather than in a footnote\. **Recorded checks\.** Injected acceptance moved the same identity\; decline returned no manager\; unavailable consent raised the interactive\-use instruction\. Direct\-path opening retained the journal location and used launch\-cwd fallback\. Controller checks also confirmed missing\-cwd fallback and settings\-save failure before switching\. Those answers were injected into the existing prompt seam\, not typed into a physical readline prompt\. **Failure and recovery\.** If relocation or cwd re\-scoping fails\, stop before further work\. Inspect identity\, current journal location\, and active directories\. The supplied code includes relocation and rollback handling\, but the evidence does not establish an all\-filesystem\, all\-failure atomicity guarantee\. **Self\-check\.** Maya opened a direct JSONL path\, and the active cwd is now the launch directory\. Has the journal necessarily moved\? **Answer\:** No\. Direct\-path fallback and ID\-based re\-rooting are different operations\. **Source anchors\:** `packages/coding-agent/src/main.ts` — `promptMoveSession`\, `moveMissingCwdSessionIfNeeded`\, `switchToResumedProject`\; `packages/coding-agent/src/session/session-manager.ts` — `open`\, `setSessionFile`\, `moveTo`\, `continueRecent`\; `packages/coding-agent/src/config/settings.ts` — `reloadForCwd`\. ## Decision Desk forking Eli wants to explore another direction while keeping the original conversation available\. A fork is useful for that\. It separates conversation identity and future journal ownership\. It does not isolate workspace changes\. ### Milestone\: Fork the current conversation **Need\.** Keep the original Lantern Board discussion while creating another conversational starting point\. **Obstacle\.** The word “fork” can suggest a Git branch\, a file snapshot\, or a previous\-message picker\. The supplied `/fork` does none of those things\. Use the complete [Decision Desk recipe]() and its [state ledger]()\. Create a **new** disposable lab for this story\. Preserve the previous receipt separately if you still need it\. **Terminal shell — Decision Desk preparation\, from extracted `examples/`\:** ~~~sh bun return-desk/lab.ts '{"version":1,"op":"discover"}' RECEIPT=$(mktemp -t continuity-decision-receipt) bun return-desk/lab.ts '{"version":1,"op":"act","action":"create"}' | tee "$RECEIPT" ~~~ Stop on `ok: false`\. Then retain its paths and the intended executable\: **Terminal shell — read the successful Decision Desk receipt\:** ~~~sh LAB=$(jq -r '.root' "$RECEIPT") SOURCE=$(jq -r '.yesterday' "$RECEIPT") SESSIONS=$(jq -r '.sessions' "$RECEIPT") PROJECT=$(jq -r '.cwd' "$RECEIPT") OMP_BIN=$(command -v omp) ~~~ The same prerequisites and stop rules from [Return Desk lab setup]() apply\. Record the parent and workspace before opening OMP\: **Terminal shell — read\-only baseline\:** ~~~sh shasum -a 256 "$SOURCE" jq -s 'map(select(.type == "session") | {id,parentSession,cwd,title})' "$SOURCE" cat "$PROJECT/today.txt" jq -r '.commands.resumeExplicitPath' "$RECEIPT" ~~~ Run the complete printed resume command\. Stop if it requires model\/auth setup\. Do not submit a prompt\. Inside the idle fictional conversation\: **Human OMP slash command — create the conversational fork\:** ~~~text /fork ~~~ Then inspect the child\: **Human OMP slash commands — inside the fork\, one at a time\:** ~~~text /session info /dirs ~~~ Keep the child active for the reset sequence in the next chapter\. ### The fork ledger A successful interactive fork has these source\-backed effects\: | Field | Expected result | | --- | --- | | Persistent identity | A new journal ID\. | | Transcript path | A new JSONL path\. | | Parent metadata | `parentSession` records the previous persistent ID\. | | Title and cwd | Retained from the current session\. | | Live conversation | Retained\. | | Ordinary steering\/follow\-up queues | Retained by this fork path\. | | Journal entries | All existing non\-header entries are carried into the new journal—not only the currently visible messages\. | | Workspace files | Still the same files in the same workspace\. | | Session artifacts | Copied recursively where available\, best\-effort\. | For this public source\, the child’s parent ID should be\: `11111111-1111-4111-8111-111111111111` The current registry description mentions a fork “from a previous message\.” The implementation route is more specific\: `handleForkCommand` calls `AgentSession.fork()` immediately\. **This is a current\-state fork\, not a previous\-message picker\.** A copied journal can retain older branches and pre\-clear entries that are not in current model context\. Forking is therefore not a way to reduce the disclosure content of a later export\. ### Artifacts are not a verified backup `copySessionArtifacts` derives the artifact directory by removing `.jsonl` from the transcript filename\. - Missing sources are ignored\. - Other copy errors are logged rather than thrown from that helper\. - The fork can therefore exist without every expected artifact having copied\. That copy does not cover arbitrary workspace files\, remote copies\, previously generated exports elsewhere\, or a guaranteed complete backup of every dependency\. **Recorded checks\.** The real SDK\/registry\/controller fork check created a new identity with parent metadata\, retained messages and ordinary queues\, preserved parent bytes around the fork call\, and copied one ordinary artifact\. The same test then wrote a fictional file in the shared workspace and confirmed that the parent manager saw the changed file at the same cwd\. The write was a test action\, not something `/fork` performed\. A separate real `copySessionArtifacts` check encountered a regular file blocking the destination directory\. It returned without throwing and did not copy the artifact\. That supports the best\-effort warning\; it is not broad filesystem coverage\. **Failure and recovery\.** Interactive `/fork` refuses while streaming\. An in\-memory session cannot fork through this path\. A before\-switch hook can veto it\. After any refusal or error\, inspect the actual file and identity before proceeding\. **Self\-check\.** If Eli later changes a workspace file while working in the fork\, will resuming the parent undo that file change\? **Answer\:** No\. The conversation identities differ\; the workspace is shared\. ### Interactive and startup forks differ This is a source\-backed comparison\, not another executed scenario\: | Boundary | Interactive `/fork` | Startup `--fork` | | --- | --- | --- | | Source | Current session | Explicit path or resolved native identity | | Cwd | Existing active cwd | Launch cwd supplied to startup | | Conversation | Retains current live messages | Rebuilds from copied journal history | | Parent\-process queues | Ordinary queues remain on the active fork path | No parent\-process steering\/follow\-up queues are cloned | | Journal | New identity\; original retained | New identity\; source retained | | Artifacts | Best\-effort copy | Best\-effort copy by default | | Workspace isolation | None | None | Full forks may inherit a provider prompt\-cache identity\. That is separate from journal identity and from provider request identity\. Changing the startup model\, thinking\, prompt\, or tool shape can suppress automatic inheritance\; explicit provider\/cache overrides are separate controls\. You do not need to tune those controls for this workbook\. The important conclusion is simpler\: **a new journal is not proof of a cold provider cache\, and a fork is not `/fresh`\.** **Source anchors\:** `packages/coding-agent/src/slash-commands/builtin-session.ts` — `fork` entry\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleForkCommand`\; `packages/coding-agent/src/session/agent-session.ts` — `fork`\; `packages/coding-agent/src/session/session-manager.ts` — `fork`\, `forkFrom`\, `copySessionArtifacts`\; `packages/coding-agent/src/main.ts` — `createSessionManager`\, `buildSessionOptions`\. ## Decision Desk resetting deliberately Eli now has a conversational fork\. Before changing it\, write down the intended boundary\: - Keep the conversation\, refresh local provider\-facing state\: **fresh**\. - Drop the live\/model conversation but keep this journal identity\: **clear**\. - Start another conversation identity\: **new**\. These operations are not escalating levels of secure deletion\. ### A before\-and\-after reset ledger The table describes successful native operations\. “Identity” means persistent journal identity\. | State | `/fresh` | `/clear` | `/new` | | --- | --- | --- | --- | | Live conversation | Retained | Cleared | Cleared | | Existing journal history | Unchanged by the operation | Retained\; reset boundary appended | Retained in the previous journal | | Persistent ID and path | Retained | Retained | New ID and allocated path | | Title | Retained | Retained | Ordinary new session starts without the prior title | | Model and settings | Retained | Retained | Not a factory reset\; current model\/settings remain applicable | | Provider\-facing state | Local handles closed\; fresh transient ID | Local handles closed\; fresh transient ID | Local handles closed\; normal identity selection resynchronized | | Ordinary queues | Retained | Cleared | Cleared | | Cwd and workspace | Unchanged | Unchanged | Current project remains | | Prior artifacts and exports | Retained | Retained | Prior artifacts retained\, not copied as a fork | | Active plan reference | Retained | Path retained and reference re\-armed | Ordinary new\-session reference resets to its default | Normally the provider\-facing ID after `/new` follows the new journal ID\. An explicit provider\-session override is a separate input\; do not turn that normal case into a universal identity rule\. ### Milestone\: Refresh the provider boundary without losing the conversation **Need\.** Eli wants to discard local provider transport\/session state while retaining the conversation\. **Obstacle\.** “Fresh session” sounds like an empty conversation\, but this command is deliberately narrower\. In the idle fictional fork\: **Human OMP slash command\:** ~~~text /fresh ~~~ **Expected observation\.** The visible conversation remains\. The status reports how many local provider states were pruned\. Zero can be normal\. The implementation closes cached provider\-state entries\, clears the local map\, mints a fresh provider\-facing ID\, rekeys associated session\-memory identity\, and invalidates append\-only context for rebuilding\. It does not append a reset boundary\, change the journal header ID\, or clear ordinary steering\/follow\-up queues\. The next model\-context build uses the retained conversation—not every old entry that might remain elsewhere in the journal\. **Recorded check\.** One inert provider handle received `close()`\. The provider\-facing ID changed\; persistent journal ID\, file\, bytes\, messages\, and ordinary queues remained unchanged\. That is local state\-transition evidence\. It does not prove that a real provider outage\, authentication failure\, remote conversation problem\, or retention concern was fixed\. **Failure and recovery\.** If a response is still streaming\, wait or abort through OMP’s normal control\, then retry\. A pruning count is not a remote deletion receipt\. Even local close errors can be logged while the handle map is cleared\. **Self\-check\.** Does a changed `AgentSession.sessionId` after `/fresh` prove that a new durable conversation was created\? **Answer\:** No\. That getter is provider\-facing\. Compare the persistent header ID and file\. ### Milestone\: Clear live context while keeping the journal **Need\.** Eli wants the next conversation to stop depending on the current turns\, but wants to continue this persistent session\. **Obstacle\.** A blank live transcript could be mistaken for erased history\. In the idle fictional fork\: **Human OMP slash command\:** ~~~text /clear ~~~ **Expected observation\.** The live transcript clears and OMP reports a context reset while the session continues\. The source\-backed reset drops\: - Live messages\. - Steering\, follow\-up\, and pending next\-turn messages\. - Pending tool calls and error state\. - Deferred session\-scoped tool decisions and internal per\-turn state\. - This agent’s scheduled continuation work and owned asynchronous jobs\. It also rotates provider\-facing state and refreshes applicable base\/project context\. Clearing conversation messages does not disable project instructions or erase a separate memory backend\. The persistent ID\, path\, title\, cwd\, model\, settings\, and active plan path remain\. A `reset_boundary` is appended to the journal\. Subsequent model\-context and collapsed\-live rebuilds honor that boundary\. Full\-history paths still retain earlier entries\. This distinction survives reopening\; it is not merely a temporary screen clear\. **Recorded check\.** The real reset retained identity\, path\, title\, model\, and cwd\; cleared messages\, ordinary queues\, and a synthetic pending tool marker\; and appended one reset boundary\. Reopening rebuilt an empty context after the boundary while full\-history reconstruction retained the earlier fictional messages\. The test also appended one fictional post\-clear message and observed only that message in rebuilt model context\. It did not send a next provider request\. **Failure and recovery\.** `/clear` refuses while streaming or while foreground bash\/Python work is running\. Its controller first aborts active compaction and waits for it to stop\. The warning text does not enumerate every predicate\. If reset throws after beginning\, do not assume nothing changed\. Inspect the journal boundary and active state before retrying\; this reset is not presented as an all\-stage transaction\. **Self\-check\.** Can a later full HTML export still include the conversation from before `/clear`\? **Answer\:** Yes\. Clear is a context boundary\, not an export scrubber\. ### Milestone\: Start a different identity without deleting the old one **Need\.** Eli wants another conversation rather than continuing the fork’s identity\. **Obstacle\.** An empty new journal may not yet exist as a physical file\. **Human OMP slash command\:** ~~~text /new ~~~ **Expected observation\.** OMP starts an empty conversation under a new persistent identity and allocated path\. Ordinary `/new`\: - Preserves the prior journal and workspace\. - Does not create a fork parent link\. - Clears messages and queues\. - Aborts current work after the veto point rather than using the same streaming refusal as `/fresh`\. - Refreshes base\/project prompt context\. - Does not reset the whole installation’s settings\. A new session can contain initial metadata without having a materialized transcript file\. Therefore\, an absent third JSONL file is not evidence that the identity failed to change\. **Recorded check\.** The real new\-session transition allocated another identity and path\, emptied messages and ordinary queues\, and retained the previous journal and workspace\. Its immediate identity was measured directly in the SDK ledger\, not inferred from file count\. **Failure and recovery\.** A before\-switch hook can veto `/new`\. Transient UI may already have been cleared by the controller\, so a changed status area is not proof of a new identity\. Other failures need inspection\; there is no universal rollback promise for this path\. **Self\-check\.** Does ordinary `/new` delete the fork you just left\? **Answer\:** No\. ### Inspect the saved outcome Exit without sending a model prompt\. **Human OMP slash command\:** ~~~text /exit ~~~ Then inspect only the lab’s files\. **Terminal shell — read\-only comparison\, in the same shell holding the receipt variables\:** ~~~sh jq -s 'map(select(.type == "session") | {id,parentSession,cwd,title})' "$SESSIONS"/*.jsonl shasum -a 256 "$SOURCE" jq -s 'map(select(.type == "reset_boundary") | {type,id,parentId})' "$SESSIONS"/*.jsonl jq -s 'map(select(.type == "message") | .message.content)' "$SESSIONS"/*.jsonl cat "$PROJECT/today.txt" ~~~ Look for retained parent history\, a child header linked to the original identity\, a reset boundary in the cleared child\, and retained fictional messages\. These queries aggregate saved journals\. **They do not measure a now\-closed process’s live context\.** Correlate the child header with its recorded parent and the child file path you noted\. Inspect that individual file when you need per\-file evidence\. The original hash is useful evidence\, but do not demand universal byte equality across native startup and shutdown\. Lifecycle records can be added outside the narrower fork call\. The recorded parent\-byte assertion was scoped to that call\. ### Milestone\: Fork from the original at startup **Need\.** Eli wants another identity from a saved conversation without first opening it interactively\. **Obstacle\.** Startup has a launch cwd and no parent process’s ordinary message queues to clone\. Print the supplied startup fork command\: **Terminal shell — print the generated native startup fork command\:** ~~~sh jq -r '.commands.forkExplicitPath' "$RECEIPT" ~~~ Run the entire printed command\. Stop on setup\; do not prompt\. If startup succeeds\, inspect session information and directories\, then exit normally\. This recipe supplies the copied project as launch cwd\. It therefore does not visually demonstrate two different project directories\. The separate parser\/manager check did use a different launch cwd and confirmed the rule\. **Expected observation\.** A new child identity retains source history and records the original persistent ID as parent\. The source remains available\. Session artifacts are copied best\-effort by default\; workspace files are not copied\. **Recorded checks\.** The parser\/manager test confirmed launch\-cwd behavior and rejection of `--fork` with `--no-session`\. The separate source\-CLI startup fork returned a new identity\, two retained fictional messages\, and unchanged workspace bytes\. Source\-ID fork lookup is implemented but was not the exercised startup\-fork target form\; the recorded startup examples used explicit paths\. **Failure and recovery\.** Unknown source IDs fail\. `--fork` with `--no-session` is invalid\. After a write or artifact error\, inspect the child journal and artifact availability before calling the result a complete copy\. **Self\-check\.** Does startup fork inherit queued follow\-up messages from an old OMP process\? **Answer\:** No\. It rebuilds from saved history\, not another process’s queues\. **Source anchors\:** `packages/coding-agent/src/session/agent-session.ts` — `freshSession`\, `resetSessionContext`\, `newSession`\, `sessionId`\; `packages/agent/src/agent.ts` — `reset`\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleFreshCommand`\, `handleResetContextCommand`\, `handleClearCommand`\, `#runNewSessionFlow`\; `packages/coding-agent/src/session/session-context.ts` — `buildSessionContext`\. ## Decision Desk refusals and failures The successful path tells you what an operation is for\. Refusals and partial failures tell you when not to trust a convenient status message\. This chapter uses failure cards\. Do not manufacture a live stream\, run a foreground job\, install a cancelling extension\, or trigger a provider failure for the exercise\. ### Milestone\: Classify the boundary before retrying **Need\.** Eli sees a warning\, a blank\-looking UI region\, or an error after a transition\. **Obstacle\.** “It did not finish normally” does not have one universal meaning\. **Exact action\:** stop submitting work\, identify the operation and failure phase\, then inspect session information\, directories\, retained messages\, and relevant journal files\. | Situation | What the current implementation does | Safe response | | --- | --- | --- | | `/fresh` while streaming | Refuses the refresh\. | Wait or abort normally\, then retry if refreshing provider state is still the goal\. | | Interactive `/fork` while streaming | Controller refuses the fork\. | Do not assume it is queued to run later\. | | `/clear` during streaming or foreground bash\/Python work | Reset method refuses\. | Let work settle or abort it normally\; inspect any file effects separately\. | | `/clear` during compaction | Controller aborts and waits for compaction before attempting reset\. | A later refusal does not mean no maintenance action happened\. | | `/new` | Offers a veto point\, then aborts current work and transitions\. | Do not treat it as a streaming\-guard equivalent\. | | Fork in an in\-memory session | Returns failure\; controller reports “not persisted or cancelled\.” | Use the persistent fictional lab\, not a guessed save flag\. | | Mode\-specific transition restriction | Some modes can block new\/fork transitions\. | Respect the restriction\; do not bypass it to make the workbook pass\. | A refusal at the guarded method’s entry can preserve conversation state while the surrounding controller has already cleared editor text\, stopped a status indicator\, or cancelled maintenance\. **Recorded check\.** Synthetic streaming and foreground predicates exercised the actual guards without running a real stream or foreground executable\. The tested conversation ledger remained unchanged\. **Self\-check\.** Does “wait or abort” mean the refused command will automatically execute after the response ends\? **Answer\:** No\. Inspect the settled state and deliberately retry the intended command\. ### Hooks can veto new\, fork\, and resume An installed extension can return a cancellation result from `session_before_switch` for the reasons `new`\, `fork`\, or `resume`\. You do not need to author a hook to understand the consequence\: - Before\-event cancellation is a legitimate refusal\. - A transient UI clear is not an identity measurement\. - Ordinary queues that survived a veto still belong to the unchanged session\. - A generic fork failure message does not distinguish every cause\. **Recorded check\.** A real SDK extension vetoed fork\, new\, and resume\. Identity\, messages\, journal bytes\, and ordinary steering\/follow\-up queues were preserved in those checks\. The native public lab disables extension discovery\. It is not intended to reproduce that hook scenario interactively\. ### The resume success\-status caveat The supplied `SelectorController.handleResumeSession()` awaits `session.switchSession()` but does not check its boolean result before repainting and reporting success\. Two separate checks establish the relevant boundaries\: 1. A controller test supplied a `false` switch result and observed a `Resumed session` status despite unchanged identity\. 2. The Decision Desk SDK test used a real hook cancellation and verified that underlying session state stayed unchanged\. Those are complementary checks\, not a claim that a physical TUI with a real cancelling hook was exercised end to end\. **Practical rule\:** after a questionable resume\, trust the actual session file\, identity\, and directories—not the success wording alone\. ### A failed switch has phases The resume controller first flushes pending settings\. In the recorded preflight failure\, switching never began\. Inside `AgentSession.switchSession`\, the operation then includes a veto point\, abort\/flush preparation\, a captured local\-state snapshot\, target loading\, context replacement\, restoration of available model\/thinking\/service\-tier information\, and reconciliation\. The guarded target\-load block has rollback handling for many captured local fields\. **Recorded check\.** Failure injected after actual target loading restored prior identity\, messages\, provider\-facing identity\, and ordinary queues\, then rethrew\. Do not extend that result into any of these claims\: - Every failure before the captured snapshot is rolled back\. - Closed physical provider handles are recreated\. - External effects or completed file edits are undone\. - `/new`\, `/fork`\, and `/clear` share the same transaction boundary\. - A mode or prompt\-refresh error always means the session switch was rolled back\. The supplied switch path catches some post\-switch reconciliation and prompt\-refresh errors and logs them without undoing an otherwise committed switch\. The interactive cwd adapter is also a separate layer\. A resumed interrupted conversation can receive a synthetic abort record\. Resume is not a promise that opening and closing every journal is byte\-for\-byte read\-only\. ### Warning only\: drop is not an erasure exercise **Do not run `/drop` in this workbook\.** The inspected command path requests best\-effort deletion of the previous session file and its artifact directory\, then starts a new session\. It has no confirmation dialog in that path\. `AgentSession.newSession({ drop: true })` catches and logs a deletion failure and can still proceed\. The UI can consequently show `Session dropped` after incomplete deletion\. That status does not establish secure erasure\. Forks\, exports\, backups\, temporary sidecars\, clipboard history\, workspace files\, and provider\-held copies may remain\. A session without a file is refused by the drop controller\. Drop was not executed in the supplied proof\. Its warning is source inspection\, not a deletion result\. **Self\-check\.** Which is stronger evidence\: `Session dropped`\, or an appropriately scoped retention\/deletion audit\? **Answer\:** The audit\. The status label is not an erasure receipt\. **Source anchors\:** `packages/coding-agent/src/session/agent-session.ts` — `newSession`\, `fork`\, `switchSession`\, `resetSessionContext`\; `packages/coding-agent/src/modes/controllers/selector-controller.ts` — `handleResumeSession`\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleDropCommand`\, `#runNewSessionFlow`\; `packages/coding-agent/src/slash-commands/builtin-lifecycle.ts` — lifecycle command routes\. ## Review Packet choosing a snapshot Noor needs to understand the fictional Harbor Notes review\, including an earlier draft and the nested checklist review\. The first decision is not “text or HTML\?” It is **which state should the packet represent\?** ### Milestone\: Choose the layer before creating an artifact **Need\.** Produce a reviewable account of the work\. **Obstacle\.** A live\-context dump can omit earlier journal history while including current system and tool context\. A saved\-file export can include earlier history without reconstructing a running agent’s current prompt\. Read the [Review Packet inspection recipe]()\. Keep its interactive examples as reference\; the runnable public packet exercise uses the fictional saved journals\. | Operation | Snapshot source | Output and important limit | | --- | --- | --- | | TUI `/dump` | Current live messages\, current system prompt\, configuration\, and tool inventory | Clipboard text\, plus an attempted temporary JSON sidecar\. Not an all\-journal export\. | | Dump sidecar | Current messages after the session’s LLM conversion boundary\, plus current model\/configuration\, raw prompt\, and wire tool schemas | Persistent temporary JSON file\. Not an exact captured HTTP request\. | | Slash `/export` | Session\-manager header\, all entries\, leaf\, current system prompt\, and tool names\/descriptions | Local HTML\; adjacent nested transcripts included by default\. TUI requests an OS open afterward\. | | Terminal `--export` | Saved journal and adjacent nested transcripts | Local HTML and printed path\. No running `AgentSession` prompt\/tool inventory is reconstructed\. | For valid saved inputs and distinct output paths\, dump and export do not append a “dumped” or “exported” journal entry\. Output creation is still a filesystem effect\. **What changes\?** Choosing the operation determines which data is copied into another artifact\. **What does not change\?** Neither operation is a conversation reset or a disclosure scrub\. **Recorded check\.** The Harbor Notes dump contained current context but not the pre\-clear message\. HTML embedded pre\-clear history\. Live\-state HTML included explicitly fictional current system\/tool metadata\; file\-based HTML did not supply those top\-level live fields\. **Failure and recovery\.** If the chosen snapshot does not contain the required evidence\, choose the correct layer\. Do not solve a missing\-history problem by claiming the live dump is complete\, and do not solve a privacy problem by hiding a viewer panel\. **Self\-check\.** Noor needs the earlier blue\-cover discussion\. Is a post\-clear live dump sufficient\? **Answer\:** Not necessarily\. The saved journal\/full HTML path retains that earlier entry\. ### What dump can contain `AgentSession.formatSessionAsText()` passes current messages to `formatSessionDumpText`\. Depending on what those messages contain\, the text can include\: - System prompt blocks\. - Model and thinking configuration\. - Tool descriptions and parameter information\. - User\, developer\, and assistant messages\. - Stored thinking blocks and tool\-call arguments\. - Tool results\. - Bash and Python execution records\. - Custom\/hook messages\. - File\-mention contents\. - Branch and compaction summaries\. The formatter omits bash\/Python execution records marked `excludeFromContext`\. That omission is specific to this formatting path\. It is not a universal journal or export exclusion policy\. When tool descriptors are already in the system prompt\, the formatter can avoid duplicating the separate tool inventory\. That does not make the information absent from the dump\. Do not reproduce real system instructions\, private dumps\, credentials\, or hidden reasoning in a public workbook or issue packet\. This workbook uses fictional examples precisely so those risks can be taught without publishing them\. ### Milestone\: Account for the sidecar separately **Need\.** Noor wants to know whether the dump produced another file that also needs review\. **Obstacle\.** A clipboard\-oriented command can leave persistent temporary data behind\. The following is a **non\-runnable reference** to the human command\. Do not run it against personal history as a workbook exercise\. ~~~text /dump ~~~ The sidecar filename follows the source’s `omp-llm-request-` naming pattern under the operating system’s temporary directory\. Its fields include\: | Field | Review concern | | --- | --- | | `model` | Model metadata is more than a short display label\. | | `thinkingLevel` | Configuration context\. | | `serviceTier` | Per\-family request configuration\. | | `systemPrompt` | Raw current prompt blocks can contain sensitive context\. | | `tools` | Descriptions and wire schemas can disclose implementation details\. | | `messages` | Converted current messages can contain sensitive content\. | The sidecar is built locally at the conversion boundary\. It is not proof that a provider request occurred\, and it is not necessarily identical to the final provider\-specific payload after all later transformations\. In the TUI\, the command attempts the sidecar first\, appends its path and a raw\-context warning to the text\, then copies that text to the clipboard\. The shared plain\-output builtin returns the text instead of invoking the TUI clipboard path\. **Recorded check\.** Sidecars were written from fictional live and in\-memory sessions\. Injected conversion failure left the plain transcript available\. No clipboard operation occurred in those tests\. **Failure and recovery\.** - Sidecar failure does not suppress the plain transcript\. - The TUI source reports sidecar unavailability\; the plain\-output handler silently omits the failed sidecar path\. - If clipboard copying fails after sidecar creation\, a sidecar may still exist\. - A temporary filename does not mean automatic deletion after the command\. Also\, zero live messages do not guarantee the text `No messages to dump yet.` The current formatter always produces a Configuration section\. The sidecar method explicitly returns no path for zero messages\, but the formatted text can still be nonempty\. **Self\-check\.** Does `--no-session` mean `/dump` cannot leave anything on disk\? **Answer\:** No\. In\-memory conversation formatting can still write a temporary sidecar\. **Source anchors\:** `packages/coding-agent/src/session/agent-session.ts` — `formatSessionAsText`\, `dumpLlmRequestToTmpDir`\, `exportToHtml`\; `packages/coding-agent/src/session/session-dump-format.ts` — `formatSessionDumpText`\; `packages/coding-agent/src/slash-commands/builtin-collaboration.ts` — `dump`\, `export`\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleDumpCommand`\. ## Review Packet local HTML export The runnable packet exercise uses only the downloaded Harbor Notes journals\. It does not require a running model session\. ### Milestone\: Export the fictional saved history **Need\.** Noor wants a local review packet containing the saved history\. **Obstacle\.** Exporting from a running session and exporting from a file have different metadata boundaries\. Prerequisites\: an already installed OMP compatible with this journal format\/export implementation\, a disposable extracted examples directory\, and `jq`\/`shasum` for the inspections below\. No login or provider request is part of this exercise\. Verify the known input before using it\: **Terminal shell — read\-only input check\, from extracted `examples/`\:** ~~~sh jq -s 'map(select(.type == "session") | {id,cwd,title})' review-packet/harbor-review.jsonl shasum -a 256 review-packet/harbor-review.jsonl review-packet/harbor-review/Scout.jsonl review-packet/harbor-review/Scout/Checklist.jsonl ~~~ Use a fresh copy of the examples so the output filename does not replace a useful earlier packet\. **Terminal shell — supplied native local export recipe\:** ~~~sh omp --export review-packet/harbor-review.jsonl review-packet/harbor-review.html ~~~ **Expected observation\.** OMP prints `Exported to: review-packet/harbor-review.html` and writes that local file\. The source handles terminal export before normal session startup\. It opens a manager with breadcrumb suppression\, reads the valid journal\, gathers adjacent nested transcripts\, generates HTML\, and exits\. It does not construct a running `AgentSession`\. The file export does not reconstruct a current live system prompt or tool inventory\. Saved entries themselves can still contain system\, tool\, file\, or other sensitive data\; absence of top\-level live fields is not a privacy guarantee\. **What changes\?** A local HTML output is created\. **What does not change in the checked valid\-input case\?** The journal remains unchanged\; no active conversation is switched\. Repeat the byte inspection\: **Terminal shell — read\-only post\-export comparison\:** ~~~sh shasum -a 256 review-packet/harbor-review.jsonl review-packet/harbor-review/Scout.jsonl review-packet/harbor-review/Scout/Checklist.jsonl ~~~ **Recorded check\.** Valid fictional exports retained journal bytes and embedded the expected older and nested history\. A real source\-CLI export completed successfully\, including a filename containing spaces\. **Failure and recovery\.** If writing fails\, inspect the target path and output before retrying\. Do not assume an automatic retry\, a transactional output\, or a particular missing\-directory creation policy\. Never choose a journal or useful workspace file as the output path\: the implementation writes to the requested output path\. **Self\-check\.** Does creating HTML also publish it through `/share`\? **Answer\:** No\. Local file generation and sharing are separate operations\. ### Milestone\: Keep shell quoting separate from slash parsing **Need\.** Noor wants a filename containing a space\. **Obstacle\.** Terminal shell quoting and human slash\-command parsing are not the same parser\. The supplied terminal recipe preserves the spaced filename as one argument\: **Terminal shell — supplied quoted\-output recipe\, from extracted `examples/`\:** ~~~sh omp --export review-packet/harbor-review.jsonl 'review-packet/harbor review.html' ~~~ **Recorded check\.** The actual source CLI exported successfully to a spaced output filename\. This is not a claim that interactive slash quoting works\. The following table is a **non\-runnable human slash\-command reference**\: | Reference | Current behavior | | --- | --- | | `/export packet.html` | Write local HTML with current live prompt\/tool descriptions and all manager entries\; TUI requests OS opening\. | | `/export --themes packet.html` | Use the selected TUI dark\/light themes rather than the default web palettes\. | | `/export packet.html --themes` | The parser also accepts this ordering\. | | `/export "packet review.html"` | Rejected as multiple whitespace\-delimited path tokens\. Quotes do not preserve the space\. | | `/export one.html two.html` | Rejected with usage\. | | `/export --copy` | Warns to use `/dump`\; no HTML export\. | | `/export copy` or `/export clipboard` | Same copy\-alias warning\. | `parseExportArgs` recognizes `--themes`\, removes that token\, and accepts at most one remaining whitespace\-delimited path\. It does not implement shell expansion\, quote interpretation\, or general option validation\. An unrecognized single token can become a literal filename\. Use a no\-space filename for interactive export\. Do not assume `~` or shell variables will be expanded there\. Terminal `--export` instead consumes its input as a flag value and uses the first positional message as output path\. It does not use `parseExportArgs` or expose the slash command’s `--themes` syntax\. Keep the terminal recipe to its documented input and optional output\. **What changes\?** The terminal recipe creates a second local HTML output\. **What does not change\?** Quoting changes argument grouping\, not snapshot scope or disclosure policy\. **Failure and recovery\.** For an interactive path error\, choose a no\-space path\. Do not switch to `/dump` merely because a warning mentions it unless you also want the dump’s broader current\-state and sidecar behavior\. **Self\-check\.** Why does terminal quoting work while slash quoting fails\? **Answer\:** The shell passes one argv element\; the slash parser splits the command text on whitespace\. ### Persistence and missing\-input limits An in\-memory manager without a session file is rejected by HTML export with\: `Cannot export in-memory session to HTML` A successful dump is not proof that HTML export is available\. For existing saved inputs\, the recorded export path did not mutate the journal\. Do not generalize that into “this command can never create or alter an input file under any path condition\.” `exportFromFile` translates an `ENOENT` that reaches it into `File not found: …`\. But its delegated `SessionManager.open` path also has fresh\-session behavior for empty\/missing explicit files\. The supplied reports did not exercise a missing\-input terminal export\. **Validate the input first\.** Do not use export as a file\-existence test\, and do not promise that every missing\-input case is a harmless not\-found failure\. **Source anchors\:** `packages/coding-agent/src/export/html/args.ts` — `parseExportArgs`\; `packages/coding-agent/src/export/html/index.ts` — `exportSessionToHtml`\, `exportFromFile`\, `buildSessionData`\; `packages/coding-agent/src/main.ts` — `runRootCommand` export fast\-path\; `packages/coding-agent/src/cli/flag-tables.ts` — `--export`\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleExportCommand`\. ## Review Packet reading the whole packet A local HTML file can contain embedded conversation data without being a self\-contained offline viewer\. That distinction was not merely inferred\. The completed browser check found that blocking the export’s CDN scripts left visible controls but **no rendered transcript**\. ### Milestone\: Review offline without assuming the viewer works offline **Need\.** Noor wants to inspect the packet without allowing external requests\. **Obstacle\.** The transcript is embedded\, but two viewer dependencies are external\. The supplied template references\: - `https://cdnjs.cloudflare.com/ajax/libs/marked/15.0.4/marked.min.js` - `https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js` The template also inlines CSS\, viewer JavaScript\, and the generated tool renderer bundle\. Those embedded assets do not remove the two external dependencies\. **Exact action\:** if your browser environment can block external requests\, keep them blocked when opening the fictional HTML\. If you cannot establish that boundary\, use the raw\-file route below instead of calling the preview offline\. **Recorded browser observation\.** With both CDN scripts blocked\, controls such as Auto\, Light\, Dark\, Default\, No\-tools\, User\, Labeled\, and All remained visible\. The transcript did not render\. Do not try to find messages or open Scout in that failed\-render state\. Use the actual fictional journals as the offline fallback\: **Terminal shell — read\-only offline fallback\, from extracted `examples/`\:** ~~~sh cat review-packet/harbor-review.jsonl cat review-packet/harbor-review/Scout.jsonl cat review-packet/harbor-review/Scout/Checklist.jsonl ~~~ Find these fixture markers\: | File | Marker and meaning | | --- | --- | | Parent journal | `PRE-CLEAR-HISTORY`\: the earlier fictional draft used a blue cover\. | | Parent journal | `CURRENT-CONTEXT`\: the current review\-packet request\. | | Scout journal | `SCOUT-TRANSCRIPT`\: the fictional headings inspection\. | | Checklist journal | `CHECKLIST-TRANSCRIPT`\: title\, summary\, and owner\. | The parent contains a saved `reset_boundary` between the earlier and current messages\. **What changes\?** Only your inspection surface\. **What does not change\?** Blocking scripts does not remove embedded data\, and reading raw journals does not mutate them\. **Failure and recovery\.** A blank viewer is an availability problem\, not proof of an empty or sanitized packet\. Stay with text inspection if external code loading is not permitted\. **Self\-check\.** Does “the data is embedded” imply “the viewer works without external scripts”\? **Answer\:** No\. ### Inspect the actual embedded payload when needed For this fictional output\, you can inspect the embedded JSON without executing the HTML\. The following optional command uses the exact session\-data tag emitted by the supplied template\. Publication review executed this filter against a fictional file export\, confirming the parent\, Scout and Checklist data and the absence of top\-level live prompt\/tool fields\. **Terminal shell — optional read\-only payload inspection using `jq`\, from extracted `examples/`\:** ~~~sh jq -eRs ' capture("") | .payload | @base64d | fromjson ' review-packet/harbor-review.html ~~~ This reads a file\, decodes its base64 JSON\, and prints it\. It does not run the embedded scripts or contact the CDN\. Inspect the header\, all entries\, leaf\, and nested sessions—not just a matching phrase\. In this file\-based recipe\, top\-level live `systemPrompt` and `tools` fields should not have been supplied\. The command depends on the current template’s tag spelling\. If it fails or produces no usable payload\, treat that as an inspection failure\, not as proof that no data exists\. A different implementation may require a different approved inspection method\. Base64 is an encoding\, not encryption\. Someone who receives the HTML can recover its embedded data even if the visible viewer does not work\. ### Milestone\: Follow the nested fictional review **Need\.** Noor wants to inspect the checklist work behind the parent’s task result\. **Obstacle\.** The parent’s short result is not the complete nested transcript\. The supplied files use the exporter’s adjacent\-directory convention\: **Non\-runnable reference — supplied fictional disk layout\:** ~~~text review-packet/harbor-review.jsonl review-packet/harbor-review/Scout.jsonl review-packet/harbor-review/Scout/Checklist.jsonl ~~~ Public copies\: - [Harbor Notes parent]() - [Scout transcript]() - [Checklist transcript]() `collectSubSessions` finds these recursively and embeds keys `Scout` and `Scout/Checklist`\. For an optional rendered preview\, make a separate\, explicit decision to allow the two public CDN scripts **for this fictional packet only**\. If you decline\, the raw and decoded JSON routes already provide the review material\. Only after permitting those requests and reloading the fictional HTML\: 1. Find the parent’s current\-context and pre\-clear\-history content\. 2. Open Scout’s agent link\. 3. Open Checklist from within Scout\. 4. Confirm the nested checklist text\. 5. Press Escape to return from Checklist to Scout\. Do not use copy\-link controls in this exercise\. **Recorded browser check\.** Headless Chromium opened Scout and Checklist through keyboard interaction\, displayed the checklist transcript\, and returned to Scout on Escape\. Pre\-clear parent history was visible\. That browser check used a privately generated fictional live\-state export\, with explicitly fictional prompt\/tool metadata\. The runnable file\-export recipe uses the same saved history and nesting convention but does not add that live metadata\. Neither result is a claim about a reader’s browser or a real private session\. **What changes\?** Viewer navigation changes the local displayed transcript\. **What does not change\?** It does not switch a running OMP session or rewrite the saved journal\. **Failure and recovery\.** If a nested link is unavailable\, inspect the raw nested file and the actual payload\. Missing directories\, `.bak` filenames\, and empty\/corrupt journals can be omitted\. Other access errors can fail collection\. Absence from a packet is not proof that no nested work ever existed\. **Self\-check\.** Is the parent’s “Fictional review complete” result enough to establish what Checklist saw\? **Answer\:** No\. Inspect the nested transcript itself\. ### The visible leaf is not the disclosure boundary HTML embeds all manager entries and the leaf identifier\. It can therefore contain more than the currently displayed path\. Before disclosure\, account for\: - Alternative and earlier branches\. - Pre\-clear history\. - Tool inputs and outputs\. - Nested session content\. - Header cwd and additional roots\. - Parent references and other metadata\. - Fields that the viewer does not render\. The export helper removes `previousSessionFiles` from exported headers\. It does not remove every path or identifying field\. Likewise\, a No\-tools filter\, collapsed thinking\, or hidden custom\-message display does not delete embedded content\. Even an All filter is a viewer control\, not a complete field\-by\-field privacy audit\. `includeSubSessions: false` exists as a programmatic `ExportOptions` setting\. It is not a supplied native slash flag\. Do not invent an omit\-nested command option\. **Source anchors\:** `packages/coding-agent/src/export/html/index.ts` — `buildSessionData`\, `sessionHeaderForExport`\, `collectSubSessions`\, `generateHtml`\; `packages/coding-agent/src/export/html/template.html`\; `packages/coding-agent/src/export/html/template.js` — `bootSession`\, sub\-session overlay functions\; `packages/collab-web/src/tool-render/tools/task.tsx` — `taskRenderer`\. ## Sharing is a separate disclosure decision Noor has reviewed a local packet\. That does not automatically authorize uploading it\. This chapter is a decision and evidence exercise\. **Do not execute `/share` as part of the workbook\.** No live upload is needed to learn the boundaries\. ### Milestone\: Identify the route before authorizing disclosure **Need\.** Noor may eventually need a link for an authorized reviewer\. **Obstacle\.** The same human command can use a default encrypted snapshot or a custom executable handler with a different data contract\. **Exact action\:** review the effective sharing settings and whether the active agent directory contains a custom share script\. Then identify what data that route would receive\. Do not invoke sharing to discover its policy\. The supplied settings schema places sharing controls under Interaction \/ Collab\: | Setting | Current default or source | Meaning | | --- | --- | --- | | `share.store` | `blob` | Upload the encrypted snapshot to the share server\. | | `share.serverUrl` | `DEFAULT_SHARE_URL` | Upload\/viewer base\. The accompanying operation document names `https://my.omp.sh/s`\. | | `share.redactSecrets` | `true` | Pass the session’s secret obfuscator to default sharing when available\. | | `secrets.enabled` | `false` | SDK creation only builds the normal secret obfuscator when enabled\. | The defining body of the imported `DEFAULT_SHARE_URL` constant is not included in the source bundle\. Treat the effective installed `share.serverUrl` as authoritative rather than assuming a documented endpoint\. Global settings\, project settings\, explicit overlays\, and runtime overrides can affect effective values\. A value in one config file is not necessarily the current effective value\, especially after a project\-scope change\. **Current default correction\:** GitHub gist is not the default or preferred route in the supplied schema\. `share.store` defaults to `blob`\. There is no supplied `--gist` flag\. ### Default sharing and custom sharing are different contracts | Route | Data contract | | --- | --- | | Default encrypted sharing | Builds a JSON snapshot directly from the manager and optional current agent state\; optionally applies the typed secret\-redaction pass\; compresses and encrypts it\. | | TUI custom handler | Receives the path to an ordinary temporary HTML export\. It is not handed the default encrypted\/redacted snapshot\. | | Shared non\-TUI builtin | Calls default `shareSession` directly\; it does not load the custom TUI share script\. | Default `buildShareSnapshot` calls `buildSessionData`\. **It does not collect adjacent subagent JSONL files\.** The supplied interception check confirmed that omission\. Ordinary HTML export\, including the TUI custom\-handler input\, does collect adjacent nested transcripts by default\. This does not mean default sharing contains no subagent\-derived information\. Parent journal entries can already contain task inputs\, results\, and quoted output\. Default sharing can work for an in\-memory session because it builds the snapshot from the manager’s entries without requiring a session file\. A custom TUI handler still depends on HTML export\, so a manager without a session file can fail before the handler runs\. There is no automatic fallback from that custom path\. **What changes\?** An approved share would create a separate disclosure artifact or handler effect\, not a new conversation identity\. **What does not change\?** The default snapshot does not append sharing entries to the source journal\. Encryption and redaction operate on the outgoing representation\, not as an erasure operation on the original\. **Recorded check\.** Intercepted default sharing encrypted a fictional snapshot\, removed a configured synthetic secret\, retained an unmatched fictional string\, left source entries unchanged\, and did not collect adjacent nested sessions\. **Self\-check\.** Can Noor assume that a custom handler receives the same sanitized data as default sharing\? **Answer\:** No\. It receives ordinary HTML under a separate contract\. ### Redaction is conditional and field\-specific `share.redactSecrets: true` is not a universal privacy guarantee\. The current default\-share path skips its typed redaction pass when there is no obfuscator or the obfuscator reports no configured\/recognized secret handling\. With `secrets.enabled` at its schema default of false\, the normal SDK path does not create that obfuscator\. When active\, the typed pass rewrites selected text\-bearing fields\, including relevant\: - Header title and cwd\. - Current system prompt and tool descriptions\. - Message text\, stored thinking text\, tool\-call arguments\, and error text\. - Tool\-result content and execution output\. - File\-mention paths and contents\. - Summaries\, labels\, and title\-change text\. It drops specified opaque provider replay material and untyped payloads\, such as certain `details`\, `data`\, output schemas\, and compaction preserve data\, rather than attempting a universal recursive scrub\. Important limits remain\: - Unknown or unconfigured strings can survive\. - Image bytes remain intact before the later size\-trimming pass\. - The typed header walk does not rewrite every possible path\-bearing field\. For example\, `additionalDirectories` is not rewritten by `redactShareHeader`\. - IDs\, parent references\, and pseudonymous account\-related metadata can still be identifying or linkable\. - Dropping a metadata field can also remove context a reviewer would otherwise need\. The recorded check confirmed configured\-secret removal\, opaque tool\-result\-details omission\, small\-image preservation\, and complete skipping of redaction with an absent or empty obfuscator\. Local HTML export does not run this share\-redaction pass\. A transcript may already contain some obfuscated content\, but that is not the same as auditing the output artifact\. ### Encryption protects a different boundary Default sharing\: 1. Builds the snapshot\. 2. Applies the configured redaction pass when available\. 3. Gzips the JSON\. 4. Seals it using a fresh AES\-256\-GCM key and a 12\-byte IV\. 5. Uploads the sealed blob\. 6. Returns a viewer URL containing the key in its fragment after `#`\. The recorded intercepted POST URL did not contain the fragment key\. Ordinary HTTP requests do not carry URL fragments automatically\. But **possession of the complete link grants decryption access**\. A recipient can forward it\. Messages\, screenshots\, browser history\, and other places where the complete link is stored can become access\-bearing copies\. Do not turn “the key is in the fragment” into “no client\-side code or recipient can disclose it\.” The viewer is part of the trust boundary\. Encryption is not redaction\, anonymity\, access approval\, or secure deletion\. ### Size trimming is loss\, not privacy review The production sealed\-byte budgets are\: - Share server\: **1\,000\,000 bytes**\. - Gist route\: **5\,000\,000 bytes**\, before base64 expansion\. When a snapshot is too large\, the implementation progressively\: 1. Replaces large inline image payloads and large data URLs\. 2. Caps long strings at lengths of 32\,768\, 8\,192\, 2\,048\, then 512\. 3. Removes oldest entries by repeatedly halving the retained entry list while more than four entries remain\. 4. Throws if the result still cannot fit\. The string caps are implementation string\-length caps\, distinct from the final sealed\-byte budget\. The result reports truncation\, and the command can display a note that large content was trimmed\. Trimming can remove evidence or qualifiers\. It is not a secret detector and does not make surviving content safe\. The recorded trimming tests used a smaller explicit 4\,000\-byte budget\, confirmed image\/text trimming and unchanged originals\, and checked an impossible\-budget error\. They did not upload a production\-size packet\. ### Gist fallback is not custom\-handler fallback Optional `share.store: gist` tries the gist route when `gh` is installed and authenticated\. It stores the sealed blob base64\-encoded as `session.ompshare.txt` in a secret gist\. If `gh` is unusable or gist creation fails\, default sharing can fall back to the share server\. That fallback matters for disclosure policy\: approving one destination is not automatically approving the fallback destination\. **Recorded check\.** A deliberately unauthenticated fake `gh` received only `auth status`\. No gist was created\. The code fell back to one intercepted server POST\. By contrast\, a TUI custom handler is discovered in the active `getAgentDir()` in this order\: 1. `share.ts` 2. `share.js` 3. `share.mjs` The first existing candidate must default\-export the expected function\. The ordinary default location is under `~/.omp/agent`\, but profile\/agent\-directory resolution can change that location\. If loading fails\, the command errors and returns\. If execution throws\, it errors and returns\. **Neither failure falls back to default sharing\.** A custom handler is executable code\, not a declarative upload destination\. Have its policy reviewed by its maintainer rather than assuming the default encryption or redaction settings constrain it\. Its result can be\: - A URL string\. - An object with optional `url` and\/or `message`\. - `undefined`\, which produces a generic shared status\. A generic status is not independent proof that a handler uploaded anything\. ### Milestone\: Interpret cancellation without assuming revocation **Need\.** Noor wants to stop a sharing action\. **Obstacle\.** Restoring the editor and cancelling transport work are different events\. This is a recorded\-boundary exercise\, not an instruction to start an upload and press Escape\. The TUI loader has an abort signal\, but `handleShareCommand` does not pass that signal into default `shareSession` or the custom callback\. The recorded default sequence was\: 1. An intercepted POST began and was held pending\. 2. The real loader handled Escape\. 3. The UI reported `Share cancelled`\. 4. No transport abort signal had been supplied\. 5. The held operation completed afterward\. 6. The late URL was not displayed or opened\. The recorded custom sequence likewise completed a callback effect after Escape\. Its temporary HTML remained while the handler was pending and was removed after settlement\. **What changes on Escape\?** The editor is restored\, the loader is cancelled\, and later result display\/opening is suppressed\. **What does not follow\?** A started upload or custom effect is not necessarily stopped\, undone\, or revoked\. Temporary custom HTML is removed in `finally` after settlement\, with cleanup errors ignored\. A crash or failed cleanup can leave it behind\. “Temporary” is not an erasure guarantee\. **Failure and recovery\.** Treat a cancelled or ambiguous share as possibly completed until the destination is checked through an approved process\. Do not repeat the share merely to recover a missing URL\. Do not use `/clear`\, `/new`\, or `/drop` as upload revocation\. A server error also does not establish that nothing reached the remote system\. The supplied HTTP\-error check observed one intercepted POST and error propagation\, not a universal remote non\-delivery guarantee\. No generic revoke\/delete\-link workflow is established by this evidence\. **Self\-check\.** Noor sees `Share cancelled`\. Is that enough to tell an owner that nothing was uploaded\? **Answer\:** No\. **Source anchors\:** `packages/coding-agent/src/export/share.ts` — `buildShareSnapshot`\, `redactShareHeader`\, `redactShareEntry`\, `redactShareMessage`\, `shareSession`\, `sealToFit`\, `tryCreateGist`\, `uploadToServer`\; `packages/coding-agent/src/export/custom-share.ts` — `getCustomSharePath`\, `loadCustomShare`\; `packages/coding-agent/src/config/settings-schema.ts` — sharing and secrets settings\; `packages/coding-agent/src/sdk.ts` — obfuscator construction\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleShareCommand`\; `packages/tui/src/components/cancellable-loader.ts` — `handleInput`\. ## Operation decision matrix Use this matrix to choose an operation by intent\. “Identity” means persistent journal identity\. None of these conversation\-management operations is a workspace rollback\. Work already performed by tools remains a separate filesystem concern\. | Your need | Operation | Main effect | Boundary to remember | | --- | --- | --- | --- | | Find another conversation while OMP is open | `/resume` | Picker\, then runtime switch if selected | Escape keeps the current session\; inspect identity after questionable status\. | | Reopen a specific native conversation | Terminal `--resume ` | Opens the selected history | IDs and direct paths have different failure and missing\-cwd behavior\. | | Choose at startup | Terminal `--resume` | Startup picker | Cancellation exits startup\; empty folder does not auto\-select all projects\. | | Return to this terminal’s applicable prior history | Terminal `--continue` | Breadcrumb\, recent fallback\, or new empty session | Not always newest\; fresh boundaries and relocation rules matter\. No `/continue`\. | | Explore an alternative from the active conversation | `/fork` | New identity\, parent metadata\, retained conversation and journal entries | Same workspace\; ordinary queues retained\; artifact copy best\-effort\. | | Create an alternative from saved history at launch | Terminal `--fork ` | New identity rooted at launch cwd | No parent\-process queues\; incompatible with `--no-session`\. | | Refresh local provider\-facing state\, keep conversation | `/fresh` | Local handles cleared\; provider\-facing ID rotates | Journal and ordinary queues remain\; no real\-provider repair guarantee\. | | Drop live\/model context\, keep this persistent session | `/clear` | Messages\/queues cleared\; reset boundary appended | Old history\, artifacts\, exports\, and workspace remain\. | | Start a different empty conversation identity | `/new` | New identity\/path and reset conversation | Prior journal retained\; new file may be lazy\; not a settings factory reset\. | | Understand local deletion behavior | `/drop`\, warning only | Best\-effort previous\-journal\/artifact deletion\, then new session | Do not exercise here\; no secure\-erasure guarantee or confirmation in this path\. | | Inspect current live context as text | `/dump` | Clipboard\/plain text plus best\-effort sidecar | Can disclose raw current prompt\/tool\/context data and leave a temporary file\. | | Export current session\-manager history with current metadata | Slash `/export` | Local HTML\; TUI requests OS opening | No\-space slash path\; nested history included\; no share\-redaction pass\. | | Export a valid saved journal without a running agent | Terminal `--export` | File\-based HTML and printed output path | No reconstructed live prompt\/tool inventory\; validate input and output paths\. | | Authorize external disclosure | `/share`\, reference only | Default encrypted snapshot or custom\-handler effect | Route\, redaction\, truncation\, complete\-link possession\, and late completion all matter\. | For export’s valid\-input and missing\-path distinctions\, return to [local HTML export]()\. For upload decisions\, use [Sharing is a separate disclosure decision]()\, not a reset command\. ## Recovery and safe disclosure checklists These are reader checklists\, not automatic session tests\. Checking a box records your own work\; it does not mean a website inspected OMP\, your files\, or a provider\. ### Recovery checklist When selection or transition behavior is uncertain\: - \[ \] **Stop adding work\.** Do not prompt the possibly wrong conversation\. - \[ \] **Identify the operation\.** Resume\, continue\, fork\, fresh\, clear\, and new have different expected effects\. - \[ \] **Check the active session file\.** Do not rely on title or a success toast\. - \[ \] **Check persistent identity separately from provider identity\.** Use the saved session header for durable identity\. - \[ \] **Check directories\.** Inspect the active working directory and additional roots\; distinguish them from an old header cwd\. - \[ \] **Account for queues and jobs\.** Fresh\/fork can retain ordinary queues\; clear\/new discard them\. Cancellation does not reverse completed file effects\. - \[ \] **Inspect the relevant journal\.** A reset boundary explains why old entries remain while current context is empty\. - \[ \] **Treat failure phase as evidence\.** A settings preflight failure\, hook veto\, guarded rollback\, and post\-commit reconciliation error are different outcomes\. - \[ \] **Use an explicit known target for recovery\.** Do not repeatedly try continue and hope recency chooses correctly\. - \[ \] **Preserve useful evidence privately\.** Do not clear or drop merely to make the screen look simpler\. If a persistence error leaves live messages ahead of disk\, do not assume restart will recover those messages\. If you need a diagnostic copy\, treat any dump and sidecar as sensitive and review them locally\. Do not publish a raw dump as a shortcut\. If cwd re\-scoping fails\, do not let tools operate while scope is uncertain\. The parent terminal shell’s directory alone does not prove the OMP process and manager agree\. ### Safe disclosure checklist Before forwarding any real packet outside its current trusted boundary\: - \[ \] **Name the recipient and purpose\.** Include only what that review requires\. - \[ \] **Identify the snapshot source\.** Live dump\, file export\, live export\, default share\, or custom HTML are not interchangeable\. - \[ \] **Inspect older history\.** Include pre\-clear entries and alternative branches in the review scope\. - \[ \] **Inspect all nested content actually embedded\.** Do not stop at the parent’s task summary\. - \[ \] **Inspect header and metadata paths\.** Cwd\, additional roots\, titles\, parent references\, and other identifiers can disclose project or user information\. - \[ \] **Inspect system\/tool data without republishing it blindly\.** Current prompts\, tool descriptions\, schemas\, file mentions\, and opaque metadata require deliberate handling\. - \[ \] **Inspect images and linked content\.** Text redaction does not inspect every pixel or authorize loading every external resource\. - \[ \] **Separate visibility from removal\.** Filters\, collapsed sections\, and blank viewers do not scrub embedded bytes\. - \[ \] **Inventory sidecars and clipboard copies\.** They may outlive the command and the session\. - \[ \] **Check effective sharing configuration and custom\-handler presence\.** Review fallback destinations as well as the preferred destination\. - \[ \] **Treat redaction as assistance\, not approval\.** Unknown strings can survive\; no obfuscator can mean no typed redaction pass\. - \[ \] **Account for truncation\.** A smaller packet may omit crucial evidence without removing sensitive surviving content\. - \[ \] **Protect complete share links\.** The fragment key is access\-bearing\. - \[ \] **Do not interpret cancellation as revocation\.** A started operation may finish after the UI returns\. - \[ \] **Hold the packet if inspection is incomplete\.** An authorized\, manually written summary may be safer than forwarding an unreviewed full artifact\. No live sharing is part of completing this workbook\. ### Finish the three desks You have reached the intended outcome when you can explain these decisions without relying on a status label\: | Situation | Sound conclusion | | --- | --- | | Maya knows yesterday’s full identity\. | Resume that known target and check file plus project scope\. | | Continue returns an empty conversation\. | Investigate breadcrumb\/fresh\-boundary\/history availability\; do not assume deletion\. | | Eli wants a second conversational direction\. | Fork\, while recognizing that workspace files remain shared\. | | Eli wants to retain the conversation but reset local provider state\. | Fresh\; do not claim a remote incident was repaired\. | | Eli wants an empty live conversation under the same persistent ID\. | Clear\; retained journal history still needs export review\. | | Noor needs the earlier Harbor Notes discussion\. | Inspect saved\/full history\, not only post\-clear live messages\. | | Noor’s blocked\-CDN HTML shows only controls\. | Use raw or decoded data inspection\; the viewer is not self\-contained offline\. | | A sharing loader says cancelled\. | Treat upload\/handler completion as unresolved\, not revoked\. | ### Clean up only owned exercise material `LAB` identifies the newly created temporary lab\. `RECEIPT` identifies a separate temporary JSON receipt\. When finished\, remove only the exact exercise paths you own and no longer need\. The generated Review Packet HTML belongs to your disposable downloaded examples copy\. No automated cleanup command is supplied that could be mistaken for a real\-session deletion instruction\. Do not use `/drop` as workbook cleanup\, and do not describe ordinary file removal as secure erasure\. ## Evidence and limitations This edition is grounded in supplied implementation bodies\, public fictional fixtures\, completed isolated reports\, and a completed browser report\. No new commands or live checks were run to author this manuscript\. The evidence supports specific behavior in a particular source snapshot\. It does not establish compatibility with every installed release\. ### Supplied implementation inspection The main source responsibilities are\: | Concern | Supplied paths and symbols | | --- | --- | | Persistent identity\, journal operations\, lazy files\, artifacts\, continuation | `packages/coding-agent/src/session/session-manager.ts` — `SessionManager.open`\, `fork`\, `forkFrom`\, `newSession`\, `moveTo`\, `continueRecent`\, `copySessionArtifacts` | | Identifier resolution and listing | `packages/coding-agent/src/session/session-listing.ts` — `resolveResumableSession`\, `sessionMatchesResumeArg`\, `findMostRecentSession` | | Breadcrumbs and terminal identity | `packages/coding-agent/src/session/session-paths.ts`\; `packages/tui/src/ttyid.ts` — `getTerminalId` | | Startup routing | `packages/coding-agent/src/main.ts` — `createSessionManager`\, `runRootCommand`\, missing\-cwd and project\-switch helpers\; `packages/coding-agent/src/cli/args.ts`\; `packages/coding-agent/src/cli/flag-tables.ts` | | Runtime reset and transition behavior | `packages/coding-agent/src/session/agent-session.ts` — `freshSession`\, `resetSessionContext`\, `newSession`\, `fork`\, `switchSession` | | Context versus retained history | `packages/coding-agent/src/session/session-context.ts` — `buildSessionContext`\; `packages/coding-agent/src/session/session-entries.ts` — `ResetBoundaryEntry` | | Human command routing and UI caveats | `packages/coding-agent/src/slash-commands/builtin-lifecycle.ts`\, `builtin-session.ts`\, `builtin-collaboration.ts`\; `packages/coding-agent/src/modes/controllers/command-controller.ts`\, `selector-controller.ts` | | Dumps and exports | `packages/coding-agent/src/session/session-dump-format.ts`\; `packages/coding-agent/src/export/html/args.ts`\, `index.ts`\, `template.html`\, `template.js` | | Sharing\, conditional redaction\, handlers\, cancellation | `packages/coding-agent/src/export/share.ts`\, `custom-share.ts`\; `packages/coding-agent/src/config/settings-schema.ts`\; `packages/coding-agent/src/secrets/obfuscator.ts`\; `packages/tui/src/components/cancellable-loader.ts` | | Startup\/provider boundaries | `packages/coding-agent/src/sdk.ts`\; `packages/coding-agent/src/config/model-registry.ts`\, `model-provider-discovery.ts` | Implementation bodies and recorded outcomes take precedence over stale descriptions\. In particular\, this workbook does not adopt the older implications that\: - `/fork` opens a previous\-message picker\. - GitHub gist is the default share route\. - Embedded HTML data guarantees an offline viewer\. - A dump necessarily contains all retained journal history\. - Every explicit missing path is a guaranteed not\-found failure\. - Every “session ID” is the persistent journal ID\. ### Completed recorded checks The supplied coverage summary reports **38 passing checks** across three suites\: | Suite | Recorded coverage | Important qualification | | --- | --- | --- | | Return Desk — 11 checks | Identity\/history\/cwd retention\, local\/global lookup\, unknown IDs\, no\-session manager precedence\, breadcrumb priority and fallback\, missing\-cwd decisions\, selector behavior\, public helper\, and source\-CLI resume\/continue\/fork | Most checks use manager\/component\/controller seams\. Native startup used RPC read\-only inspection and private disabled\-provider policy\, not a physical TUI\. | | Decision Desk — 11 checks | Real SDK\/registry\/controller fork\, fresh\, clear\, new\, queue retention\/removal\, synthetic guards\, in\-memory fork refusal\, real extension veto\, injected switch rollback\, artifact success\/failure\, command inventory | Provider handles were inert\; busy predicates were synthetic\; artifact coverage was narrow\. Drop was not executed\. | | Review Packet — 16 checks | Live versus file snapshots\, nested history\, path parsing\, source\-CLI export\, sidecars and failure\, in\-memory limits\, intercepted encrypted sharing\, conditional redaction\, trimming\, gist fallback\, server error\, custom handlers\, and late completion after Escape | No real upload or clipboard operation\. Share transport was intercepted\, and `gh` was a deliberately unauthenticated fake\. | All three final launch reports recorded successful exit without timeout\. The native continuity check ran the real source CLI with only state\/message inspection and stdin EOF shutdown\. Resume and continue returned the intended fictional identity\; fork returned another identity\; each retained two fictional messages and unchanged workspace bytes\. Its network\-attempt records were empty under the private restrictions\. The supplied coverage summary also reports a passing public `bun check` and no remaining blockers in the preceding review\. That summary is not a new verification of this manuscript\, a website build\, or an installed distribution\. Publication review also independently checked the complete manuscript with no remaining blockers and executed its added receipt\-capture\, JSON inspection\, checksum and embedded\-payload decoder commands on owned fictional copies\. The reset\-inspection queries were syntax\-checked against initial copied journals\; the actual reset behavior is established by the separate SDK checks above\, not by those queries\. ### Completed browser evidence The separate headless Chromium report reviewed a generated fictional Harbor Notes packet\, including its decoded parent\, Scout\, Checklist\, and explicitly fictional current prompt\/tool metadata\. It recorded\: - **Blocked CDN scripts\:** visible controls\, no rendered transcript\. - **Allowed CDN scripts\:** visible pre\-clear history\, keyboard navigation into Scout and Checklist\, and Escape returning to Scout\. This establishes the tested viewer behavior\. It does not establish a self\-contained offline viewer\, a physical desktop\-open result\, or clipboard behavior\. The generated proof exports remain private artifacts\; this workbook links only the supplied public fixtures and recipes\. ### What remains unverified Material limitations remain explicit\: - **Physical TUI behavior\:** full installed interactive startup\, terminal rendering\, picker exit presentation\, and platform\-specific input behavior were not physically tested\. - **Real providers\:** no inference\, authentication recovery\, transport repair\, remote deletion\, or provider\-cache outcome was established\. - **Concurrency\:** real streaming cancellation\, hidden\-turn scheduling\, async\-job races\, and compaction timing were not exercised by the synthetic guard checks\. - **Universal rollback\:** the switch\-failure injection covered the guarded target\-load block\, not every preflight\, post\-commit\, external\, or filesystem effect\. - **Filesystem breadth\:** one successful artifact file and one blocked destination do not establish symlink\, huge\-tree\, cross\-device\, permission\, or power\-loss guarantees\. - **Missing export inputs\:** the reports checked valid input journals\, not every empty\/missing\-path behavior delegated through the loader\. - **Clipboard and OS opening\:** controller open requests were intercepted\; TUI dump clipboard delivery and real desktop opening were not performed\. - **Live sharing\:** no actual share server or GitHub publication\, viewer decryption service\, revocation\, expiry\, or retention policy was verified\. - **Redaction completeness\:** configured synthetic cases do not prove that arbitrary real secrets\, personal information\, image content\, or extension metadata will be removed\. - **Implementation identity\:** the supplied inventory fingerprints source files\, but no exact release\/commit mapping establishes what a reader’s installed OMP contains\. Session format version 3 is not itself a product\-release promise\. - **Delegated code\:** some loader\/storage\/provider helpers and the generated tool\-view bundle were not included as implementation bodies\. Named repository tests were not supplied as executed test logs\. - **Reader state\:** no workbook page\, checklist\, or fixture inspection establishes what is active in a reader’s actual OMP process\. When installed behavior differs\, preserve that difference as an observation and stop the affected exercise\. Do not turn an expectation into a passed check\. The durable habit is the same across all three stories\: **choose conversations by identity\, choose resets by state boundary\, and choose disclosure by inspected content—not by the appearance of the screen\.** ## Sessions\, resets\, and reviewable history\: next steps You can now ask for a precise continuity operation instead of an unspecified reset\. You can also explain why a cleared live transcript can coexist with retained history and an export containing earlier material\. That still leaves another question\: **what knowledge can return without reopening that journal\?** A separate memory backend\, a managed skill\, or applicable project guidance is not erased merely because conversation messages were cleared\. Continue to [Memory and reusable knowledge]()\. Keep the ledger beside the next part’s four\-place model\: one describes session and output boundaries\; the other describes where useful knowledge can live\. Their relationship is developed in [An empty context is not an empty history or memory store]()\. ## Memory and reusable knowledge Continuity preserves access to a conversation\. Memory supports a different need\: retrieving useful evidence when that conversation is no longer the active one\. A stored preference\, a recalled excerpt\, and a managed skill are not three names for the same object\. Nor does storing something guarantee that the next relevant query will retrieve it\. This part teaches a checkable loop\: identify the evidence\, understand its scope\, inspect complete content before correction\, and verify the relevant outcome\. ### Read the configuration as a snapshot The source teaches a sanitized Mnemopi configuration dated 28 August 2026\, with a configuration record at 00\:01 UTC the following day\. Its tables distinguish persisted global overrides from resolved defaults\. They do not establish the health of a database\, embedding worker\, provider\, or currently running session\. Mnemopi is the selected backend in that snapshot\. The native `local` backend and Hindsight are alternatives\, not extra active layers that should be added to the explanation\. The recorded `per-project` scope derives from resolved cwd\, not Git root\. A session relocation or a launch from a subdirectory can therefore require a fresh scope investigation\; retaining a conversation identity does not establish an unchanged memory bank\. Read [the complete configuration]() before treating a threshold\, budget\, or automation switch as applicable elsewhere\. ### Use the complete fictional lab The [local Memory lab]() retains all five Cedar stories\: deliberate preference retention\, decision recall\, reflection\, exact\-row correction\, and turning a verified technique into a lesson or skill\. Its selectable three\-stage illustration\, copy controls\, disclosures\, and lesson ticks remain interactive\. Selecting the durable\-fact stage does not store a fact\. Selecting later recall does not search a database\. The lab’s `window.memoryTutorial` interface exists on that page only and operates tutorial state\. Use the [Memory browser\-interface chapter]() for that interface\, not the unified site’s control contract\. The original lab’s default\-location examples for managed skills are not universal active\-profile paths\. The manuscript explains their location under the active agent configuration directory\. Keep the default path illustration separate from your actual resolved configuration\. ### Three boundaries to carry forward First\, `/memory view` shows injected instructions and cached recalled text\, not a database inventory or a new search\. Second\, a retain acknowledgement is not sufficient proof of a successful write\, and a clipped preview is not enough content for a replacement edit\. Third\, local SQLite and local embeddings do not establish offline processing\: the recorded online memory\-model setting permits additional model use\, and recalled content enters the main model’s context\. Do not confuse `/clear` with `/memory clear` or `/memory reset`\. The former is a live\-context reset that retains journal history\; the latter commands request broad scoped memory\-file deletion in the recorded controller and are warning\-only here\. Neither is a universal erasure mechanism\. Finally\, when this source says to start a fresh session after startup\-related configuration changes\, do not silently substitute the `/fresh` command\. Continuity established that `/fresh` refreshes local provider\-facing state\; it is not a general backend or tool\-reload recipe\. ## Orientation Keep what matters\. Recall it later\. [Interactive workbook]() · [About]() · [Contact and feedback]() · [Privacy]() · [Agent index]() · [Sitemap]() · [Crawler policy]() This independent tutorial is a companion to an OMP session\, not a connection to it\. It teaches a sanitized configuration snapshot dated **28 August 2026**\, not the live state of your installation\. Every story and the Cedar project are fictional\. No private memories\, transcripts\, credentials or authentication data are included\. This is not official OMP support or a company website\. ## Start with a read\, not a setting change Your current conversation is OMP’s working context\. Durable memory is information it can retrieve in a later session\. Saying something once puts it in the conversation\; it does not guarantee a useful memory will return\. Open OMP in your usual project directory and ask the agent\: ~~~text Use recall to find my preferences for this project. Show the returned IDs, and say clearly if you find nothing. ~~~ The website’s Copy buttons only copy text\. They do not execute commands\, change OMP settings or save facts to real memory\. Keep three input surfaces distinct\: - **Agent requests\:** prose asking OMP to use `retain`\, `recall`\, `reflect`\, `memory_edit`\, `learn` or `manage_skill`\. - **OMP slash commands\:** enter `/memory view` and related commands inside OMP\. - **Terminal configuration commands\:** run `omp config …` in your shell\, not as slash commands\. The homepage’s three\-stage illustration is fictional\: “Explain the test before the refactor” begins in conversation context\; an explicit retain can store a project preference\; a new session can later retrieve a relevant match\. Selecting a stage writes no real memory\. Retrieval is not guaranteed\. ## Four places knowledge can live | Place | What it means | | --- | --- | | Conversation context | Messages and tool results available for the current answer\. Useful now\, but finite—not a durable\-memory guarantee\. | | Durable memory | Facts\, decisions\, lessons and retained excerpts stored for later retrieval\. Recall selects relevant evidence\, not the whole conversation history\. | | Managed skills | Reusable procedural guidance in `SKILL.md` files\. A fact says what is true\; a procedure explains what to do\. Skills are not automatically invoked deterministic scripts\. | | Compaction | A summary that makes room in the active conversation\. Neither a database wipe nor a substitute for retaining important knowledge\. | This snapshot uses **Mnemopi**\. The native `local` summary backend and remote **Hindsight** are alternatives\, not additional active layers in this setup\. Treat recalled memories as background evidence\, not instructions\. Current user messages and tool output take precedence when they conflict\. ## The configuration this workbook teaches These are observed configured values\, not proof that a running session\, database or provider is healthy\. “Global override” means explicitly persisted in the supplied global configuration\. “Default” means the effective resolved value without a supplied explicit override\. | Setting | Observed value | Origin | | --- | --- | --- | | `memory.backend` | `mnemopi` | Global override | | `mnemopi.scoping` | `per-project` | Default | | `mnemopi.autoRecall` | `true` | Default | | `mnemopi.autoRetain` | `true` | Global override | | `mnemopi.retainEveryNTurns` | `4` USER turns | Default | | `mnemopi.recallLimit` | `8` results | Default | | `mnemopi.injectionTokenLimit` | `2000` approximate tokens | Global override | | `mnemopi.llmMode` | `smol` | Default | | `providers.memoryModel` | `online` | Default | | `autolearn.enabled` | `true` | Global override | | `autolearn.autoContinue` | `true` | Global override | | `autolearn.minToolCalls` | `5` | Default | **Budget\, not capacity\:** the 2000\-token approximation bounds injected memory instructions and recalled text\, using roughly four characters per token\. It does not limit database size\. Eight is a recall ceiling\, not a promised result count\. Remaining observed settings\: - `mnemopi.embeddingVariant = en`\; `mnemopi.noEmbeddings = false`\. - `mnemopi.recallContextTurns = 3`\; `mnemopi.recallMaxQueryChars = 4000`\. - `mnemopi.polyphonicRecall`\, `mnemopi.enhancedRecall`\, `mnemopi.proactiveLinking` and `mnemopi.debug` are `false`\. - `compaction.enabled = true`\. - No supplied database\-path\, bank\, embedding\-model or endpoint overrides\. No Mnemopi environment variables were observed in the supplied parent environment\; other sessions can differ\. ## Five fictional lab stories Adapt these prompts to non\-sensitive facts in your own work\. They are requests to the agent\, not slash commands\. The stories illustrate checks to perform\, not observed runtime results\. ### 1\. Save a preference deliberately **Fictional situation\:** Cedar’s maintainer keeps asking for a small testable change before a wider refactor\. Ask OMP\: ~~~text Use retain to remember this project preference: explain the smallest testable change before proposing a wider refactor. Then use recall to find it and show its exact ID. ~~~ `retain` requests a save immediately\; it does not wait for the four\-turn batch\. A preference saved here is project\-scoped\, not automatically universal\. **Check\:** recall returns the intended preference and an ID\. Try again in a fresh session from the same directory\. **Pitfall\:** the retain acknowledgement counts requested items\. It alone is not proof of a successful write\. ### 2\. Resume the reason\, not just the task **Fictional situation\:** a new session starts after Cedar’s queue\-design discussion\. You remember the decision\, but not its constraints\. Ask OMP\: ~~~text Use recall to find Cedar's durable job-queue decision, rejected alternatives and migration constraints. Show the returned IDs. Separate saved evidence from assumptions before proposing next steps. ~~~ The first prompt can trigger automatic recall\. Ask for on\-demand `recall` later when the topic changes\. **Check\:** look for the decision’s rationale\, source and date—not merely a confident summary\. **Pitfall\:** “No relevant memories found” does not mean the entire store is empty\. Try specific project and decision terms\. ### 3\. Connect related lessons **Fictional situation\:** Cedar has several retry and timeout decisions\. You want the pattern\, including disagreements\. Ask OMP\: ~~~text Use reflect to examine Cedar's retry and timeout decisions. Compare their tradeoffs; distinguish agreement, conflict and missing evidence. Use recall for IDs when checking a source. ~~~ Here\, `reflect` retrieves and formats scoped memories for the agent to synthesize\. It is not a separate guaranteed reasoning service or an exhaustive database audit\. **Check\:** the answer distinguishes retrieved evidence from the agent’s interpretation\. **Pitfall\:** a fluent synthesis can still omit relevant memories\. The recall limit still applies\. ### 4\. Correct the row\, not the preview **Fictional situation\:** Cedar’s agreed retry limit changed from three to five\. An old memory still says three\. Begin with inspection\, without editing\: ~~~text Recall Cedar's retry-limit decision and show exact IDs. Read each candidate's memory:// address in full, including its bank and store. Do not edit yet. Identify the row that says three retries. ~~~ Ask OMP to read `memory://` followed by an **exact returned ID**\. That is OMP’s internal resource address\, not an HTTP endpoint on this website\. It reveals full content and metadata\; a recall preview can be clipped\. After selecting the working\-store row\, ask\: ~~~text Use memory_edit update on the exact working-store ID we just selected. Replace only the three-retry rule with five retries, preserving the rest of its full content. Read back that same ID, then recall the topic again. ~~~ Store rules in this snapshot\: - `update` and `forget` operate on working rows\. To remove an unwanted row\, ask OMP to forget the exact selected ID\. - `invalidate` supports working or episodic rows\. Ask OMP to invalidate the selected ID\, optionally linking a verified replacement ID\. - Extracted `fact` projections are read\-only\: expect `not_editable`\, not an edit\. **Check\:** inspect the operation’s returned status\, bank and store\. Verify the full row and related recall results afterward\. **Pitfall\:** an update replaces content wholesale\. Never reconstruct it from a clipped preview\. Episodic update\/forget can report `not_found`\; stale copies may remain elsewhere\. Forgetting one eligible row is not universal erasure\. ### 5\. Turn a verified fix into a technique **Fictional situation\:** a duplicate\-delivery test failed before Cedar’s fix and passed afterward\. Now there is a lesson worth keeping\. Ask OMP\: ~~~text We verified Cedar's duplicate-delivery fix with a failing test before the fix and a passing rerun afterward. Use learn to capture the cause, fix, limits and verification. If the steps generalize, also create a managed skill named webhook-replay-check with prerequisites, steps and failure checks. Exclude credentials. ~~~ `learn` stores a lesson and can also write a skill\. `manage_skill` creates\, updates or deletes managed skills separately\. Generated files live in the `managed-skills` directory under OMP’s agent configuration directory\, separate from authored `skills`\; authored names take precedence\. **Check\:** recall the lesson and inspect `managed-skills/webhook-replay-check/SKILL.md` under that configuration directory\. If discovery lags\, start a fresh session\. **Pitfall\:** verify your own technique first\. Skill creation can fail after the lesson is saved\; check both outcomes\. The example’s claimed before\/after test evidence is fictional\, not evidence for your project\. ## The automatic lifecycle 1. **First turn\:** automatic recall uses the first non\-empty prompt and recent context\. It is **not a new search every turn**\; later prompt rebuilds can reuse the cached snippet\. Request recall when needed\. 2. **Four USER turns\:** at agent\-end\, automatic retention checks for at least four new user turns since the retention cursor\. It batches the unretained suffix—not four assistant replies or tool calls\. 3. **Before compaction\:** a fresh recall supplies additional context to the compaction summary\. This is distinct from the first\-turn recall gate\. 4. **On shutdown\:** best\-effort disposal retains the remaining transcript and drains pending extraction\, skipping fresh extraction and full consolidation\. Shutdown deadlines can interrupt completion\. ### A separate loop\: auto\-learn With both autolearn switches on\, an eligible completed top\-level turn with **at least five tool calls** can trigger an extra private capture turn\. Counts do not accumulate across prompts\. Aborted turns\, plan mode and goal\-mode turns are skipped\. This adds model use\; it is not `autoRetain` and does not run after every prompt\. ## The command desk Enter these slash commands inside OMP\. Nothing on this website executes them\. | Command | Meaning and limits | | --- | --- | | `/memory view` | Shows the injected payload\: instructions plus cached recalled text\, not the whole database or a fresh search\. | | `/memory stats` | Shows scoped bank counts\, working\/episodic memory\, triples and database locations\. Use it to understand scope\. | | `/memory diagnose` | Inspects scoped database diagnostics and integrity findings\. Does not establish provider authentication or embedding availability\. | | `/memory enqueue` | **Mutates memory\.** Alias\: `/memory rebuild`\. Retains the remainder\, flushes extraction and requests full\, age\-gated cross\-session consolidation—not an index\-only rebuild\. An “enqueued” banner is not proof of success\; check diagnostics and recall afterward\. | ### Destructive warning\: clear is a wipe\, not a refresh `/memory clear` and `/memory reset` delete all currently scoped database files and sidecars\, including rescued legacy banks and shared\/base databases when present—even beyond ordinary per\-project recall\. **The controller described in this snapshot has no confirmation\.** Inspect scope and backups first\. Removal can fail\; a success banner does not prove erasure\. `/memory mm` is Hindsight\-only\, not a Mnemopi command workflow\. ### Optional configuration changes—not applied by this tutorial Use your shell\, not OMP’s prompt\. Read a value first\: ~~~sh omp config get mnemopi.autoRetain --json ~~~ Choose individual changes deliberately\; this is not a script to run wholesale\. | Goal | Shell command | Caveat | | --- | --- | --- | | Pause periodic retention only | `omp config set mnemopi.autoRetain false` | Not a complete privacy switch\; other save paths remain\. | | Skip extra capture turns | `omp config set autolearn.autoContinue false` | Standing auto\-learn guidance remains\. | | Disable the active memory backend | `omp config set memory.backend off` | Does not delete existing data\. | | Disable auto\-learn separately | `omp config set autolearn.enabled false` | Also disables its generated\-skill tools on fresh startup\. | Read back changed keys with `omp config get` and `--json`\. Start a fresh OMP session after changes affecting startup tools or the backend\. ## Privacy and costs ### In a real OMP session Mnemopi uses local SQLite and local embedding execution\. Initial embedding\-model downloads may use the network\. With `providers.memoryModel = online`\, retained user excerpts can reach the tiny\/smol role for fact extraction\, and consolidation can use that online model too\. The snapshot’s configured global smol role is `google-antigravity/gemini-3.7-flash:medium`\, with no TINY override\. Actual runtime model resolution and authentication were not exercised\. Recalled memories also enter the main model’s context\. Budget for extraction\, consolidation and extra capture turns\; do not assume zero egress or guaranteed encryption\. **Automation switches are separate\.** Turning `autoRetain` off gates periodic batches—not explicit saves\, `learn`\, enqueue or shutdown retention\. Setting `memory.backend` to `off` disables the active backend\, but does not delete data or stop normal main\-model conversation\/session persistence\. Disable autolearn separately for generated skills\. **Forgetting is not universal erasure\.** An eligible row can be deleted without erasing transcripts\, backups\, provider copies\, skills or every derivative\. Keep secrets out of memory\; verify corrections instead of assuming all copies disappeared\. ### On this website The interactive homepage stores only self\-reported checklist flags in the browser’s localStorage key `omp-memory-workbook:checklist:v1`\. Reset lesson ticks removes that key\; it does not touch OMP data\. Storage can fail\, and saved status is the last local observation\, not a multi\-tab guarantee\. Copy controls attempt to write a displayed prompt or command to the clipboard\; manual selection is the fallback\. They do not read your clipboard or execute the copied text\. Fonts are self\-hosted\. The tutorial script makes no network requests\, but loading public pages and fonts requires delivery through here\.now and the read\-only Cloudflare delivery layer\. That layer does not add a tutorial datastore\. This workbook does not establish what access logs the hosting providers keep or who can access them\. No account\, authentication\, payment or local OMP connection is offered\. See the [privacy explanation]() for the distinction between site behavior and real memory processing\. ## Troubleshooting ### Different session\, different results\? Check the directory and bank first\. `per-project` derives its bank from **resolved cwd\, not git root**\. Subdirectories and moved projects can differ\. Same\-cwd legacy rescue may add recall banks\. Compare scoped stats and diagnostics\. ### Rows exist\, but the payload lacks them\? `/memory view` shows current injection\, not stored coverage\. Ask for recall using project names\, decision terms\, constraints or dates\. An empty search differs from a backend\-unavailable error\. ### A recent conversation was not retained\? Count new USER turns against the four\-turn threshold\. For an important fact\, request explicit retain and verify retrieval\. Do not depend on shutdown finishing\. ### Settings say “on\,” but tools or recall fail\? Persisted settings can differ from running state\. Start a fresh session\. Check `/memory diagnose`\, then embedding download\/worker availability and memory\-model availability\. Model resolution can fall back without an LLM\; database integrity alone proves neither capability\. ### An old answer keeps coming back\? Inspect exact IDs\, banks and stores\. Check duplicates\, rescued banks\, read\-only fact projections and cached injection\. State the current correction explicitly\; current user\/tool evidence wins\. Re\-read and recall after editing rather than deleting vaguely matching rows\. ## Your checkpoint Mark these only after your own checks\. Homepage ticks are self\-reported lesson progress\, not OMP verification or real memory state\. - \[ \] I can distinguish context\, memory and skills\. - \[ \] I saved a non\-sensitive fact and recalled its ID in a new session\. - \[ \] I inspected full content before choosing an edit\. - \[ \] I checked my bank scope and understand the automation switches\. The homepage is readable without JavaScript\. Without it\, select prompt text manually\; the illustration remains readable and lesson ticks cannot be saved\. ## Browser agent interface ### When to use—and when not to Use the interface to read authored chapters\, navigate the workbook\, select the fictional illustration\, open disclosures\, inspect tutorial state or operate an explicitly requested local lesson checklist\. Do not use it to search\, save\, correct or erase actual OMP memories\, run terminal commands\, authenticate to OMP or establish database health\. No REST endpoint or MCP service is provided by this site\. Open the [canonical homepage]() in a JavaScript\-capable browser and evaluate in the **page’s main JavaScript world**\. The API is `window.memoryTutorial`\, version 1\. A fetch\-only document reader\, an isolated extension world or a support page does not expose this object\. If it is absent\, use the authored Markdown for reading\; do not invent a network API\. Call `discover()` for the live schemas\, permissions\, exact control IDs\, enabled states and gaps\. These schemas\, not guesses from visible labels\, define the currently loaded page’s interface\. | Operation | Input | Result | | --- | --- | --- | | `discover()` | None | Scope\, permissions\, schemas\, controls and gaps\. | | `inspect()` | None | Authoritative page revision\, content revision\, current chapter\, illustration\, checklist\/storage\, clipboard\, disclosures and stable controls\. | | `query({text, limit})` | Text of at most 240 characters\; optional integer limit 1–10\, default 5\. | Searches authored chapter text\, including closed disclosures\, never memories\. Status is `matched`\, `empty` or `empty-query`\; unavailable content is a structured failure\. | | `act({id, action, expectedRevision, …})` | Exact registered control ID\, supported action and a fresh revision\. | `performed` or `unchanged`\, `changed`\, current revision and optional clipboard outcome\. | | `wait({afterRevision, timeoutMs, match})` | Existing revision from this document\; optional integer 0–5000 milliseconds\, default 1500\; optional `match` with `chapterId` and\/or `demoStep` \(1\, 2 or 3\)\. | `matched` only after a newer revision satisfying every supplied condition\, otherwise `timed-out`\; includes current revision and state\. | | `diagnose()` | None | Tutorial runtime\, storage\, clipboard capabilities and control integrity—not OMP health\. | `query()` matches all whitespace\-separated search terms case\-insensitively within a chapter\. Results have a chapter ID\, title\, anchor\, navigation control ID and excerpt\. A chapter excerpt is not the full source text\. ### Read\, act\, observe Run this JavaScript in the homepage’s main world\. It selects only a fictional stage\: ~~~js const t = window.memoryTutorial; const capabilities = t.discover(); const chapters = t.query({ text: "compaction", limit: 3 }); const before = t.inspect(); const result = await t.act({ id: "demo-recall", action: "click", expectedRevision: before.revision }); const observed = result.ok && result.changed ? await t.wait({ afterRevision: before.revision, timeoutMs: 1000, match: { demoStep: 3 } }) : t.inspect(); const diagnostics = t.diagnose(); ~~~ An already selected stage or another unchanged action does not guarantee a newer revision\. Do not interpret a wait timeout as a successful transition\, or a successful stage selection as a successful real memory operation\. ### Action shapes and revision rules - Use `action: "click"` for a discovered click control\, such as a navigation\, illustration\, copy or reset control\. - Use `action: "setChecked"` with a boolean `checked` only for a checkbox control\. This changes self\-reported local progress\, not verified OMP state\. Do not tick it without the reader’s actual completion or explicit request\. - Use `action: "setOpen"` with a boolean `open` only for a disclosure’s **summary control ID**\, such as `settings-extra-toggle`\, not its containing details ID\. - Supply `checked` only for `setChecked`\, and `open` only for `setOpen`\. Extra or unsupported fields are rejected\. - Inspect immediately before every action\. Pass that response’s opaque `revision` as `expectedRevision`\; do not use `contentRevision` or manufacture a token\. - Revisions expire on reload\. User actions\, scrolling and asynchronous clipboard results can change them\. On `STALE_REVISION`\, inspect again and reassess the intended action\. - Honor `enabled` and `unavailableReason`\. Disabled\, hidden\, inert or closed\-disclosure targets are not actionable\. Open the appropriate discovered disclosure first\, then inspect again\. Never bypass a disabled control by editing the DOM\. - Actions use the same native click\/change paths as human controls\. A structured success is not permission to claim unobserved effects\. For example\, open the configuration disclosure without changing a setting\: ~~~js const t = window.memoryTutorial; const before = t.inspect(); await t.act({ id: "config-options-toggle", action: "setOpen", open: true, expectedRevision: before.revision }); ~~~ ### Failures and boundaries Failures use `{ok:false, error:{code,message}}`\, with revision\/scope metadata and optional details\. The discovery schema lists `INVALID_ARGUMENT`\, `STALE_REVISION`\, `STALE_DOCUMENT`\, `INVALID_REVISION`\, `UNKNOWN_TARGET`\, `AMBIGUOUS_TARGET`\, `DISABLED_TARGET`\, `UNSUPPORTED_ACTION`\, `ACTION_FAILED`\, `UNAVAILABLE` and `BUSY`\. Clipboard access depends on browser policy and user activation\. Inspect the returned outcome\; copying may require manual selection\. A timed\-out attempt is unconfirmed\, not proof that a later browser write is impossible\. Saved checklist state reports the last local observation\, without multi\-tab locking\. The API requires no login\, API key\, authentication or payment\. It operates the tutorial only\: no OMP\, filesystem\, credentials\, real memories\, command execution or network requests from its script\. `diagnose()` cannot assess your OMP installation\. ## Sources\, method and limitations The original workbook was AI\-authored by Ultima from supplied sanitized configuration and OMP\-facing source\. Its factual review is source\-based\, not a live memory audit or a claim of human certification\. This Markdown edition derives from the authored homepage and its browser API implementation\. The configuration was observed with `omp config list --json`\; the supplied record is 29 August 2026 at 00\:01 UTC\, while the workbook snapshot is dated 28 August\. Memory contents and database health were not inspected\. This describes a custom local build\, not guaranteed upstream version parity\. Core extraction\/consolidation internals were not exhaustively supplied\. Examples describe expected checks rather than observed outcomes\. The [upstream Oh My Pi project]() is the place to consult public software documentation\; it is not the operator or official support channel for this independent workbook\. Implementation references below are source\-relative paths under `packages/coding-agent/src/`\, not private filesystem links\: | Source | Relevant symbols | | --- | --- | | `mnemopi/config.ts` | `loadMnemopiConfig`\, `computeMnemopiBankScope`\, `projectBank`\, `extendRecallWithLegacyBanks`\, `truncateApproxTokens` | | `mnemopi/state.ts` | `MnemopiSessionState`\: `beforeAgentStartPrompt`\, `maybeRetainOnAgentEnd`\, `recallForCompaction`\, `consolidate`\, `dispose`\, `getScopedMemory`\, `editScopedMemory`\; `getMnemopiScopedDbPaths` | | `mnemopi/backend.ts` | `mnemopiBackend`\, `resolveMnemopiProviderOptions`\, `resolveMemoryCompletionInput` | | `tools/memory-recall.ts`\, `tools/memory-retain.ts`\, `tools/memory-reflect.ts`\, `tools/memory-edit.ts` | `MemoryRecallTool`\, `MemoryRetainTool`\, `MemoryReflectTool`\, `MemoryEditTool` | | `internal-urls/memory-protocol.ts` | `MemoryProtocolHandler.resolve`\, `renderMnemopiMemory` | | `autolearn/controller.ts`\, `autolearn/managed-skills.ts` | `AutoLearnController`\, `buildAutoLearnInstructions`\, `writeManagedSkill`\, `getManagedSkillsDir` | | `tools/learn.ts`\, `tools/manage-skill.ts` | `LearnTool`\, `ManageSkillTool` | | `memory-backend/types.ts`\, `memory-backend/off-backend.ts` | `MemoryBackend`\, `offBackend` | | `modes/controllers/command-controller.ts` | `handleMemoryCommand` | Reading fonts are served with the site under the SIL Open Font License\. No telemetry or account connection is included in the tutorial script\. [Return to the interactive workbook]() · [About]() · [Contact and feedback]() · [Privacy]() · [Agent index]() · [Sitemap]() · [Crawler policy]() ## Memory and reusable knowledge\: next steps Useful memory is evidence with scope and provenance\, not standing permission and not an infallible account of the project\. A corrected row can coexist with an older journal\, a skill\, a cached injection\, or a previously exported copy\. Verify the representation that matters instead of treating one successful operation as a claim about all copies\. The next part adds another active conversation\. A tangent can inherit memory\-derived content already present in the conversation\, as well as access to shared files\. Its narrow assignment does not make that inheritance a privacy boundary\. Continue to [Tangent work and live control]()\, carrying two questions\: what evidence did the worker receive\, and what authority does its actual runtime have\? ## Tangent work and live control A **tan** is an OMP tangent subagent\, not TanStack\. It is a contextual\, tool\-capable conversation launched from Main’s persisted history\. It can work alongside Main\, but its conversation fork does not create a separate checkout or worktree\. This part starts where control mistakes are most costly\: a tan is already running\, and you need to know what the next input will affect\. ### Keep three state tracks visible The **view** may be Main\, a focused Tan chat\, or an overlay\. The **agent** may be running\, idle\, parked\, aborted\, or absent\. The **initial background job** has its own running or settled state and may later disappear from the job list\. Those tracks can change independently\. A completed initial job normally parks the tan and returns focus to Main\. A revived tan can subsequently answer another prompt and become idle without restarting that old job\. A draft is not permanently addressed to the agent for which you began typing it\. Use the full Tan agent ID for conversation identity and a separately discovered job ID for the initial managed run\. A supervised process has yet another identity\: its process name\. Display labels\, row positions\, and shortened task previews are not substitutes\. ### Read the practice assignment as a bounded contract Lantern Library’s catalog\, label guide\, and visitor FAQ are fictional textual fixtures included in the source chapters\. You can work through every control decision without launching another provider request\. There is no separate downloadable Tan example package\. The assignments deliberately name read inputs\, write ownership\, excluded work\, and evidence expected in the report\. That makes concurrent work reviewable\, but a “do not edit” instruction is not filesystem isolation\. When two workers share a directory\, even a read\-only report can become stale as another worker changes its inputs\. The initial subagent setup also deserves attention\: the recorded helper defaults unattended approval to `yolo`\, while explicit per\-tool policies remain inherited\. Main’s live extension instances and interactive facilities are not simply cloned into the child\. Do not assume an extension safeguard follows a tan merely because it was active in Main\. ### Operate the actual surface Read [Find and focus the right tan]() with your effective bindings in mind\. The chapters preserve important implementation\-specific cautions about Escape\, double\-left\, the Hub\, queues\, images\, retry\, and Main\-owned command paths\. The recorded proof used real session and controller components with a mock provider and a recording UI adapter\. It supports the named lifecycle observations\, not physical key delivery\, real task quality\, cache savings\, or complete external\-process cancellation\. Keep [Evidence and method]() attached to those claims\. ## Orientation *An Ultima\-authored guide to starting a tangent\, finding it again\, changing its direction\, continuing it\, and stopping the right thing\.* This workbook is for operating Oh My Pi through its terminal interface and through Main\. It emphasizes the moment **after a tan has started**\, when knowing the current target matters more than remembering a command\. **Scope\:** this describes a **custom local OMP source snapshot from 29 August 2026**\. The installed CLI reported `omp/18.0.7`\; that version number does **not** establish upstream\-release parity or prove that an installed binary matches these sources\. All **Lantern Library** examples below are fictional teaching fixtures—not observed user conversations\, files\, or work\. Expected observations are checks to make in your own session\, not claims that the examples have been executed there\. ## A tan is already running **What do you want to do\?** Before typing\, distinguish three things\: - **Main chat\:** ordinary prompts address Main\. - **Agent Hub\:** selecting a row does not yet focus its chat\. Inspect the **full agent ID**\, not merely the display name `tan`\. - **Focused tan chat\:** after successful activation\, look for the notice beginning **`Viewing agent …`** with the intended ID\. The transcript and status line are retargeted to that session\. The dimmed editor outline is only a secondary cue—not a unique identity\. After any automatic return to Main\, **recheck the target before submitting an existing draft**\. | I want to… | Action in this implementation | Important distinction | | --- | --- | --- | | Find the tan | Open the runtime **Agent Hub** with **Alt\+A** or **Ctrl\+S**\; inspect its exact ID\. From Main\, use `/jobs` for background\-job status\. | A Tan agent ID and its background job ID are different\. | | Watch or talk to it | In the Hub\, select the exact Tan row and press **Enter**\. | A parked tan may need revival before focus succeeds\. | | Correct its current work | In the verified tan chat\, type a plain\-language correction and press **Enter** while it is streaming\. | This queues steering\; it is not a guaranteed immediate hard interruption\. | | Give it the next task | In the verified tan chat\, submit with **Ctrl\+Q** or **Ctrl\+Enter** while it is streaming\. | A follow\-up waits until the current work would otherwise yield\. | | Return to Main without cancelling it | In ordinary focused chat\, **Escape clears a nonempty text draft**\; with an empty draft\, **Escape returns to Main**\. Inspect the result after each press\. | Do not blindly press Escape twice\: the second press might already be acting on Main\. | | Return using Left | With an empty focused editor\, deliberately press **Left\, Left**\. | It returns **directly to Main**\, despite the current banner saying “parent\.” | | Continue a finished tan | Find its **parked** row\, press **Enter**\, then send a new\, scoped prompt\. | This continues the agent conversation\; it does not restart its old background job\. | | Interrupt a turn to advance a queued correction | With the tan **streaming**\, a message **already queued**\, and **no text or images in the editor**\, press **Enter**\. | This requests a turn abort\. Queues\, job cancellation\, and agent killing remain separate\. | | Cancel its background job | Ask Main to discover the exact current job identity\, then cancel that **job ID** through the Hub tool\. | `/jobs` itself is a status command\, not a cancellation command\. | | Explicitly kill the tan | In the runtime Hub\, inspect the exact Tan row\, then press **x**\. | The explicit\-kill path requests a durable tombstone and retains the transcript\. It does not undo edits\. | The ordinary focused\-Escape behavior above assumes **no higher\-priority panel or speech playback and no global loop\-mode handling taking precedence**\. See [Leave and switch safely]()\. > **Two common wrong turns** > > - `/tan` launches work\. It has no management subcommands in this snapshot\. A word such as `stop` after `/tan` is work text—not an instruction to stop an existing tan\. > - The runtime **Agent Hub** opened by Alt\+A\/Ctrl\+S is not the `/agents` dashboard for configuring agent definitions\. --- ## 1\. Understand the fork ### One conversation branches\; one workspace remains shared A tan is a **separate\, contextual agent conversation** created from Main’s persisted conversation history\. It receives a new work request and can run concurrently with Main\. It is tool\-capable—not merely a second text answer\. Depending on the tools available when it is constructed\, it can read files\, edit them\, execute work\, and use other enabled capabilities\. The useful mental picture is\: > **Two conversations\, potentially two active workers\, one shared working directory\.** The conversation fork does **not** create an isolated checkout\, Git branch\, or worktree\. There is no automatic tan merge operation\. If a tan edits a file in the shared directory\, that edit is already in the directory Main uses\. ### What a tan is not | Nearby concept | How it differs | | --- | --- | | A quick side question | `/btw` uses an ephemeral side\-request path\. Its tool calls are discarded rather than executed\. A tan has a real session and can perform tool work\. | | An ordinary task subagent | Ordinary task execution starts from a delegated assignment and an agent definition\, with its own model\, lifecycle\, isolation\, and result conventions\. Do not assume those conventions all apply to `/tan`\. | | Another terminal session | Opening another terminal does not automatically fork Main’s conversation\. Tan registry identities and background\-job rows are process\-local controls\, not universal handles across terminal processes\. | | A supervised process | A server\, watcher\, debugger\, or REPL managed through the Hub’s process operations is addressed by a project\-scoped **process name**\. It is not a conversational Tan agent\. | | A safe sandbox | Shared directory access and tool permissions still matter\. “Do not edit” is a task instruction\, not filesystem isolation\. | | A permanent worker | Completion can dispose the live session and leave a parked record\. Revival depends on retained files and available runtime support\. | ### The fork has a task boundary The initial tan is told that the earlier conversation belongs to its parent and that its own responsibility is the new tangent\. The controller also clears the **clone’s inherited todo list**\, including a persisted empty todo edit\. It does **not** clear Main’s todo list\. This reduces a common failure\: a fork sees Main’s unfinished checklist and tries to finish Main’s work instead of its own assignment\. **Operating recommendation\:** make the boundary concrete anyway\. State\: 1. The desired outcome\. 2. The files it may read\. 3. The files it may change—or that it must not change any\. 4. Work owned by Main or another tan\. 5. What evidence its report must contain\. --- ## 2\. Start from Main ### The exact syntax **OMP slash command — enter in Main’s composer\, not a shell\:** ~~~text /tan ~~~ Replace `` with the task\. The command takes the remaining\, trimmed text as the work item\. Multi\-word text needs no special quoting\. There are no `/tan` flags in the supplied implementation\. Main can already be streaming when you launch a tan\. The launch path does not require aborting Main’s current turn\. ### Fictional practice project Imagine a disposable checkout containing these files\. **`data/catalog.csv` — fictional fixture\:** ~~~csv title,shelf,label The Paper Moon,green,amber A Map of Clouds,green,blue The Quiet Atlas,silver,amber ~~~ **`docs/label-guide.md` — fictional fixture\:** ~~~text Green-shelf books use amber labels. Silver-shelf books use silver labels. ~~~ **`docs/visitor-faq.md` — fictional fixture\:** ~~~text Visitors may browse the green and silver shelves. Ask a librarian if a shelf label is unclear. ~~~ You can work through the examples without creating anything\. For a live rehearsal\, have Main prepare these fixtures in a disposable practice directory—not by overwriting similarly named files in an existing project\. ### Worked scenario\: launch a bounded audit First confirm that you are in Main and that the fictional files are available\. **OMP slash command — Main only\:** ~~~text /tan Audit the fictional Lantern Library label rules. Read data/catalog.csv and docs/label-guide.md. Report mismatched labels with their expected labels. Do not edit any file, run project-wide repairs, or change Main's work. ~~~ **Expected observations** - A dispatch status identifies a background job\, such as the generated job ID shown after `Dispatched background tan`\. - The tan appears in the runtime Hub under a generated `Tan-…` agent ID\. - Main remains the underlying conversation\; launch does not automatically focus the tan\. - If Main was already working\, its turn can continue alongside the tan\. The compact dispatch breadcrumb may show only a shortened work preview\. While Main is streaming\, the controller queues that breadcrumb for later context rather than steering it into Main’s current response\. **Fictional acceptance check** Against the unchanged fixtures\, a complete audit should identify\: - **A Map of Clouds\:** blue → amber\. - **The Quiet Atlas\:** amber → silver\. That is a correctness check for the assignment—not a promised model response\. If the tan finishes before you reach it\, use [Continue a finished tan]()\. Finishing quickly is not a control failure\. ### Prerequisites and launch failures | Observation | Meaning and recovery | | --- | --- | | `Usage: /tan ` | No nonblank work was supplied\. Return to Main and provide a concrete assignment\. | | `No active model available for /tan.` | Main has no active model to pass to the clone\. Resolve model availability in Main before launching again\. | | `Background jobs are disabled; enable async jobs to use /tan.` | The actual check is that this session has an async job manager\. See the correction below\. | | `/tan requires a persisted session.` | An in\-memory session is insufficient\. Use a normal persisted interactive session\. | | Background\-job limit reached | Wait for an appropriate running job to finish\, or deliberately cancel an identified job\. Do not cancel an arbitrary row to make room\. | | A filesystem\, session\, authentication\, or provider error | Determine whether dispatch happened before retrying\. A launch acknowledgment does not prove that the first model request succeeded\. | A persisted session need not already contain an assistant answer\: the controller calls `ensureOnDisk()` and flushes it before forking\. An in\-memory session\, however\, has no persisted parent path to fork\. > **Important recovery correction** > > Although the missing\-manager error says “enable async jobs\,” this `/tan` controller does not test `async.enabled`\. The shown SDK constructs the primary async manager independently of that toggle\. > > Therefore\, changing `async.enabled` is **not an established repair for a missing manager**\, nor is that toggle a proven `/tan` on\/off switch here\. Have Main diagnose the current host\/session setup and implementation version\. > > The SDK does read `async.maxJobs` when constructing the manager\. That is not evidence of live resizing of an existing manager\. Keep a copy of an important launch request\. The slash\-command handler clears its text before starting\; the focused\-chat restoration behavior described later is not a blanket guarantee for failed slash\-command launches\. ### What is inherited—and what is not synchronized | At initial launch | Boundary | | --- | --- | | Persisted conversation entries | The child reconstructs context from a journal copy\. Unfinished streaming text\, unsent drafts\, and pending user queues are not a synchronized continuation of Main\. Compaction can affect what history becomes active model context\. | | Main’s current model and configured thinking selector | These are passed at launch\, including an `auto` thinking selector when configured\. Main’s later choices are not a live model mirror for the tan\. | | Main’s current system\-prompt blocks | A snapshot is passed\, not a continuously synchronized prompt\. | | Main’s enabled tool names | This includes enabled tools that are not top\-level\-visible\. The SDK rebuilds tools\; names alone do not guarantee identical availability or implementations\. | | A settings snapshot | The subagent helper applies its own overrides\. Shared services and storage still exist\. | | Model registry and authentication infrastructure | The tan is not a separate account or permission sandbox\. | | Working directory and inherited workspace context | No isolated repository copy is created\. | | Main’s initial `local://` mapping | It is captured for the initial background run\; later Main session changes do not retarget that captured mapping\. | **Permission caveat\:** the subagent settings helper sets the default approval mode to **`yolo`** for unattended execution and disables the advisor by default\. Explicit per\-tool approval policies are still inherited\. Do not assume Main’s interactive approval behavior is reproduced unchanged\. The initial tan is created headlessly\. Focusing it later does not recreate it as a new Main session with all interactive\-only facilities\. It also does not inherit Main’s live extension instances\, editor\, shell\/kernel state\, browser ownership\, or active provider request as one cloned runtime\. Initial extension discovery is disabled\, but that is **not** equivalent to “all custom capabilities are disabled”\: SDK custom\-tool discovery and supplied MCP proxy tools are separate paths\. ### Newly staged images are not forwarded by the launch command The current `/tan` slash handler forwards **work text only**\. `TanCommandController.start()` does not accept an image argument\, and its initial `clone.prompt()` supplies no images\. Consequently\: - An image already recorded in inherited conversation history may be part of the forked history\. - An image newly staged beside `/tan …` is **not forwarded as a new attachment by this launch path**\. - A textual image marker in the work request is not evidence that its image bytes arrived\. For a new image\, launch first\, focus the verified Tan ID\, then attach it to an ordinary chat message\. Alternatively\, provide an authorized\, accessible file and ask the tan to read it\. Inspect the composer after launch\. Do not assume staged attachments were either sent or safely discarded\. --- ## 3\. Find and focus the right tan ### Learn your actual bindings **OMP slash command — Main only\:** ~~~text /hotkeys ~~~ Use the displayed bindings rather than treating this workbook’s defaults as immutable\. On macOS\, OMP may label **Alt** as **Option**\. Terminal applications\, multiplexers\, and custom bindings can intercept or change delivery of a chord\. Ctrl\+Enter is especially dependent on terminal support\; Ctrl\+Q is the alternative default\. **A current documentation gap\:** the generated `/hotkeys` sheet shows the resolved Hub shortcuts and many other application actions\, but the supplied generator omits follow\-up and dequeue rows\. Their absence from that sheet does not mean the actions are disabled\. For those bindings\, ask Main to inspect the effective configuration for\: - `app.message.followUp` - `app.message.dequeue` The keybinding loader supports `keybindings.yml`\, `keybindings.yaml`\, and legacy `keybindings.json`\, with profile inheritance\. Do not infer an effective binding from one file without considering overrides\. ### Default controls by surface | Surface | Default control | Effect | | --- | --- | --- | | Ordinary editor | **Alt\+A** or **Ctrl\+S** | Open the runtime Agent Hub\. | | Hub roster | **Up\/Down** or **k\/j** | Select a row\. | | Hub roster | **Enter** | Focus a local\, usable agent\; revive a parked one if possible\. Successful activation closes the Hub\. | | Hub roster | **t** | Switch between Flat and By parent views\. | | Narrow Hub | **Tab** | Toggle the selected\-agent details view\. | | Visible Hub details | **Page Up\/Page Down** | Scroll details\. | | Narrow details view | **Escape** | Return to the roster\. Use Escape rather than Left when the Hub is open over a focused tan\. | | Hub roster | **Escape**\, or its Hub toggle key | Close the Hub\, revealing the prior chat view\. | | Hub\, selected parked row | **r** | Attempt revival without submitting a new task\. | | Hub\, selected agent row | **x** | Explicit kill\/release\. Inspect the target first\. | | Focused tan chat | **Enter** | New prompt when idle\; steering when streaming\. | | Focused tan chat | **Ctrl\+Q** or **Ctrl\+Enter** | Follow\-up when streaming\; ordinary new prompt when idle\. | | Focused tan chat | **Escape** | Ordinary behavior\: clear text draft\, otherwise return to Main\. | | Empty focused editor | Deliberate **Left\, Left** | Return directly to Main\. | **Focused\-Hub caution\:** with a tan focused and an empty composer\, the global Left handler consumes the key before the Hub details view receives it\. Repeating Left can return the underlying chat to Main instead of dismissing details\. Left is a details\-back action only when that focused\-agent interceptor is inactive\; use Escape here and recheck the prompt recipient after closing the Hub\. The Hub’s By parent view is **agent lineage**\, not Main’s `/tree` conversation\-branch selector\. Changing that display does not move files\, merge conversations\, or change the current prompt recipient\. Main is the ambient chat and is excluded from the runtime Hub roster\. Do not look for a Main row as the normal way back\. ### Worked scenario\: inspect\, then focus 1. Open the runtime Hub\. 2. Select the row for the label audit\. 3. Read its **full Tan ID**\, lifecycle state\, task information when available\, and lineage\. 4. If the information is ambiguous\, use Main’s discovery procedure in [Observe jobs and read results]()\. 5. Press Enter only once the intended row is identified\. 6. Wait for the focus notice identifying that exact agent\. **Expected observation\:** the Hub closes and that agent’s conversation becomes the visible chat\. **Failure recovery\:** if activation fails\, the Hub keeps the failure visible as a notice\. Do not type the task into an uncertain surface\. Diagnose the reported revival or session problem first\. A parked row is not automatically a promise of revivability\. An aborted row opens a read\-only transcript viewer rather than becoming a writable focused session\. Advisor rows are also observation\-only\. ### The “parent” banner is misleading The current focus notice includes\: ~~~text Viewing agent — Esc returns to main, ←← hops to parent ~~~ The second clause is not the implemented key behavior\. The focused double\-left handler calls `unfocusSession()`\. It goes **directly to Main**\, including when the focused agent has a non\-Main parent\. To inspect another parent agent\, select its exact row in the Hub\. Do not use double\-left as a one\-level\-up navigation instruction\. ### Optional detail\: double\-left is a gesture\, not key repeat From Main\, deliberate double\-left on an empty editor opens the Hub only when it has agent content to show\, including saved agents\. The explicit Hub shortcuts can open an empty roster\. The editor detector rejects very rapid synthesized bursts and held\-arrow repetition\. Its accepted second\-tap interval is at least 40 ms and less than 500 ms\. You do not need to time this precisely\; use two deliberate taps\, or use the explicit Hub key\. These are source\-backed input rules\. The supplied runtime proof did not test physical keyboard decoding\. --- ## 4\. Steer and queue work ### Choose “change this” or “do this next” While the tan is streaming\: - **Enter\:** “Adjust the work you are doing\.” - **Ctrl\+Q \/ Ctrl\+Enter\:** “After the current work would otherwise finish\, do this next\.” When the tan is idle\, both submission paths start a normal prompt\. A follow\-up key does not create an indefinite holding queue behind nonexistent work\. ### Worked scenario\: correct the audit mid\-flight The label audit is running\. You now want only green\-shelf mismatches\. Confirm the focused Tan ID\. **Plain\-language message — submit to the verified tan with Enter while streaming\:** ~~~text Correction: report only green-shelf label mismatches. Exclude silver-shelf books from this audit. Keep both input files read-only, and do not repair anything Main is changing. State the narrowed scope in your answer. ~~~ **Expected observations** - The submission is accepted into the tan’s steering path\, not Main’s user queue\. - Pending\-message state may be visible before the message appears in the transcript\. - A later response should acknowledge the green\-only scope\. **Fictional acceptance check\:** the narrowed report should identify **A Map of Clouds\: blue → amber**\, without treating the silver\-shelf mismatch as part of this requested audit\. Earlier output may still contain the original broader scope\. Steering does not retract text already produced or reverse tool effects\. ### Why steering may not act instantly Steering is delivered at agent\-loop boundaries\. Its timing depends on queue and interruption settings and on what is currently executing\. In the shown loop\: - Interruptible waits can be interrupted for steering\. - Tools with side effects are not indiscriminately hard\-killed just because steering arrived\. - Cooperative tools may step aside\. - Tools not yet started may be skipped\. - Otherwise\, the message waits for a safe boundary\. Even the setting named `immediate` does not mean “every provider request and external process stops immediately\.” If the correction is urgent enough to stop execution rather than wait for steering\, use the distinctions in [Interrupt\, cancel\, or kill]()\. ### Worked scenario\: queue the next task Keep the same tan focused while it is still working\. **Plain\-language message — submit with Ctrl\+Q or Ctrl\+Enter\:** ~~~text After the audit, list the green-shelf book titles in alphabetical order. Read the current catalog again before answering. Do not edit any files. ~~~ **Expected observation\:** this is queued as a follow\-up rather than steering\. **Fictional acceptance check\:** with the original fixtures unchanged\, the later list is\: 1. A Map of Clouds 2. The Paper Moon Steering is handled ahead of follow\-up work in the normal queue flow\. Multiple messages can be drained one at a time or together according to the session’s queue settings\. **Important result boundary\:** the initial tan job returns the **last assistant text** after its run settles\. If a follow\-up becomes the last turn\, the job’s delivered text may be the title list rather than the earlier audit\. Read the conversation when you need both\. ### Queued does not mean completed A queued message is live scheduling state\, not a durable task ticket or proof that the model acted on it\. After an interruption\, error\, parking transition\, or uncertain submission\: 1. Recheck the current focus\. 2. Check the queue and transcript\. 3. Determine whether the instruction was accepted and answered\. 4. Only then decide whether to submit it again\. Repeatedly sending the same instruction can create duplicate work\. ### Images in focused chat Focused chat forwards pending image payloads for both Enter and follow\-up submissions\, including image\-only drafts represented by their actual attachment chips\. Keep the image’s chip or marker intact\. At submission\, the input controller drops attachments whose inline markers were removed and renumbers the survivors\. Attachment delivery to the session is not the same as native vision support\. The session may normalize images\, describe them through another model\, or omit them from provider input according to capabilities and settings\. **Recovery when dispatch rejects\:** the focused\-submit catch path restores the submitted text\, pending images\, and image links\, and surfaces the error\. That guarantee concerns a **rejected submission call**\. It does not mean every later model error restores a draft\, or that an accepted message was never processed\. If focus changed while the call was pending\, verify the recipient again before resubmitting the restored draft\. ### Focused chat is not a command console Do not issue slash commands while focused on a tan\. The focused input path blocks\: - Slash commands\. - Bash input beginning with `!` or `!!`\. - Recognized Python command input such as `$ …` or `$$ …`\. The draft is left in place with a notice that commands run in Main\. This does **not** prevent the tan itself from using its enabled tools\. Main’s `.` \/ `c` continue shortcuts and queue shorthand are not the focused\-chat control path\. Use an explicit plain\-language prompt instead\. Model\/thinking cycling is also refused while focused\. Other configuration surfaces remain Main\-owned\; this workbook provides no live Tan model\-switch recipe\. Changing Main’s model\, or editing an agent definition in `/agents`\, is not a supported way to retarget an already\-running tan\. **A useful exception\:** the default **Alt\+R** retry action targets `viewSession`\, so it can retry an idle focused tan’s failed turn\. Preserve an unrelated draft first\: a started retry clears the draft and attachments\. The `/retry` slash command is still not something to enter while focused\. ### Optional detail\: the dequeue shortcut currently targets Main The default dequeue keys are **Alt\+Up \/ Shift\+Up**\, but the supplied `restoreQueuedMessagesToEditor()` implementation drains `ctx.session`—Main—not the focused `viewSession`\. **Do not use those keys as a Tan queue\-editing control\.** They can restore Main’s queued text into the shared editor while a tan is visible\. If that happens\, do not submit it to the tan\. Return to Main and reconcile the restored text with its actual owner\. No Tan\-specific queue\-edit slash command is established by these sources\. --- ## 5\. Leave and switch safely ### Leaving is a view change In ordinary focused chat\, Escape does not cancel the tan\. - **Nonempty text draft\:** Escape clears the text and leaves you focused on the tan\. - **Empty text draft\:** Escape returns you to Main\. This is not a universal “press Escape twice” macro\. If you started with an empty draft\, one Escape already returned you\. Another press can affect Main\. ### Worked scenario\: leave with an unfinished draft You are focused on the label\-audit tan and have typed—but not submitted\: ~~~text Please also rewrite the visitor FAQ. ~~~ You decide not to send it\. 1. Press Escape once\. 2. Confirm the text is gone and you are still viewing the tan\. 3. Inspect any attachment state\. 4. With an empty draft\, press Escape again\. 5. Confirm `Returned to main session` or the corresponding return notice\. **Expected outcome\:** no FAQ request was submitted\. Leaving did not cancel the running audit\. If you want to preserve the draft instead\, copy its text before clearing it\. Do not assume separate per\-agent draft buffers\. ### Worked scenario\: switch between Main and two tans - **Main → tan\:** open Hub\, select exact ID\, Enter\. - **Tan → Main\:** ordinary empty\-draft Escape\, or empty\-editor double\-left\. - **Tan A → Tan B\:** open Hub\, select Tan B’s exact ID\, Enter\. - **Hub → prior chat\:** close the Hub\. Closing the overlay does not by itself mean “return to Main\.” Recheck the focus notice after every transition\. ### Automatic returns need the same target check The focus controller returns to Main when the focused agent is\: - Parked\. - Marked aborted\. - Removed from the registry\. The initial `/tan` run normally parks at completion\, so completion normally causes this automatic return\. A later revived tan can finish a prompt and become **idle** without immediately returning you to Main\. An idle transition alone is not the auto\-unfocus trigger\. **Draft safety rule\:** a draft intended for the tan is not permanently addressed to it\. If the tan parks while you type and the view returns to Main\, the next submission is now a Main submission\. Do not replay an already\-submitted message merely because the screen returned to Main afterward\. First check whether that submission reached the tan\. ### Escape has higher\-priority owners The ordinary focused\-chat rule is conditional\. The input controller handles certain owners before the focused Escape branch\, including\: - Active MCP\-test cancellation handlers\. - Side panels such as `/btw`\, `/omfg`\, and `/cleanse`\. - Speech playback\. - Global loop mode\. **Loop mode is particularly important\:** if enabled\, Escape can act on **Main’s** streaming loop iteration even while a tan is focused\. If Main is idle\, it can pause the loop and cancel its pending submission instead\. It may not unfocus the tan\. Resolve the topmost surface or mode\, then inspect where you are\. Do not keep pressing Escape until something disappears\. ### Do not use whole\-application controls to leave one tan Ctrl\+C\, Ctrl\+D\, closing the terminal\, and process suspension are not Tan\-navigation controls\. In this input controller\, a first Ctrl\+C clears the editor\; a rapid second press requests application shutdown\. Ctrl\+D exits\. Shutdown can cancel owned background work\. Returning to Main is also different from creating\, clearing\, deleting\, or switching Main’s logical session\. Session\-boundary operations can affect jobs\, delivery\, and retained files\. Use focus controls when you only want to change the view\. --- ## 6\. Observe jobs and read results ### Keep three identities separate | Identity | What it names | Where to discover it | | --- | --- | --- | | **Tan agent ID** | The conversation\/agent registration\, generated as `Tan-…` | Runtime Hub roster or agent\-facing Hub list | | **Background job ID** | The initial managed run\, commonly generated as `bg_…` | Dispatch acknowledgment\, `/jobs`\, Hub job inspection | | **Supervised process name** | A server\, watcher\, debugger\, or other broker\-managed process | Hub process listing and description | A display label such as `tan`\, a shortened task preview\, or “the second row” is not an identity\. The internal background\-job record has an `agentId` association\. The persisted tan dispatch record also contains the job ID\, full work text\, and a transcript filename based on the Tan ID\. **Not every rendered or tool\-facing job snapshot exposes that association\.** Do not claim to have mapped the two IDs merely because a list contains one plausible label\. ### Copyable discovery request to Main **Plain\-language message — Main only\:** ~~~text Main, inspect the current live and parked agent roster and your background jobs. Find the tan assigned to the Lantern Library label audit. Report: - its exact Tan agent ID; - any backing background job ID, distinguishing running from merely retained; - its owner or parent; - its agent lifecycle state and job state separately; - the evidence connecting the task, Tan ID, and job ID. Use current roster, dispatch, and authorized transcript information. Do not infer the mapping from a shared "tan" label, a truncated preview, row order, or a remembered job number. Do not send, revive, or cancel anything. If the mapping is unavailable or ambiguous, say so. ~~~ This is a discovery request\, not a special OMP command\. Main must use the inspection surfaces actually available to it\. ### Status without messaging **OMP slash command — Main only\:** ~~~text /jobs ~~~ This shows Main’s owner\-scoped running jobs and a small recent\-job list\. It is a status snapshot\; it does not itself retrieve and consume settled job\-result bodies\. For a currently parked tan\, messaging is not passive observation\: sending can revive it and start a turn\. Read its transcript instead when you only want to inspect prior work\. ### Hub tool arguments are not terminal commands The following are **argument objects for the agent’s `hub` tool**\. They are not shell commands\, slash commands\, or HTTP requests\. Main normally supplies them through its available tool interface\. **Discover live peers\:** ~~~json {"op":"list"} ~~~ **Discover parked peers in the current session root\:** ~~~json {"op":"list","status":"parked","limit":100} ~~~ **Inspect owner\-scoped jobs and additional running\-agent activity\:** ~~~json {"op":"jobs"} ~~~ The default peer list includes running and idle peers\, excludes the caller and advisor transcripts\, and does not list aborted agents\. Parked peers require the parked filter\. Lists default to 32 rows and allow at most 100\. Inspect `shown` and `truncated` counts\. Increasing the limit is not a guarantee of an exhaustive roster\, and no pagination parameter is supplied here\. The runtime UI Hub can also show parked\, killed\, and advisor transcript rows\. These surfaces intentionally have different visibility rules\. ### Checking status can consume delivery A completed tan normally delivers its final text to the **owning session**\, ordinarily Main\. Owner\-routed delivery can enter an active run at a boundary or wake an idle owner\. However\, if the agent’s Hub **`jobs` or `wait`** operation observes a settled result first\, that snapshot becomes the recovered delivery and suppresses a duplicate automatic `async-result`\. Later snapshots may say\: ~~~text Delivery: already delivered or recovered. ~~~ …and omit the body\. That does not mean the tan produced no output\. Look in the earlier delivery or Hub result\, then follow any actual artifact link\. This is why repeated status polling is not a reliable way to repeatedly fetch the same full report\. ### Waiting is not “wait until all work succeeds” After discovering an actual job ID\, Main can narrow a wait\. **Hub tool arguments — replace the placeholder only with a discovered current job ID\:** ~~~json {"op":"wait","ids":[""],"timeoutMs":30000} ~~~ The unified wait can return on the first relevant message\, watched job settlement\, timeout\, or interruption\. It is not an all\-jobs\-complete barrier\. A timeout\: - Does not cancel the job\. - Does not prove the tan is stuck\. - Does not prove that a message was not delivered\. Default job waits can use an adaptive window\. An explicit `timeoutMs` is in **milliseconds**\; do not confuse it with process\-operation timeout fields measured in seconds\. ### Messaging from Main is a different input path **Plain\-language message — Main only\:** ~~~text Main, rediscover the exact Tan ID for the Lantern Library label audit. If there is one unambiguous match, send it this correction: report only green-shelf mismatches, keep the input files read-only, and leave Main's work alone. Report the exact recipient and delivery receipt. Do not describe the receipt as proof that the correction has already been followed. ~~~ For illustration\, the corresponding tool arguments have this shape\: ~~~json {"op":"send","to":"","message":"Report only green-shelf mismatches. Keep the input files read-only and leave Main's work alone."} ~~~ The source messaging path delivers a peer message to a busy agent or wakes\/revives an idle\/parked one\. This is **not the same queue\-control gesture as focused Enter**\, and it is not the same as Ctrl\+Q follow\-up ordering\. If an answer is essential\, `send` supports `await:true`\. That waits for a reply\; it is not a guarantee of task completion\. If the send succeeded but the reply wait timed out or was interrupted\, check the inbox or wait again rather than blindly resending\. ### Read the transcript\, not an invented result path `history://` is an **OMP internal resource scheme**\, read through OMP’s read tooling\. - `history://` provides an index\. - `history://` reads that agent’s transcript\. For live agents\, the handler reads live session messages\. For parked or unregistered agents\, it can use retained JSONL files found through its discovery paths\. It does not need to revive the agent just to read history\. The representation is concise Markdown\, not a promise that every large tool payload is reproduced verbatim\. **Plain\-language message — Main only\:** ~~~text Main, discover the exact Tan ID for the Lantern Library label audit and read its history:// transcript without reviving it. Summarize the audit, the later correction, and any queued follow-up that actually ran. Distinguish completed evidence from proposed or skipped work. Follow only artifact links that were actually returned. ~~~ Ordinary task result URLs such as `agent://` resolve a corresponding `.md` output artifact\. **The initial `/tan` controller does not automatically write that ordinary task result artifact\.** Do not assume an `agent://` route for a Tan ID will work merely because its transcript exists\. ### Full text versus previews A Hub preview or compact dispatch line is not the whole result\. Owner delivery keeps text inline up to the current 12\,000\-character threshold\. Larger text is normally represented by a 4\,000\-character preview plus an `artifact://` link **if artifact persistence succeeds**\. If persistence fails\, only the preview may be available through that delivery\. Read the returned full\-output artifact when present\. If it is missing\, report the gap\; do not silently treat the preview as a complete report\. ### Job IDs are short\-lived handles Background\-job rows are process\-local and normally retained for roughly five minutes after settlement\. They can be removed earlier by lifecycle operations\. Generated job IDs can be reused after eviction\. Therefore\: - Rediscover before cancelling\. - Do not use a job number from an old screenshot or a previous OMP process\. - A missing job row does not mean its Tan transcript disappeared\. - A revived tan can be working without a new job row for its prompt\. Hub job snapshots include additional running\-agent activity not represented by the caller’s running jobs\. That can include a revived agent or work owned by another agent\. It is not blanket authority for Main to cancel that work\. --- ## 7\. Continue a finished tan ### Parked is not idle | Agent state | Practical meaning | | --- | --- | | **Running** | The registration claims active work\. Check live activity if it appears stale\. | | **Idle** | A live session is attached and awaiting another prompt\. | | **Parked** | The live session has been disposed and detached\; a record and transcript path may remain\. Revival is required for new work\. | | **Aborted** | A terminal agent record\, notably after explicit kill\. It is not a writable paused session\. | | **Absent** | No current registry entry\. A transcript may still remain on disk\. | Normal completion of the initial `/tan` job sets the agent to parked\, disposes the live session\, and detaches it\. This is separate from the job’s `completed`\, `failed`\, or `cancelled` state\. A parked tan can have encountered an error\. A completed job is not proof the assignment succeeded\. ### Worked scenario\: ask a finished tan one more question The label audit has finished and its row is parked\. 1. Discover the exact Tan ID again\. 2. Open the runtime Hub\. 3. Select that parked row\. 4. Press Enter\. 5. Wait for successful focus on that exact ID\. 6. Submit a new\, scoped prompt\. **Plain\-language message — verified tan chat\:** ~~~text Continue the Lantern Library tangent only. Main owns all other work. Read the current data/catalog.csv again and report how many green-shelf books it contains. Do not edit files or resume Main's earlier checklist. ~~~ **Fictional acceptance check\:** the unchanged fixture contains **two** green\-shelf books\. **Expected lifecycle observation\:** successful revival attaches a new live session to the same Tan identity and retained transcript\. After this prompt\, it can become idle\. The old background job remains settled or may already have expired\. This prompt does not recreate that job\, and its answer is not promised to flow through the old job’s automatic delivery\. Read the Tan conversation or have Main retrieve the answer\. ### Revival is not task resubmission - **r** attempts to make a parked session live while leaving you in the Hub\. - **Enter** attempts revival as needed and then focuses its chat\. - A **new prompt** asks it to do work\. - A **Hub send** can combine revival with delivery of a new message\. None of these means “rerun the original `/tan` command automatically\.” ### When revival fails Common boundaries include\: - No usable transcript file\. - No saved session\-initialization contract\. - The recorded working directory is gone\. - No persisted reviver installed by the host\. - Unavailable model\/authentication or rebuilt tool dependencies\. - The agent was killed\, removed\, or replaced during revival\. A failed cold revival is not necessarily sticky\: the lifecycle manager drops a failed cold adoption so a later attempt can rebuild from fresher context\. **Recovery** 1. Read and preserve the exact error\. 2. Inspect history without reviving\, if available\. 3. Repair the actual dependency through Main\. 4. Rediscover and retry only after that repair\. 5. If the agent is transcript\-only or terminal\, start a **new** bounded tangent from a reviewed summary instead of pretending the old agent resumed\. Do not delete a tombstone to force a killed agent back into service\. ### Optional detail\: cold revival has new boundaries The initial tan writes a saved contract containing its system prompt\, work text\, and enabled tool names\. It does not record a complete live runtime\. The cold\-revive path\: - Reopens the transcript\. - Rebuilds settings from the host’s current base settings\, with subagent overrides\. - Resolves models through the SDK’s restoration and availability logic\. - Rebuilds tools and clamps the enabled set to available saved names\. - Uses current host resources for parts of initialization\. - Denies respawning when no saved spawn policy exists\; the initial tan contract does not record one\. The recorded working directory is checked and used when reopening the transcript\, while current Main context is also supplied for SDK discovery and shared artifacts\. After a Main move or session transition\, inspect paths and resource mappings rather than assuming perfect reconstruction\. The initial tan’s special fork reminder and compaction subscription are also not a permanently serialized control package\. The original controller installs that subscription for its background run and removes it afterward\; the generic cold reviver does not reinstall the Tan\-specific subscription\. **Practical consequence\:** after revival\, restate the tangent’s scope\, file ownership\, and current inputs\. Check the effective model and tools when they matter\. Do not interpret successful revival as proof of an identical model\, settings snapshot\, cache lineage\, or environment\. --- ## 8\. Interrupt\, cancel\, or kill These operations stop **different things**\. > **None of them rolls back file edits\. None proves that every external process\, tool side effect\, or provider request has stopped\.** ### A\. Interrupt the current turn Use this when the goal is to stop the current attempt and continue the conversation—not to remove the agent\. The demonstrated runtime primitive was `AgentSession.abort()`\, applied to a **revived live tan**\. In that proof\, the tan remained attached and idle\, then answered another prompt\. That primitive is not an OMP slash command\. #### Worked scenario\: advance a queued correction The focused tan is streaming and your correction is still queued as steering\. 1. Verify the exact Tan focus\. 2. Verify that a message is actually queued\. 3. Ensure the editor contains **no text and no images**\. 4. Press Enter\. The focused input handler requests a turn abort and refreshes pending\-message display\. **What to check next** - The interrupted turn settles\. - Pending steering may drain into a fresh run\. - The correction appears in the intended Tan conversation\. - The resulting work obeys the new scope\. **Important limits** - Empty Enter with no queued message does nothing here\. - Empty Ctrl\+Q\/Ctrl\+Enter does not invoke this abort behavior\. - The queue is not automatically erased\. - A follow\-up\-only queue can remain waiting after a deliberate user interrupt\; do not promise that empty Enter flushes every queue\. - On the initial `/tan` run\, settling can lead to ordinary job finalization and parking\. Do not assume every turn interruption leaves the original live session attached\. If it parks or returns you to Main\, inspect the transcript and queue outcome before continuing it\. ### B\. Cancel the background job Use this when the initial managed background run is no longer wanted\. **Plain\-language message — Main only\:** ~~~text Main, refresh the current roster and your background jobs. Identify the exact Tan and backing job for the Lantern Library label audit, with evidence connecting them. Cancel only that job if it is still running, using its discovered background job ID—not its Tan agent ID. If it has already settled or the mapping is ambiguous, take no destructive action and report the state. Afterward, report the cancellation outcome, the Tan's current lifecycle state, and any file or external-process effects that still need inspection. Do not roll back files. ~~~ **Hub tool arguments — only after current discovery\:** ~~~json {"op":"cancel","ids":[""]} ~~~ **Expected observation\:** a successfully cancelled running job becomes `cancelled`\. Cleanup then unwinds\. In the supplied runtime proof\, cancelling the initial Tan job resulted in\: - A cancelled job\. - The Tan registration becoming absent\. - Its transcript remaining on disk at observation\. **Crucial boundary\:** this initial Tan signal\-abort path does not establish the same durable tombstone as explicit kill\. Later persisted discovery can therefore differ\. Do not say “a cancelled tan can never reappear\.” If cancellation reports not found or already completed\, refresh discovery\. Do not increment the job number and try again\. ### C\. Explicitly kill the agent Use this when you want the Tan registration to be terminal\, not merely its current job cancelled\. #### Worked scenario\: kill a finished or revived tan 1. Open the runtime Agent Hub\. 2. Select the exact Tan ID\. 3. Inspect its assignment and lineage\. 4. Press **x** only when that row is the intended target\. The source handler attempts to abort a running session\, then calls explicit lifecycle release with `tombstone:true`\. Treat x as immediately actionable\; the shown handler does not add a separate confirmation step\. **Expected result of a successful explicit kill** - The agent becomes terminal `aborted`\. - Its live session is detached and disposed\. - A `.tombstone` sidecar is written beside its transcript\. - The transcript is retained for reading\. - Revival is refused\. The durable marker is what lets later persisted discovery preserve the terminal decision rather than treating the remaining transcript as a fresh parked agent\. If the Hub displays an error\, or the row changed during the operation\, recheck the outcome\. Do not infer a successful durable kill from pressing the key alone\. **The job can tell a different story\:** x does not itself call background\-job cancellation\. An initial job may settle separately\, and a previously completed job stays completed\. A later settlement notice is not by itself proof that the killed agent is live again\. ### D\. Understand the Hub cancel fallback There is an additional behavior worth knowing before supplying an ID to `hub cancel`\. When the supplied ID does not identify a visible job\, the Hub can try to cancel an **agent registration with that exact ID**\. For a caller with an identity\, the shown check allows its **direct children**\, not arbitrary descendants or other agents’ children\. This fallback aborts\/disposes and performs a plain release or unregister\. It does **not** request `tombstone:true`\. Therefore\: - The lower\-level job manager rejects a Tan ID as the wrong job ID\; the runtime proof demonstrated that\. - The higher\-level **Hub tool may still act on that Tan ID through its registration fallback**\. - A “cancelled agent” receipt is not proof that the original `bg_…` job was cancelled\. - A plain registration removal is not equivalent to the explicit x\/tombstone path\. For an intentionally removed\, jobless child\, this fallback is available\: ~~~json {"op":"cancel","ids":[""]} ~~~ This is a **Hub tool argument example**\, not a recommended substitute for explicit kill when durable terminal intent matters\. ### E\. “Pause\,” process shutdown\, and undo are separate needs No Tan\-specific pause\/resume slash interface is established here\. A message saying “stop editing and wait” is a behavioral request to the model—not a guaranteed runtime freeze\. If you need stronger stopping\, choose job cancellation or explicit kill and verify the outcome\. If the tan started a supervised process\: 1. Have Main discover the actual process name\. 2. Inspect its description\, project\, command\, and ownership evidence\. 3. Stop it through the process\-control surface if that is also intended\. Hub process operations such as `ps`\, `describe`\, `logs`\, and `stop` address **`name`**\, not a Tan ID or background\-job ID\. Process restart\/persistence options are not Tan options\. To undo edits\, inspect the shared working tree and make a separate\, reviewed recovery plan\. Never assume cancelling a tan restores the pre\-launch files\. --- ## 9\. Coordinate several tans ### Allocate ownership before parallel work Every tan starts in the same working directory\. Disjoint conversations do not make disjoint files\. A useful fictional ownership plan is\: | Worker | Write ownership | Read\-only inputs | Must leave alone | | --- | --- | --- | --- | | Main | `data/catalog.csv` and integration decisions | Both documentation files | Documentation while its assigned tan is editing | | Label\-guide tan | `docs/label-guide.md` | `data/catalog.csv` | FAQ\, catalog edits\, unrelated repairs | | FAQ tan | `docs/visitor-faq.md` | Catalog and label guide | Label\-guide edits\, catalog edits\, unrelated repairs | Agree on when shared inputs are stable\. Even a read\-only worker can produce stale conclusions if Main changes its inputs mid\-audit\. ### Worked scenario\: two independent documentation passes Enter each launch separately from Main\. **OMP slash command — Main only\:** ~~~text /tan For the fictional Lantern Library, improve only docs/label-guide.md for clarity. Read data/catalog.csv as an input, but do not edit it. Do not change docs/visitor-faq.md or repair unrelated files. Report the exact edits and any assumptions about the catalog. ~~~ **OMP slash command — Main only\:** ~~~text /tan For the fictional Lantern Library, improve only docs/visitor-faq.md for visitors. Read the catalog and label guide as inputs, but do not edit them. Do not change any other file. Report the exact edits and any assumptions that need Main's review. ~~~ After each launch\, record the discovered identity pair before adding more similar work\: - Full Tan ID\. - Initial job ID\. - Assignment and write scope\. - Current agent state\. - Current job state\. The label `tan` is not enough to distinguish them\. ### Worked scenario\: Main changes an input Suppose Main changes the label policy while the FAQ tan is still writing\. **Plain\-language message — Main only\:** ~~~text Main, discover the exact Tan ID currently responsible for docs/visitor-faq.md. Tell it that the label policy has changed and ask it to reread the current docs/label-guide.md before finalizing. Do not message every tan. Report the exact recipient and whether it acknowledged the new input. ~~~ Do not rely on the tan learning the change from Main’s conversation\. The file can be shared while the explanation of its change is not\. ### Worked scenario\: two workers touched the same file 1. Stop assigning additional overlapping work\. 2. Discover which exact agents and jobs are involved\. 3. Steer or stop the relevant worker according to urgency\. 4. Inspect the **current file and diff**\, not just each agent’s report\. 5. Establish one writer for the conflicted file\. 6. Have that writer reread current contents before making a repair\. 7. Run the specific project checks that cover the reconciled change\. A failed build during Main’s refactor is not an invitation for a tan to repair unrelated work\. Ask it to report the conflict or blocker\. **Acceptance check\:** the final shared file contains the intended combined change\, no unrelated edits\, and passes the relevant checks selected from the actual project\. There is no tan merge command to perform this review for you\. Use unique scratch paths too\. Two workers writing `local://notes.md` can conflict even when their repository files are disjoint\. --- ## 10\. Protect context and recover ### A tangent is not a privacy boundary A tan can inherit conversation content that has nothing to do with its narrow assignment\: - Prior user and assistant messages\. - Tool results and file contents\. - Previously attached images\. - Instructions or memory\-derived content already present in the inherited context\. It can also access the shared workspace through its available tools\. Before launching\, consider whether the inherited content is appropriate for the model\/provider and tool access involved\. A narrow task prompt does not remove unrelated inherited information\. Do not assume that Main’s extension\-based safeguards or interactive approval prompts are reproduced identically\. Verify protections that matter before unattended work\. This public workbook never needs your real transcripts\, credentials\, or private instructions\. ### Cost\: concurrent does not mean free A tan can add model requests\, tool work\, retries\, and auxiliary model activity while Main is also active\. The initial controller copies Main’s effective prompt\-cache routing key while giving the child a separate provider request lineage\. That creates **eligibility for provider cache reuse**\, not a cache\-hit or savings guarantee\. The supplied mock\-provider proof reported zero usage by design\. Those zeros are not pricing evidence\. Also be careful with transcript\-derived totals\: a fork includes historical messages and their usage records\. Such totals are not necessarily the tan’s incremental new spend\. ### Shared scratch space and artifact boundaries During its initial run\, the tan uses a captured mapping to Main’s `local://` scratch root\. A file such as `local://lantern-label-audit.md` can therefore be shared with Main\. The Tan transcript is nested in the parent session’s artifact tree\, and the launch does not recursively copy that tree\. But sharing `local://` does **not** mean every artifact allocator is identical\. The initial controller does not adopt Main’s `ArtifactManager`\; tools can create child\-session artifacts\. The cold reviver\, in contrast\, adopts the current Main artifact manager\. Use paths and links actually returned by the tools\. Do not construct guessed artifact IDs or assume that all resources keep the same mapping after Main moves or a tan is cold\-revived\. ### Compaction preserves intent only within its actual wiring During the initial background run\, the Tan controller reasserts the fork boundary after successful reported compaction\. That is a useful guard\, not a guarantee that every later revived conversation carries the same live reminder machinery\. After compaction or revival\, a concise restatement of scope and ownership is a sensible operating practice\. ### Recovery guide | Symptom | Check | Recovery | | --- | --- | --- | | “I cannot find it in `/jobs`\.” | Did the job expire\? Is it owned by another agent\? Is this a revived\, jobless prompt\? | Check the live and parked roster and `history://`\; do not guess a new job ID\. | | “Hub list says no actionable peers\.” | Are there parked peers\? Is the list truncated\? | Request the parked filter and inspect counts\; use the runtime Hub for further inspection\. | | “The row says running\, but nothing seems active\.” | Is startup still wiring up\? Does live session activity corroborate the status\? | Inspect current state and history before treating it as a stale registration\. | | “My correction did not affect the answer\.” | Was the right Tan focused\? Was it queued\, processed\, or submitted after auto\-return\? | Locate the message in the correct transcript before resending\. | | “I got returned to Main unexpectedly\.” | Did the focused tan park\, become aborted\, or disappear\? | Recheck both state tracks and the draft recipient\. | | “The command was refused in tan chat\.” | Did the draft begin with slash\, shell\, or Python command syntax\? | Preserve it if needed\, return to Main\, and perform only the intended Main action there\. | | “An image was missing\.” | Was it staged beside `/tan`\, or sent later as an actual focused attachment\? Was image input allowed\? | Attach explicitly to the verified tan\, or provide an authorized accessible file\. | | “The report disappeared from later job snapshots\.” | Was it already auto\-delivered or recovered\? | Read the earlier result\, actual artifact link\, or transcript\. | | “Revival failed\.” | Transcript\, saved contract\, workspace\, runtime factory\, model\/auth\, and tool dependencies | Repair the actual dependency\; otherwise use retained history to prepare a new tangent\. | | “I cancelled it\, but a parked row appeared later\.” | Was this job cancellation or plain release rather than explicit tombstoned kill\? | Reconcile the transcript and lifecycle\. Use explicit kill if terminal intent is still required\. | | “Stopping it did not stop a server\.” | Was the server a separately supervised or external process\? | Discover and control that process separately\; verify ownership first\. | | “A test failed during concurrent edits\.” | Did another worker change the tested files or dependencies\? | Establish a stable input point and one writer\, then rerun the relevant check\. | ### Restart and retention are not the same as live control Source supports discovering retained child transcripts under a session’s artifact tree and rebuilding eligible parked agents\. It does not mean a running Tan keeps executing through an OMP process exit\. Discovery also has boundaries\: - It is tied to reachable session roots\, not an unlimited search of every file on the computer\. - Saved\-agent scans and metadata hydration can fail or be incomplete\. - A long inherited transcript can place Tan\-specific initialization beyond the small prefix used for roster metadata\. - A row’s preview may therefore be missing or insufficient to identify its assignment\. - File existence alone does not prove a live\, controllable agent\. The supplied runtime proof exercised cold revival **without proving restart rediscovery**\. Transcripts remained on disk at the proof’s observation points\. That is not permanent retention\. Session deletion\, artifact cleanup\, archive\/GC policy\, storage errors\, and loss of image\/blob dependencies can change later availability\. The supplied evidence does not establish a guaranteed retention period\. Completed journal entries and in\-flight streaming text also have different durability\. Do not assume an abrupt exit preserves every partial token\. ### Optional detail\: do not borrow ordinary\-task recovery settings blindly The initial Tan controller does not run through the ordinary task executor’s full driver\. In particular\, do not present these as established controls for the initial Tan\: - `task.maxRuntimeMs` as its automatic wall\-clock stop\. - `task.softRequestBudget` as its run budget\. - `task.agentIdleTtlMs` as a way to prevent its immediate completion parking\. - `task.isolation.*` as automatic `/tan` isolation\. - Agent\-definition model overrides as a live Tan model selector\. Those settings have uses elsewhere\. Their existence does not establish the same behavior in `TanCommandController.start()`\. --- ## 11\. Operate through Main ### Use an identity\-first brief Main can inspect and coordinate through the tools available in its session\. An agent with authorized terminal\-interface control can also operate the UI\. But a prose request does not magically expose every internal lifecycle method\. The native `/tan` launch is an interactive Main\-composer path\; Hub `start` launches a **process**\, not a tan\. Do not substitute an ordinary task subagent and silently call it a tan\. For each control request\, specify\: 1. **Discovery\:** identify the exact current agent and any job\. 2. **Intent\:** inspect\, message\, continue\, cancel the job\, or explicitly kill the agent\. 3. **Scope\:** which files and processes must remain untouched\. 4. **Evidence\:** report the actual receipt and resulting state\. 5. **Uncertainty\:** stop short of destructive action when identity is unresolved\. ### Copyable request\: inspect without waking ~~~text Main, rediscover the Lantern Library label-audit tan, including parked entries. Read its available transcript and report the latest completed result, current agent lifecycle state, and any current backing job. Do not send it a message, revive it, cancel it, or edit files. Note any missing history, truncated result, or ambiguous identity. ~~~ Remember that Main’s Hub job\-result inspection can consume settled automatic delivery\, as explained earlier\. ### Copyable request\: continue through a message ~~~text Main, find the exact retained Tan ID for the Lantern Library label audit. If it is usable or revivable, send it one new request: continue this tangent only, reread the current catalog, count green-shelf books, and do not edit files or resume Main's old checklist. Report the recipient and delivery outcome. Retrieve its answer when available. Do not assume the original background job has restarted, and do not invent a replacement ID if revival fails. ~~~ This uses peer messaging\. For the precise user steering\-versus\-follow\-up distinction\, use the focused composer controls instead\. ### Copyable request\: explicit terminal intent ~~~text Main, rediscover the exact Lantern Library label-audit tan. I want an explicit agent kill with a durable terminal tombstone, not merely a turn interruption, background-job cancellation, or plain registration removal. Use only an installed control that actually provides that behavior. If it is not exposed to your tools, identify the exact runtime Agent Hub row for the operator's x action and state the limitation. Do not silently substitute another stopping operation. Preserve the transcript, do not roll back files, and identify any separate processes that still require inspection. ~~~ ### Before accepting “done” Ask Main to distinguish\: - The control request was accepted\. - The targeted turn or job settled\. - The agent is idle\, parked\, absent\, or terminal\. - The requested project outcome was actually verified\. - External processes and already\-written files were inspected where relevant\. These are separate claims\. **Your operating habit** > Identify → focus or address → submit once → observe → leave safely → review the result or stop the exact target\. --- ## 12\. State and control reference Three state tracks remain independent\: - **View\:** Main\, a focused Tan chat\, or an overlay\. - **Agent\:** running\, idle\, parked\, aborted\, or absent\. - **Job\:** running\, completed\, failed\, cancelled\, or no longer retained\. | Actor \/ control | Target | Preconditions | Effect | Does **not** imply | | --- | --- | --- | --- | --- | | Operator\: `/tan ` | New child conversation and initial job | Main\; work\; model\; manager\; persisted parent | Forks and dispatches background work | Isolation\, automatic focus\, successful task | | Operator\: Hub Enter | Selected exact agent ID | Usable live agent or successful revival | Focuses chat | New assignment or old job restart | | Operator\: focused Enter | Current Tan session | Nonempty prompt or actual attachment | Prompt if idle\; steering if streaming | Immediate hard stop | | Operator\: Ctrl\+Q \/ Ctrl\+Enter | Current Tan session | Prompt\/attachment | Follow\-up if streaming\; prompt if idle | A paused queue when idle | | Operator\: empty Enter | Current Tan turn | Streaming\; queued message\; no text\/images | Requests turn abort\; leaves queue handling to session | Job cancellation\, kill\, universal queue flush | | Operator\: ordinary focused Escape | Draft or view | No higher\-priority handling | Clears text\, otherwise returns Main | Cancelling the tan | | Operator\: focused double\-left | View | Empty editor\; recognized gesture | Returns directly Main | A one\-level parent hop | | Main\: `/jobs` | Main\-owned jobs | Main composer | Status snapshot | Result consumption or cancellation | | Main\: Hub `jobs` \/ `wait` | Visible owner\-scoped jobs | Available manager\; valid IDs when supplied | Observes\; can consume settled delivery | All work succeeded\, perpetual result retrieval | | Main\: Hub `send` | Exact agent ID in `to` | Addressable recipient | Delivers\; may wake\/revive | Focused steering timing or acknowledged compliance | | Main\: Hub `cancel` with job ID | Running owned job | Current verified job ID | Marks cancelled and signals abort | Durable Tan tombstone | | Main\: Hub cancel registration fallback | Exact direct\-child agent ID | Applicable registration\; ownership check | Aborts\/disposes and removes registration | Same behavior as x | | Operator\: Hub x | Selected exact Tan ID | Matching row\; successful release | Explicit kill with tombstone\; transcript retained | Job necessarily says cancelled\; rollback | | Operator\: Hub r | Selected parked agent | Successful reviver | Rebuilds live session | Reissues original task | | Main\: read `history://…` | Discovered transcript | Reachable live history or retained file | Read\-only transcript access | A live controllable agent | | Main\: Hub process control | Verified process `name` | Available process supervision | Inspects or controls that process | Tan conversation control | --- ## Evidence and method ### What was actually observed The supplied proof used real SDK sessions\, `TanCommandController`\, installed `InputController` callbacks\, `SessionFocusController`\, the registry\, `AsyncJobManager`\, and the persisted cold reviver\. Model transport was the repository’s **mock provider**\. The UI was a **recording adapter**\. The launcher denied network access\, restricted writes to a fresh runtime area\, and removed that area afterward\. Local verification recorded the following nine successful scenarios\. Ultima received the first eight\; the publisher subsequently added the initial\-running\-tan kill check before publication\: | Scenario | Bounded observation | | --- | --- | | Persisted parent and startup | Main and the tan were streaming concurrently\; their session identities differed\; their working directory matched\; the child received Main’s effective prompt\-cache key\. | | Focused steering\, follow\-up\, and Escape | Steering and follow\-up entered the child’s queues\, not Main’s\. With loop mode off and no higher\-priority panels\/TTS\, the first Escape cleared draft text and the next returned to Main without cancelling the job\. | | Queue delivery and normal parking | Steering preceded follow\-up in the child conversation\. The job completed with the last follow\-up text\; the agent parked and detached\; focus returned to Main\. | | Main finishing | Main’s recorded turn finished without an aborted assistant result\. | | Cold revival and continuation | The same Tan identity and transcript were reopened through the real cold\-revive path\, and a new prompt received a mock response\. | | Turn interruption | Direct `AgentSession.abort()` on the revived session left it idle and attached\; a subsequent prompt worked\. This was not an Escape\-key test\. | | Explicit kill | Direct `AgentLifecycleManager.release(..., {tombstone:true})` created the sidecar\, retained the transcript\, and caused revival to be refused\. The physical x key was not exercised\. | | Running\-job cancellation | Direct `AsyncJobManager.cancel(jobId)` cancelled the job and the Tan registration became absent\; its transcript remained\. Passing the Tan ID to that lower\-level job manager did not cancel the job\. | | Killing an initial running tan | The runtime Hub\'s abort\-then\-release primitives produced an aborted\, detached\, tombstoned agent\. Its original job separately became `completed` with `(no output)` and an un\-aborted job signal\. The physical x key was not exercised\. | The supplied focused\-test report records **136 passed\, 0 failed** across\: - `packages/coding-agent/test/slash-commands/tan.test.ts` - `packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts` - `packages/coding-agent/test/session-focus-controller.test.ts` - `packages/coding-agent/test/input-controller-escape.test.ts` - `packages/coding-agent/test/input-controller-keybindings.test.ts` - `packages/coding-agent/test/input-controller-focused-submit-restore.test.ts` - `packages/coding-agent/test/agent-hub-activate.test.ts` - `packages/coding-agent/test/registry/agent-lifecycle.test.ts` Other supplied test bodies were used as contract evidence\, but are not silently included in that reported pass count\. ### What this evidence does not prove It does not establish\: - Physical terminal key delivery or actual OMP renderer appearance\. - Real model quality\, task success\, provider cache hits\, or savings\. - Real LSP\/MCP\/tool side effects or complete external\-process cancellation\. - Worktree isolation\. - Restart rediscovery\. - Permanent transcript or artifact retention\. - Upstream\-release parity\. - Browser verification or an official agentic score for this workbook\. The proof’s cold\-revive fixture deliberately had no enabled tools and disabled several auxiliary systems\. Its successful continuation is not evidence that every production tool configuration reconstructs identically\. The teaching recommendations—identity\-first requests\, disjoint file ownership\, scope restatement\, and post\-control inspection—are operating practices derived from these boundaries\. This manuscript reports supplied evidence\; it is not an additional execution or verification run\. ### Source map | Subject | Supplied project\-relative paths and symbols | | --- | --- | | Slash syntax and routing | `packages/coding-agent/src/slash-commands/builtin-lifecycle.ts` — `BUILTIN_LIFECYCLE_SLASH_COMMANDS`\, `tan.handleTui`\; `packages/coding-agent/src/modes/interactive-mode.ts` — `InteractiveMode.handleTanCommand` | | Initial fork\, inheritance\, images\, parking | `packages/coding-agent/src/modes/controllers/tan-command-controller.ts` — `TanCommandController.start`\, `extractAssistantText`\; `packages/coding-agent/src/session/session-manager.ts` — `SessionManager.forkFrom`\, `ensureOnDisk` | | Rebuilt tools and settings | `packages/coding-agent/src/sdk.ts` — `createAgentSession`\, `createAgentSessionScoped`\, `unregisterUnlessParked`\; `packages/coding-agent/src/task/executor.ts` — `createSubagentSettings`\, `createMCPProxyTools` | | Focused submissions\, Escape\, double\-left\, retry\, dequeue | `packages/coding-agent/src/modes/controllers/input-controller.ts` — `setupKeyHandlers`\, `setupEditorSubmitHandler`\, `#submitToFocusedSession`\, `handleFollowUp`\, `#handleFocusedLeftTap`\, `handleRetry`\, `restoreQueuedMessagesToEditor` | | Focus notices and automatic return | `packages/coding-agent/src/modes/controllers/session-focus-controller.ts` — `SessionFocusController.focusAgent`\, `unfocus`\, `#onRegistryEvent`\, `#attach` | | Default keys and hotkeys\-sheet limitation | `packages/coding-agent/src/config/keybindings.ts` — `KEYBINDINGS`\, `KeybindingsManager`\; `packages/coding-agent/src/modes/utils/hotkeys-markdown.ts` — `buildHotkeysMarkdown` | | Runtime Hub navigation\, revival\, kill | `packages/coding-agent/src/modes/components/agent-hub.ts` — `AgentHubOverlayComponent.#handleTableInput`\, `#activateAgent`\, `#reviveSelected`\, `#killSelected` | | `/jobs` versus `/agents` | `packages/coding-agent/src/slash-commands/builtin-session.ts` — `BUILTIN_SESSION_SLASH_COMMANDS`\; `packages/coding-agent/src/modes/controllers/command-controller.ts` — `handleJobsCommand` | | Job identity\, ownership\, retention\, delivery consumption | `packages/coding-agent/src/async/job-manager.ts` — `AsyncJob`\, `AsyncJobManager.register`\, `cancel`\, `consumeJobResults`\, `#resolveJobId`\, `#scheduleEviction` | | Hub argument shapes and waits | `packages/coding-agent/src/tools/hub/index.ts` — `hubSchema`\, `HubTool.execute`\, `#executeWait`\; `packages/coding-agent/src/tools/hub/types.ts` — `JobSnapshot`\, roster limits | | Cancellation fallback and snapshots | `packages/coding-agent/src/tools/hub/jobs.ts` — `executeCancel`\, `cancelAgentRegistration`\, `buildJobResult`\, `runningAgentsOutsideJobs` | | Peer messaging and list scope | `packages/coding-agent/src/tools/hub/messaging.ts` — `executeList`\, `executeSend`\, `executeMessageWait` | | Process\-name distinction | `packages/coding-agent/src/tools/hub/launch.ts` — `LaunchParams`\, `executeLaunch`\, `operationFor` | | Queue timing and turn abort | `packages/agent/src/agent-loop.ts` — `runLoopBody`\, `executeToolCalls`\; `packages/agent/src/agent.ts` — `steer`\, `followUp`\, `continue`\; `packages/coding-agent/src/session/agent-session.ts` — `prompt`\, `abort`\, `#canAutoContinueForFollowUp` | | Owner delivery and large results | `packages/coding-agent/src/session/agent-session.ts` — `#deliverAsyncJobResult`\, `#formatAsyncResultForFollowUp`\; `packages/coding-agent/src/session/async-job-delivery.ts` — inline and preview thresholds | | Lifecycle and durable terminal intent | `packages/coding-agent/src/registry/agent-lifecycle.ts` — `AgentLifecycleManager.ensureLive`\, `release`\, `persistAgentTombstone`\; `packages/coding-agent/src/registry/agent-registry.ts` — `AgentStatus`\, `getAgentTombstonePath` | | Saved discovery and cold reconstruction | `packages/coding-agent/src/registry/persisted-agents.ts` — `ensurePersistedRoster`\, `registerPersistedSubagents`\, `readPersistedAgentMetadata`\; `packages/coding-agent/src/task/persisted-revive.ts` — `createPersistedSubagentReviverFactory` | | Transcript\, result\, and scratch URLs | `packages/coding-agent/src/internal-urls/history-protocol.ts` — `HistoryProtocolHandler`\; `packages/coding-agent/src/internal-urls/agent-protocol.ts` — `AgentProtocolHandler`\; `packages/coding-agent/src/internal-urls/local-protocol.ts` — `resolveLocalRoot`\, `LocalProtocolHandler.resolveOptions` | | Ordinary task output distinction | `packages/coding-agent/src/task/executor.ts` — `finalizeRunResult`\, `finalizeSubagentLifecycle`\, `runSubagentFollowUpTurn` | | Fork\-boundary intent | `packages/coding-agent/src/prompts/system/tan-context-switch.md`\; `packages/coding-agent/src/prompts/system/background-tan-dispatch.md` — prompt text interpreted as evidence of intended separation\, not as instructions governing this workbook | | Version and configuration definitions | `packages/coding-agent/package.json`\; `packages/coding-agent/src/config/settings-schema.ts` — `SETTINGS_SCHEMA`\; settings behavior was checked against the consuming paths above\, not inferred solely from labels | The bundle does not include every terminal\, provider\, messaging transport\, renderer\, or GC implementation\. Those omissions are material to claims about physical interaction\, external effects\, and long\-term availability\. --- ## Tangent work and live control\: next steps The useful endpoint is not merely “the tan stopped\.” It is a report that identifies the target\, distinguishes job and agent state\, locates the available output\, and accounts for already\-written files or separately supervised processes\. Likewise\, “the message was delivered” does not establish that the requested correction was followed\. Completion\, delivery\, returned output\, and effects are different facts\. The next question is why a particular operation was permitted at all\. A tangent can inherit a per\-tool policy record while its initial settings helper defaults the approval mode to yolo\. Its narrow assignment is not an OS boundary\, and its initial headless construction is not Main’s interactive approval experience copied intact\. Continue to [Tool permissions and approvals]()\. Follow the exact call through tier classification\, effective policy\, device dispatch\, one\-call answers\, and host UI availability before treating a refusal as something to repair or a missing prompt as proof of safety\. Extensions can then make these distinctions easier to operate\: explicit tools can expose identity and revisions\, lifecycle handlers can retire stale authority\, and owner\-addressed delivery can keep a result with its originating conversation\. They do not remove the underlying boundaries or automatically install themselves in every child runtime\. After permissions\, continue to [Extensions inside those boundaries]()\. The design question remains how to make a capability’s actual scope visible to both a human and an agent\. ## Tool permissions and approvals A tangent’s identity tells you which worker you are addressing\. It does not yet explain why one of that worker’s calls ran without asking\, why another stopped before a dialog\, or why an approved write still failed\. This part makes permission resolution an operator skill rather than an extension\-author prerequisite\. Start with the exact operation\, follow its applicable policy\, and keep permission separate from execution and effects\. ### Read the three desks in sequence **Approval Desk** establishes the tier matrix\, then works through conflicts among explicit tool policy\, effective user policy\, mode defaults\, and ordered bash rules\. Its command strings are classification data only\. **Dispatch Desk** follows a `write` envelope into the fictional `seed_slot` device\. You will distinguish generic write policy from device policy\, an outer admission from an inner check\, and two prompts from two executions\. **Boundary Desk** explains the actual one\-call Approve\/Deny choice\, dismissal and unavailable UI\, RPC and ACP capability differences\, launch precedence\, and the later OS\/host boundary\. It also connects Task and Tan construction to the yolo\-default settings helper without pretending that a conversation fork clones every safeguard\. The public starting points are [Approval Desk’s cases]()\, [Dispatch Desk’s cases]()\, and [Boundary Desk’s cases]()\. They are inert JSON\, not configuration to install or tools to submit\. The recording actions change no real inventory or publication service\. ### Keep the default route on paper Predict\, inspect\, explain\, and compare with the supplied recorded outcomes\. No provider call\, credentials\, personal settings change\, remote connection\, privileged broker\, or executable simulator is required\. Browser milestone selection changes reading state only\. The source snapshot and new evidence are dated 30 August 2026\. The two existing focused test runs\, the separate private scenario report\, and the installed configuration CLI observation retain distinct scopes\. Use [Evidence and limitations]() before promoting a passing classification into a claim about physical UI or OS enforcement\. ## Orientation A tool call can stop without offering a dialog\. Another call can run without asking\, even in a mode named `always-ask`\. A call displayed as `write` can actually dispatch a different tool\, with a different tier and policy key\. None of these observations is explained adequately by saying that permissions are simply on or off\. This part teaches an operator’s method\: **identify the exact operation\, follow the policy that applies to that operation\, and distinguish permission to proceed from evidence of an effect\.** You will read enough TypeScript to understand the decision\, but you do not need to build an extension or make a provider request\. The practice setting is the fictional **Cedar Seed Library**\. Its three desks are a sequence of reading exercises\: - **Approval Desk** classifies declarations\, modes\, policies\, and ordered shell rules\. - **Dispatch Desk** follows an operation through a `write` envelope into an argument\-sensitive device tool\. - **Boundary Desk** separates one\-call answers\, UI capabilities\, provider safety acknowledgements\, and host authority\. The complete practice data is in [Approval Desk’s cases]()\, [Dispatch Desk’s cases]()\, and [Boundary Desk’s cases]()\. These are inert JSON records\, not OMP configuration\, executable extensions\, or shell scripts\. `seed_note` and `seed_slot` are fictional recording tools used by the supplied private verifier\; this workbook does not install them\. An action string named `publish` does not contact a publishing service\. Shell\-shaped strings are objects of classification only\: **do not execute them or submit them to OMP\.** ### Use the paper route For each worked case\, cover the answer\, predict the decision\, inspect the fictional inputs\, and compare your explanation with the recorded outcome\. Keep three labels separate\: - **Source\-backed\:** follows the supplied implementation snapshot of 30 August 2026\. - **Recorded\:** describes a completed check in a supplied report\, under that report’s conditions\. - **Paper checkpoint\:** a falsifiable question for the reader\; answering it is not a new runtime test\. The website’s example controls select authored reading milestones\. They do not evaluate your settings\, resolve a real permission policy\, answer an OMP dialog\, or run a fixture\. The default route requires only the text and fictional data\. No credentials\, provider prompts\, personal settings changes\, SSH connection\, privileged broker\, or new simulator are needed\. ## Start with the operation Nia\, the fictional desk operator\, receives two reports\: “the tool was blocked” and “the tool did not ask\.” Before changing a setting\, she asks what operation each report actually describes\. That question prevents a common repair mistake\. A missing tool cannot be enabled by approving a call\. An explicit policy denial is not an unanswered question\. A successful approval cannot make an unwritable file writable\. Each failure belongs to a different boundary\. ### Five gates that must not be collapsed The following is a diagnostic map\, not a promise that every host implements five checks in this exact order\. | Gate | Question it answers | What passing it does not establish | | --- | ---: | --- | | Tool availability | Is this capability enabled and reachable through the current session’s actual tool surface\? | That any particular invocation is approved\. | | Approval policy | Does the applicable declaration\, user policy\, and effective wrapper mode allow\, prompt\, or deny this call\? | A domain grant\, provider acknowledgement\, or OS privilege\. | | Domain authority | Does the application permit this action on this object and revision\? | That host approval or filesystem access will succeed\. | | Provider safety | Are applicable provider requirements satisfied\, including pending computer safety checks handled by the wrapper\? | That the operation is correct or allowed by the OS\. | | OS or host authority | Can the actual process or client perform the requested effect at the actual destination\? | That the effect was wanted\, completed\, or correctly reported\. | The distinction between availability and presentation is especially important\. A discoverable tool can be enabled without appearing as a top\-level schema\. The supplied `xd://` implementation can reach enabled mounted tools and enabled top\-level tools through its canonical map\. Conversely\, a name in old conversation text does not establish present availability\. `ToolLoadMode` in `packages/agent/src/types.ts` describes presentation\. `resolveXdevTool()` in `packages/coding-agent/src/tools/xdev.ts` checks the enabled union before returning a tool\. Neither is a grant for an arbitrary operation\. The SDK’s restricted\-session options are also separate construction controls\; do not treat a familiar launch flag or a displayed name as a complete inventory of every runtime path\. ### Predict two different refusals Inspect these inputs from Boundary Desk as data\: ~~~json { "case": "boundary-no-ui", "approval": "exec", "args": { "action": "publish" }, "mode": "always-ask", "ui": false } ~~~ Now compare `boundary-deny-before-handler`\. Its declaration includes `policy: "deny"`\, its original action is `blocked`\, and its proposed handler replacement is `inspect`\. **Prediction\:** will either case display a selection\? Will the replacement rescue the denied call\? **Recorded answer\:** neither displayed a selection and neither reached the inert executor\. Their traces nevertheless differed\. `boundary-no-ui` recorded one `tool_call`\, then approval requested and approval resolved false with reason `no interactive UI available`\. `boundary-deny-before-handler` recorded no `tool_call` and no approval lifecycle pair\: the direct wrapper’s original\-input policy denial stopped before its handler could supply a replacement\. Thus zero prompts does not mean automatic approval\. It can mean that the call was denied before prompting\, that prompting was required but unavailable\, or that policy admitted the call without a prompt\. The decision and execution evidence distinguish those cases\. ### Make a small decision record For a blocked or unexpectedly unprompted call\, begin with the exact observed tool name\, call ID if available\, arguments\, path or device address\, and current session\/cwd scope\. Then identify the effective mode\, applicable policy key\, tool declaration\, and host UI capability\. Finally\, record whether the underlying operation executed and what effect was actually inspected\. For this workbook\, those facts come from the supplied cases and recorded outcomes—not from a request to an agent to investigate your installation\. In later operational work\, keep complete sensitive arguments and diagnostics private\. **Paper checkpoint\:** explain why `boundary-no-ui` is not an OS permission\-denied file write\. **Worked answer\:** it stops in `ExtensionToolWrapper.execute()` before the inert tool runs\; no file primitive is involved\. An OS denial belongs to a later operation\, such as the separate fallback case studied at Boundary Desk\. **Failure boundary\:** the private scenario report uses a structural runner adapter and explicitly instrumented executors\. It is not a record of a provider choosing a tool\, a real person answering\, or every possible dispatch path\. **Source anchors\:** `packages/agent/src/types.ts` — `AgentTool`\, `ToolLoadMode`\, `ToolApprovalDecision`\; `packages/coding-agent/src/sdk.ts` — `createAgentSessionScoped`\; `packages/coding-agent/src/tools/xdev.ts` — `resolveXdevTool`\; `packages/coding-agent/src/extensibility/extensions/wrapper.ts` — `ExtensionToolWrapper.execute`\. ## Read\, write\, and exec are tiers Nia’s next mistake would be to infer behavior from a tool’s name\. A tool called `read` is not always read\-tier\. A tool carried through `write` is not always write\-tier\. The declaration can be a function of arguments\. A **tier** is a tool’s approval classification\. It is not a sandbox\, a syscall monitor\, or proof that the implementation has no other effects\. ### Learn the baseline matrix first The resolver ranks `read` below `write` below `exec`\. With no explicit policy or active override changing the decision\, the matrix is exact\: | Approval mode | Read tier | Write tier | Exec tier | | --- | ---: | --- | --- | | `always-ask` | allow | prompt | prompt | | `write` | allow | allow | prompt | | `yolo` | allow | allow | allow | The name `always-ask` therefore does **not** mean every call prompts\. It automatically admits read\-tier calls at this baseline layer\. The schema default for `tools.approvalMode` is `yolo`\. The wrapper also falls back to `yolo` when the execute\-time settings context supplies no mode\. That is a source default\, not a statement about a reader’s installation\. A tool with no approval declaration defaults to **exec**\, not read\. **Recorded\:** Approval Desk exercised all nine combinations through the actual `resolveApproval()` and `requiresApproval()` functions\. The cases are `approval-always-ask-read`\, `approval-always-ask-write`\, `approval-always-ask-exec`\, `approval-write-read`\, `approval-write-write`\, `approval-write-exec`\, `approval-yolo-read`\, `approval-yolo-write`\, and `approval-yolo-exec`\. They classified calls\; they did not execute tools or show dialogs\. ### An omitted declaration is a useful counterexample Cover the expected result for `approval-undeclared-exec`\. It supplies the fictional tool name `seed_note`\, no declaration\, and mode `write`\. **Prediction\:** does the absence of an execution\-related name make this an automatically allowed call\? **Recorded answer\:** the result was `policy: "prompt"`\, `tier: "exec"`\, `override: false`\, `source: "mode"`\. Omission is deliberately conservative\. `requiresApproval()` returned `required: true`\; that is still a classification result\, not evidence that a UI appeared\. The same default applies to an unannotated MCP tool at this resolver\. An MCP\-looking name does not itself establish a lower tier\. The existing `approval.test.ts` tests both unannotated and explicitly annotated MCP subjects\. ### Read tier does not mean universally read\-only Several supplied declarations make the limit concrete\: | Source\-backed operation | Declaration | Boundary to retain | | --- | ---: | --- | | Ordinary `ReadTool` path | Usually read | URL reads can make network requests\; some specialized reads escalate\. | | `ReadTool` or `GrepTool` targeting `ssh://` | exec | The higher tier does not grant remote access\. | | `HubTool` peer `send`\, inbox\, waits\, and job `cancel` | read for these declared forms | Messaging\, consuming an inbox\, or cancelling a job can change agent\/job state\. | | `HubTool` process `send` with a process name and no peer target | exec | Process input is classified differently from a peer message\. | | Ordinary filesystem `WriteTool` target | write | The tier is not a workspace\-containment guarantee\. | | `ManageSkillTool` | write | Its managed\-skill storage is not simply the current workspace\. | | `EvalTool` | exec | A harmless\-looking cell does not lower this static declaration\. | These rows are source examples\, not new executed workbook scenarios\. The `hubApproval()` implementation\, rather than its broad comment about read\-only operations\, establishes the classifications\. `HubTool.execute()` then routes those operations to messaging and lifecycle functions\. Likewise\, `ReadTool.approval()` returns read for ordinary HTTP URL reads\, while its execution path can reach `executeReadUrl()` or `fetchReadUrl()`\. Local\-looking or read\-tier work is not a general no\-network promise\. A declaration can also distinguish handler\-backed paths and session artifacts\. Later chapters follow those paths without pretending that read\-tier artifact work has zero effects\. ### Use tiers to predict a gate\, not to certify a program A capable operator can use the matrix to predict the default policy\. To assess the effect\, the operator still needs the actual implementation and destination\. A tool author can declare a tier incorrectly\, and trusted in\-process code can do work outside a particular wrapped call\. **Paper checkpoint\:** predict the baseline policy for an unannotated `seed_note` in `write` mode\, then for a read\-tier peer message in `always-ask`\. **Worked answer\:** prompt\, then allow\. Neither answer establishes what a real implementation would change or disclose\. **Failure boundary\:** the matrix is the fallback after the resolver’s higher\-precedence branches\. Do not apply it before checking explicit denies\, explicit tool policies\, overrides\, or the effective launch mode\. **Source anchors\:** `packages/coding-agent/src/tools/approval.ts` — `normalizeDecision`\, `resolveToolTier`\, `APPROVAL_MODE_MAX_TIER`\, `resolveApproval`\; `packages/coding-agent/src/config/settings-schema.ts` — `tools.approvalMode`\; `packages/coding-agent/src/tools/hub/index.ts` — `hubApproval`\, `HubTool.execute`\; `packages/coding-agent/src/tools/read.ts` — `ReadTool.approval`\, `#executeInner`\; `packages/coding-agent/src/tools/grep.ts` — `GrepTool.approval`\; `packages/coding-agent/src/tools/manage-skill.ts` — `ManageSkillTool`\; `packages/coding-agent/src/tools/eval.ts` — `EvalTool`\. ## Approval Desk\: modes and policies The baseline matrix explains defaults\. It does not explain every decision\. Nia now compares two plausible rules\: “user policy always wins” and “yolo allows everything\.” Both are too broad\. The actual resolver gives special treatment to **denial**\, then distinguishes explicit tool policy from an override\-only prompt and from the mode fallback\. ### Follow the implementation’s precedence First\, the tool’s declaration is evaluated against the arguments and normalized\. A declaration can be a bare tier\, an object carrying a tier and additional fields\, or a function returning either form\. The resolver then identifies the effective user policy\. Its key is the declaration’s `policyKey`\, if present\, otherwise the invoking tool’s name\. If a distinct keyed policy is absent or invalid\, the invoking tool’s policy is the fallback\. After that lookup\, the following order applies\: | Order | Condition | Result | | --- | ---: | --- | | 1 | Tool decision says `deny` | Deny from tool policy\. | | 2 | Effective user policy says `deny` | Deny from user policy\. | | 3 | Mode is `yolo` | An explicit tool policy wins\; otherwise use the effective user policy or allow\. Override is reported false\. | | 4 | Non\-yolo decision has `override: true` | Explicit tool allow remains allow\; otherwise prompt\. Source is tool and override remains true\. | | 5 | Tool decision explicitly says allow or prompt | Use that tool policy\. | | 6 | A valid effective user policy remains | Use that user policy\. | | 7 | No earlier branch decided | Compare the tier with the mode matrix\. | This table describes `resolveApproval()`\. The wrapper can add provider safety requirements and has a specific forwarded\-dispatch prompt predicate\, examined later\. An **override\-only prompt** is a decision such as `{ "tier": "exec", "override": true }`\, with no explicit policy\. It prompts in a non\-yolo mode even if a user allow would otherwise admit the call\. In yolo\, the override\-only prompt is ignored\. By contrast\, `{ "tier": "exec", "policy": "prompt" }` remains a prompt in the resolver’s yolo branch\. Even `override: true` is not literally “always force a prompt”\: a decision that also explicitly says allow returns allow\, after the deny checks\. Read the fields together\. ### Work through four policy conflicts **Prediction\:** for each case below\, name the winning source as well as allow\, prompt\, or deny\. | Case | Important inputs | Recorded resolution | | --- | ---: | --- | | `approval-tool-deny-wins` | Tool write\-tier deny\; user allow\; yolo | deny\, source tool\, reason `Fictional desk is closed` | | `approval-user-deny-wins` | Tool read\-tier allow\; user deny\; yolo | deny\, source user\, policy key `seed_note` | | `approval-explicit-tool-prompt` | Explicit tool prompt\; user allow\; yolo | prompt\, source tool\, override false | | `approval-tool-allow-before-user-prompt` | Explicit tool allow\; user prompt\; always\-ask | allow\, source tool | The last row is easy to misread\. A valid user prompt is not a universal veto over an explicit tool allow\. A valid **effective user deny** is checked earlier and does stop it\. Consequently\, the short settings description cannot replace the resolver’s actual order\. These records also show why denial provenance matters\. `denyError()` distinguishes a tool\-owned refusal from a user\-policy refusal\. A tool\-policy error can include the tool’s reason\. A user\-policy error names the effective user key\. The stock error’s repair hint is not a workbook instruction to remove the policy\. ### A policy key is a lookup identity\, not another cumulative grant Compare these complete fictional resolver inputs\. They are teaching data\, not configuration to install\. ~~~json { "tool": "write", "approval": { "tier": "exec", "policyKey": "seed_slot" }, "mode": "yolo", "userPolicies": { "seed_slot": "not-a-policy", "write": "deny" } } ~~~ This is the input shape of `approval-policy-key-fallback`\. The keyed value is invalid\, so the valid invoking\-tool policy supplies the denial\. **Recorded answer\:** deny\, source user\, policy key `write`\. Now inspect `approval-policy-key-specific`\: ~~~json { "tool": "write", "approval": { "tier": "exec", "policyKey": "seed_slot" }, "mode": "always-ask", "userPolicies": { "seed_slot": " ALLOW ", "write": "deny" } } ~~~ **Recorded answer\:** allow\, source user\, policy key `seed_slot`\. The valid device policy replaces the invoking `write` fallback\, including that fallback’s deny\. The resolver is not performing an intersection of every policy entry in the record\. That does not contradict deny precedence\. The `write` entry is no longer the effective user policy for this keyed decision\. A tool\-owned deny or a deny at a later applicable inner gate is a different matter\. ### Keep normalization claims local `normalizePolicy()` accepts strings\, trims them\, lowercases them\, and recognizes only `allow`\, `deny`\, and `prompt`\. Other values do not become policies at that resolver layer\. A missing or invalid tier in a returned decision defaults to exec\. A function\-valued declaration can still throw\; the general resolver does not promise to catch every throwing declaration and convert it into a safe result\. These facts are not a claim that every raw settings object is validated everywhere\. The wrapper separately uses raw own\-property presence when deciding whether an inner prompt is explicit\. An invalid entry can therefore be ignored as a policy by the resolver while still mattering to that later predicate\. Nor does `resolveApproval()` normalize arbitrary invalid mode names into one of the three supported modes\. Use the documented record shape and exact mode values\. Do not intentionally depend on malformed settings as a safety mechanism\. ### Read the result as an explanation A resolved result contains policy\, tier\, and override\, with provenance fields where the selected branch supplies them\. `policyKey` is useful when user policy won\. `reason` is optional\, not a complete audit record\. For example\, ignoring an override\-only critical prompt in yolo can also omit its reason from the resolved result\. **Paper checkpoint\:** does `write: deny` necessarily deny a call whose declaration has `policyKey: seed_slot`\? **Worked answer\:** no\. A valid keyed policy is selected first\; the invoking `write` policy is consulted only when the keyed value supplies no valid policy\. Then the ordinary precedence applies\. **Failure boundary\:** an allow result is permission at this resolver\, not a successful call\, a persisted human answer\, a domain grant\, or proof that another gate agrees\. **Source anchors\:** `packages/coding-agent/src/tools/approval.ts` — `normalizePolicy`\, `normalizeDecision`\, `resolveApproval`\, `requiresApproval`\, `denyError`\; the fixture references identify the resolver section as lines 104–233\. Recorded cases are in `proof/report.json`\, under the Approval Desk IDs above\. Existing contract coverage is in `packages/coding-agent/test/tools/approval.test.ts`\. ## Approval Desk\: ordered shell rules Nia now reviews a shell\-policy list\. She expects a deny anywhere in the list to win\. The implementation instead chooses the **first applicable rule**\. Whether a rule is applicable depends partly on its approval value\. This makes ordering part of the policy\, not merely its formatting\. ### Inspect strings without running them The following is a complete fictional classification input from `bash-first-applicable-rule`\. It is not a shell exercise and is not a configuration recommendation\. ~~~json { "command": "printf seed-card", "patterns": [ { "match": "printf *", "approval": "allow" }, { "match": "*", "approval": "deny" } ], "mode": "always-ask" } ~~~ **Prediction\:** does the final catch\-all deny block this string\? **Recorded answer\:** no\. The first rule applies\. `BashTool.approval()` returns an explicit tool allow at write tier\, and the resolver returns allow from tool policy\. No shell command was executed by this scenario\. The existing `approval.test.ts` also covers a broad early `*` allow shadowing a later matching deny\. Therefore “there is a deny later” is not sufficient evidence of an effective denial\. ### Understand what matching means `bash.patterns` is an ordered array of objects with `match` and `approval`\. In the supplied implementation\: - Only `*` is a wildcard\. Other regular\-expression\-looking punctuation is escaped\. - Pattern and command whitespace is normalized before matching\. - Policy values are normalized\; malformed rule entries are discarded by the rule reader\. - An allow must match the whole command and pass the shell\-control heuristic\. - A deny or prompt may match the whole command or a tokenized segment of a compound command\. - The first rule that applies under those semantics is selected\. The matching is not a shell security parser\. It does not certify executable identity\, the behavior of scripts or binaries\, environment\-dependent behavior\, or every form of shell interpretation\. The allow heuristic does distinguish some literal quoted metacharacters from active shell control\. The existing tests cover a quoted literal pattern that remains allowable\, as well as expansion\, redirection\, compound syntax\, and arguments reinterpreted through command\/eval options that do not ride a narrow allow\. Those are useful classification contracts\, not an exhaustive shell\-language proof\. ### Change the command shape\, not the rule order Now read `bash-compound-deny-segment`\: ~~~json { "command": "printf seed-card && printf closed", "patterns": [ { "match": "printf *", "approval": "allow" }, { "match": "printf closed", "approval": "deny" } ], "mode": "yolo" } ~~~ **Prediction\:** does the first allow still apply because the text begins with `printf`\? **Recorded answer\:** no\. The compound line cannot use that allow\. The second rule matches a segment\, so the decision is tool\-owned deny with reason `Blocked by bash pattern: printf closed`\. Yolo does not remove the selected explicit denial\. This explains why “first matching” must include the rule’s semantics\. It does not mean “first textual prefix\.” ### Critical heuristics have another ordering boundary After selecting a rule\, `BashTool.approval()` does the following\: 1. If the selected rule says deny\, return explicit deny immediately\. 2. Otherwise\, check `CRITICAL_BASH_PATTERNS`\. 3. If a critical pattern matches\, return exec with `override: true` and reason `Critical pattern detected`\, but no explicit prompt policy\. 4. Only then return the selected allow or prompt\, if any\. 5. With none of those decisions\, return exec\. For the next three cases\, the command field is the inert string `chmod -R 700 /fictional-seed-library`\. It is included to classify a recursive absolute\-path permission change\. **Never execute it\.** | Case | Rule and mode | Recorded resolution | | --- | ---: | --- | | `bash-critical-before-allow` | `chmod *` allow\; write mode\; user bash allow | prompt\, exec\, override true\, source tool | | `bash-critical-yolo` | Same allow rule\; yolo | allow\, exec\, override false\, source mode | | `bash-selected-deny-before-critical` | `chmod *` deny\; yolo | deny\, exec\, override true\, source tool | The critical result in the first two rows is an override\-only decision\. That is why yolo can bypass it\. The third row is an explicit denial returned before the heuristic and remains denied\. There is a further consequence worth predicting from source\: a selected prompt rule does not necessarily survive as an explicit prompt decision when the critical branch returns first\. The selected rule is found first\, but the critical branch is evaluated before selected allow\/prompt is returned\. Do not turn a catch\-all prompt rule into a guarantee that every critical string will prompt in yolo\. For comparison\, `bash-explicit-prompt-yolo` uses the noncritical `printf seed-card` string and a `printf *` prompt rule\. **Recorded\:** it remains a tool\-sourced prompt in yolo\, even with user bash allow\. Here the explicit prompt branch was actually reached\. ### Repair an explanation before repairing a policy When a result surprises you\, write down the selected rule and the branch reached after selection\. If you cannot identify the first applicable rule\, rearranging or broadening the list is premature\. Keep approval patterns separate from `bashInterceptor` rules\: the latter are another execution\-time mechanism for directing work toward dedicated tools\, not the same ordered approval array\. **Paper checkpoint\:** why does a selected deny survive yolo while the critical override\-only result can be allowed\? **Worked answer\:** explicit denial is resolved before the yolo branch\; an override flag without an explicit policy is ignored by that branch\. **Failure boundary\:** the six private bash cases called the real declaration and resolver only\. They did not call `BashTool.execute()`\. Neither their passing classifications nor the existing pattern tests establish a shell sandbox\. **Source anchors\:** `packages/coding-agent/src/tools/bash.ts` — `getBashApprovalPatternRules`\, `bashApprovalRuleMatches`\, `findBashApprovalPatternRule`\, `hasBashApprovalShellControl`\, `CRITICAL_BASH_PATTERNS`\, `BashTool.approval`\; `packages/coding-agent/src/tools/approval.ts` — `resolveApproval`\; `packages/coding-agent/test/tools/approval.test.ts` — ordered\-pattern\, compound\-command\, and critical\-pattern tests\. ## Dispatch Desk\: device and path gates At Dispatch Desk\, Nia sees a call named `write`\. She initially assumes it is a generic filesystem write\. The address changes the question\: the call targets `xd://seed_slot`\, so `write` is carrying an invocation of another tool\. The operator must identify both the **outer transport** and the **inner operation**\. ### Read the envelope and its payload separately This is the fictional envelope used for a reservation case\. Inspect it\; do not submit it to a running agent\. ~~~json { "path": "xd://seed_slot", "content": "{\"action\":\"reserve\"}" } ~~~ The `content` field is a JSON string containing the inner argument object\. In the private verifier\, the only mounted recording tool is `seed_slot`\. Its declaration returns read for `inspect`\, write for `reserve`\, an explicit exec\-tier deny for `blocked`\, and exec for other action strings\, including `publish`\. The executor merely appends an in\-memory record\. `WriteTool.approval()` parses the device payload and calls `resolveToolTier()` on the target\. It returns the borrowed tier with `policyKey: "seed_slot"`\. It does **not** copy the target’s entire policy decision into the outer declaration\. During execution\, `dispatchXdevTool()` resolves the enabled canonical tool and validates the decoded arguments before invoking the executable instance\. The inner wrapper can still enforce a tool\-owned deny or other applicable gate\. ### Predict an inspection and a reservation `dispatch-inspect-no-ui` supplies `action: inspect`\, always\-ask mode\, and no UI\. `dispatch-reserve-once` supplies `action: reserve` in always\-ask and one recorded `Approve` answer\. **Recorded answers\:** the inspection produced no prompt and one inert execution\. The reservation produced one prompt and one inert execution\. Both produced two `tool_call` events\: one for `write`\, one for `seed_slot`\, under the same outer call ID\. The reservation’s outer prompt was\: ~~~text Allow tool: write Path: xd://seed_slot Content: {"action":"reserve"} ~~~ The available responses were exactly `Approve` and `Deny`\. After the outer gate\, `WriteTool.execute()` forwards `xdevApproved: true` when a context is available\. For unchanged inner input\, the wrapper can suppress the duplicate mode\-tier prompt\. Two wrapper layers therefore do not necessarily mean two questions\, and two events do not mean two executions\. ### Policy identity can replace the generic write fallback Compare these recorded cases\: | Case | Applicable policy data | Recorded outcome | | --- | ---: | --- | | `dispatch-fallback-deny` | No device policy\; `write: deny`\; yolo | Outer throw\; zero prompts\, zero `tool_call` events\, zero inert executions\. | | `dispatch-specific-allow` | `seed_slot: allow`\; `write: deny`\; always\-ask\; no UI | Exec\-tier fictional action returned\; zero prompts\, two `tool_call` events\, one inert execution\. | | `dispatch-explicit-prompt-twice` | `seed_slot: prompt`\; yolo\; two Approve answers | Two prompts\, two `tool_call` events\, one inert execution\. | | `dispatch-inner-tool-deny` | Inner action `blocked`\; yolo | Error result with tool\-policy refusal\; one outer `tool_call`\, no inner execution\. | The device\-specific allow is a valid replacement for the invoking\-tool fallback\. It is not an instruction to widen a real device policy\. The explicit device prompt is consulted at both outer and inner layers in the recorded path\, so the current implementation can ask twice for one action\. Do not interpret that as two successful reservations\. The inner\-deny case explains why borrowing a tier is not borrowing the whole decision\. The outer gate permits exec under yolo\, but the inner declaration still denies\. The dispatcher converts that ordinary inner error into a result carrying `isError: true`\. A returned result is not necessarily success\. ### Know the exact forwarded\-prompt predicate The relevant source expressions in `ExtensionToolWrapper.execute()` are\: ~~~ts const explicitPrompt = resolved.override || Object.hasOwn(userPolicies, resolved.policyKey ?? this.tool.name); const xdevBypass = context?.xdevApproved === true && effectiveParams === params; ~~~ An ordinary resolved prompt is required when `explicitPrompt` is true or `xdevBypass` is false\. Pending provider safety checks independently require approval\. Two limits follow directly from this source\: - Raw own\-property presence is not the same as a normalized valid policy\. An invalid entry can still affect this predicate for the key it checks\. - The unchanged\-input test is object identity\, not a deep content comparison or revision hash\. The recorded replacement cases use new argument objects\. There is also a source\-derived edge case\: an unchanged forwarded inner decision that resolves to prompt but has neither a surviving override nor an own user\-policy entry can be suppressed by this predicate\. Do not generalize the tested explicit **user** prompt case into a claim that every possible tool\-owned prompt produces an inner dialog\. This edge case is not a separately executed Dispatch Desk scenario\. ### A revised input must be explained again In `dispatch-rewrite-prompts`\, the outer input is `inspect`\. The recording handler supplies this replacement for the inner tool\: ~~~json { "action": "publish", "note": "Revised fictional card" } ~~~ **Prediction\:** can the replacement ride the original read\-tier admission\? **Recorded answer\:** it cannot use the unchanged\-input bypass\. The inner wrapper reclassifies it as exec\, prompts with the revised action\, and records one inert execution after Approve\. The returned dispatch tier is exec\. A useful diagnostic qualification appears in the same record\: `details.xdev.args` still contains the dispatcher’s original validated `inspect` input\, while the effective tier and inert execution ledger reflect the replacement\. The tier callback updates the tier\; it is not a general rewrite of every dispatch metadata field\. Do not treat that nested metadata as a universal final\-input audit\. `dispatch-rewrite-denies` replaces `inspect` with `blocked`\. **Recorded\:** two `tool_call` events\, no prompt\, no inert execution\, and an error result naming tool policy\. A previously admitted input does not authorize a newly denied one\. `dispatch-malformed-json` carries `{not-json` in yolo\. **Recorded\:** one outer event\, no prompt\, no inner execution\, and an error result explaining that the device expects a JSON args object\. The outer declaration falls back to exec for malformed JSON\; yolo admitting that tier does not make the payload valid\. In a prompting mode\, the outer gate can be reached before this dispatch validation failure\. ### Ordinary paths have different rules The device story does not replace path analysis\. - `WriteTool` unwraps a hashline path header before classification\. SSH\-shaped targets escalate to exec before ordinary handler\-backed write classification\. - `resolveFileWriteApprovalTier()` returns write for ordinary filesystem paths\. For recognized internal\-resource paths\, a writable handler keeps write tier\; absence of a handler write method can yield read tier\. - `local://` can subsequently resolve to session artifact storage and be written\. Thus this classification is not proof of zero file effects\. - A device\-only `write` transport is not a general file\-write grant\. The existing dispatch tests verify refusal of filesystem targets\, with the source’s specific active\-plan local\-sandbox exception\. A fuller displayed description alone does not relax that execution guard\. - `ReadTool` and `GrepTool` use `pathTargetsSsh()` to escalate SSH\-containing arguments\. The substring scan can catch a remote entry before later path\-list expansion\. It does not authenticate to the host or grant access there\. The existing `ssh-url-approval-gate.test.ts` rejects remote\-shaped read\, grep\, and write calls at the wrapper before an SSH connection\, while exercising local counterparts\. That proves the tested gate boundary\, not remote execution\. **Paper checkpoint\:** explain `dispatch-reserve-once` as one outer prompt\, two tool\-call events\, and one inert execution\. Then explain why `dispatch-explicit-prompt-twice` has two prompts without two executions\. **Worked answer\:** the first uses forwarded duplicate\-tier suppression\; the second retains an explicit device user policy at the inner gate\. **Failure boundary\:** this route is not a model for every nested call\. Same\-tool native delegation through `ExtensionRunner.invokeNativeTool()` calls an unwrapped native implementation without another approval gate\. Other bridges and direct calls have their own wiring\. `xd://` is a dispatch address\, not a new source of authority\. **Source anchors\:** `packages/coding-agent/src/tools/write.ts` — `WriteTool.approval`\, `WriteTool.execute`\; `packages/coding-agent/src/tools/xdev.ts` — `parseDeviceArgs`\, `resolveXdevTool`\, `dispatchXdevTool`\; `packages/coding-agent/src/extensibility/extensions/wrapper.ts` — `ExtensionToolWrapper.execute`\; `packages/coding-agent/src/tools/path-utils.ts` — `resolveFileWriteApprovalTier`\, `pathTargetsSsh`\; `packages/coding-agent/test/write-xdev-dispatch.test.ts`\; `packages/coding-agent/test/tools/ssh-url-approval-gate.test.ts`\. ## Boundary Desk\: one call at a time Boundary Desk begins with a deceptively small question\: what did the word Approve authorize\? For the generic tool gate in the supplied wrapper\, the answer is the current call\. There is no built\-in choice here named “allow for session” or “always allow\,” and selecting Approve does not write a per\-tool policy\. ### Inspect the actual binary choice The wrapper calls\: ~~~ts choice = await uiContext.select(safetyPrompt, ["Approve", "Deny"]); const approved = choice === "Approve"; ~~~ Only the exact returned label `Approve` is positive\. `Deny`\, `undefined`\, and other nonmatching values are not approval\. A dialog exception also stops this path and is reported as a false resolution before being rethrown\. These are the generic tool\-approval choices\. They are not Review Desk’s local review outcomes\, an ACP plan\-review menu\, or a domain delegation dialog\. ### Predict the second call Inspect `boundary-approval-does-not-persist`\: ~~~json { "approval": "exec", "args": { "action": "publish" }, "mode": "always-ask", "choices": ["Approve", "Deny"], "repeat": 2 } ~~~ **Prediction\:** does the first answer eliminate the second question\? **Recorded answer\:** no\. The same wrapped tool\, with unchanged settings\, was invoked twice\. There were two prompts and two `tool_call` events\, but only one successful call and one inert executor entry\. The second invocation threw `Tool call denied by user: seed_note`\. The first inert result remains present in the report even though the final outcome is a throw\. That is not evidence that the second invocation ran\. Read `successfulCalls`\, the execution ledger\, and the per\-call lifecycle together\. The simpler cases establish the alternatives independently\: | Case | Recorded response | Prompts | Inert executions | Outcome | | --- | ---: | --- | --- | --- | | `boundary-approve-one-call` | Approve | 1 | 1 | return | | `boundary-deny-one-call` | Deny | 1 | 0 | throw | | `boundary-dismiss-one-call` | `undefined`\, represented by fixture null | 1 | 0 | throw | A declined call is not a persisted deny policy\. Conversely\, a user\-policy deny does not require a dialog in which a person declines this particular call\. ### Follow the order\, not just the final banner For the directly exercised wrapper path\, the useful sequence is\: 1. Consume any existing loop\-emission marker and sample approval inputs from the execute\-time context\. 2. Resolve the original input\; an effective deny stops this wrapper path before its own `tool_call` handler emission\. 3. If not already emitted by the loop\, run applicable `tool_call` handlers\, which can block or return replacement input\. 4. Resolve approval against the effective input and report an effective xdev tier when that callback exists\. 5. If approval is required\, wait for the applicable scheduled\-call preview when such a waiter is installed\. 6. Emit `tool_approval_requested` when approval lifecycle handlers are present\. 7. Obtain the selection\, or resolve false because no UI is available\. 8. Emit `tool_approval_resolved`\; execute the underlying tool only after a positive required decision\. `ui.select` and the executor are steps in this explanation\, not extra OMP event names\. The existing `extensions-runner.test.ts` records requested → UI selection → resolved order and tests preview waiting for canonical and wire\-aliased tool names\. The private fixture report records the lifecycle pairs\, prompt data\, and executor counts through its structural adapter\; it does not exercise that transcript preview waiter\. An approval requested event can therefore exist even when no dialog was displayed\. It records a required decision path\, not proof of a human interaction\. The empty `sessionId` in several private scenario events comes from their deliberately partial execute\-time context\, which has no session manager\. It is not a real reader’s conversation identity\. ### Reclassification has a supported scope The wrapper’s supported replacement path applies a returned `input` before the full approval gate\. The existing runner tests verify that a revised input can become denied\, that a prompt describes revised rather than original input\, and that an xdev replacement forfeits the bypass\. For normal model\-loop preparation\, `AgentLoopConfig.beforeToolCall` documents replacement argument revalidation and propagation into scheduling and tool\-call history\. The retained [Tools\, interception and native delegation]() chapter explains the session wiring and its distinction from direct execution\. A direct `tool.execute()` call is not proof that the loop’s schema revalidation occurred\. The runner’s handlers are not a field\-by\-field replacement pipeline\: they receive the normalized event\, and the last returned result object is retained unless a block short\-circuits\. Computer\-provider calls expose a synthetic actions\/safety\-check view\, so the wrapper does not apply ordinary returned input replacements to those execution parameters\. Do not extend the supported replacement proof to arbitrary in\-process mutation\, to code that changes data after approval\, or to every nested executor\. The wrapper samples mode and user policies before awaiting handlers and selection\; it is not a continuous policy\-revalidation transaction while a dialog remains open\. ### Cancellation is not one universal mechanism The recorded dismissal case and synthetic RPC cancellation both produce `undefined`\, which the wrapper refuses\. Existing runner tests also cover a throwing approval selector and cancellation while an extension\-owned `tool_call` confirmation is pending\. Those are different seams\. The runner supplies signals and active\-work timeout accounting to extension\-handler dialogs\. The generic approval selector call shown above does not itself pass dialog options containing the execution signal\. Do not claim from these records that every external abort automatically cancels every native approval selection or defeats every possible late response\. A cancelled presentation\, a blocked tool\, and rollback of an earlier effect remain separate claims\. **Paper checkpoint\:** after the Approve\-then\-Deny repeat case\, what is the execution count\? **Worked answer\:** one\. The second prompt did not persist or reuse the first answer\, and the denial did not undo the first inert record\. **Failure boundary\:** the wrapper’s result hooks can transform returned content\, details\, and error presentation after execution\. They cannot undo an external effect\. An approval event\, a nonthrowing result\, or a visible success label is not a substitute for checking the operation’s own postcondition\. **Source anchors\:** `packages/coding-agent/src/extensibility/extensions/wrapper.ts` — `ExtensionToolWrapper.execute`\; `packages/coding-agent/src/extensibility/extensions/runner.ts` — `emitToolCall`\, `markToolCallEmitted`\, `consumeToolCallEmitted`\, `waitForToolApprovalPreview`\; `packages/agent/src/types.ts` — `AgentLoopConfig.beforeToolCall`\; `packages/coding-agent/test/extensions-runner.test.ts` — tool approval lifecycle\, input replacement\, timeout\, and cancellation tests\. ## Boundary Desk\: when the host can ask Nia next hears that RPC is headless and concludes it cannot ask for approval\. That conclusion confuses a physical terminal with a semantic UI adapter\. The wrapper asks its **extension runner** whether UI is available\. In the supplied runner\, `hasUI()` is implemented as a comparison against the built\-in no\-op UI context\. It is not a test for a keyboard\, TTY\, window\, or working client display\. ### Separate three questions Ask these independently\: 1. What host mode is running\? 2. Which UI context was installed on the runner or tool context\? 3. Does that adapter actually support the requested selection operation\? The SDK’s initial `hasUI` and `interactivePrompts` options\, the tool context’s UI state\, and `ExtensionRunner.hasUI()` serve related but distinct consumers\. A boolean from one is not proof of every capability in the others\. | Host path | Source\-backed approval surface | Important limit | | --- | ---: | --- | | TUI | `ExtensionUiController` installs selector\-based UI\. | Component\/controller evidence is not physical key\-delivery proof\. | | RPC | `runRpcMode()` installs `RpcExtensionUIContext` on extension initialization\; select uses RPC request\/response helpers\. | A connected client must handle the semantic request\. Native custom components and raw terminal input are not provided\. | | ACP | `createAcpExtensionUiContext()` translates supported dialogs into form elicitations\. | Support depends on negotiated `elicitation.form`\; other methods remain stubbed\. | | Default print\/JSON extension initialization | No UI context is supplied to the runner\. | A required approval fails closed\; automatically allowed calls need not prompt\. | In `runRpcMode()`\, the optional `setToolUIContext` callback is called with the adapter and true when supplied\. `main.ts` supplies that callback for `rpc-ui`\, not ordinary `rpc`\. Nevertheless\, both use the RPC adapter in `initializeExtensions()`\, which is the runner UI consulted by this approval wrapper\. This is why the initial tool\-UI flag does not justify flattening ordinary RPC into no\-UI\. ### Read the two RPC cases `boundary-rpc-approve` and `boundary-rpc-cancel` use the same exec\-tier fictional call in always\-ask mode\. Their `ui` value is `rpc`\. **Prediction\:** what should a positive correlated response and a cancelled response do\? **Recorded answer\:** each produced one select request through the real `requestRpcSelect()` helper and was answered through the real `dispatchRpcControlFrame()` helper\. The positive response produced one inert execution\. The cancelled response became `undefined`\, produced no execution\, and threw the user\-denial error\. Both left zero pending requests in the helper map\. This is stronger than merely printing an expected frame\: the supplied verifier exercised the actual helper functions and wrapper\. It is narrower than launching a full RPC process or proving a real client rendered a dialog\. The runner itself was a structural adapter\, and the responses were supplied in\-process\. The source also gives `RpcPendingExtensionRequests.rejectAll()` a disconnect failure path\. That is source\-backed here\, not an additional workbook disconnect scenario\. ### ACP requires capability\-specific language The ACP adapter checks `clientCapabilities.elicitation.form`\. Without form support\, `select()` returns `undefined`\, `confirm()` returns false\, and editor\/input paths return their unavailable values\. `AcpAgent.#configureExtensions()` still passes a distinct UI adapter to the extension runner\. As a result\, the runner can report `hasUI: true` even when a particular form operation is unavailable\. For a required generic tool approval\, that unavailable selection can be refused as a non\-Approve response rather than taking the runner’s literal no\-UI branch\. This is not evidence that a person selected Deny\. It is an adapter capability boundary\. The supplied ACP setup also marks the tool UI available through its callback when form support is present\, and exposes extension mode as `rpc`\; neither means terminal components work\. ACP plan\-proposal approval has its own control flow and capability fallback\. It is not the generic two\-choice tool gate\. Do not borrow its behavior or menu to explain a `tool_approval_requested` event\. ### No UI is a reason to stop\, not permission to skip Compare `boundary-no-ui` with `dispatch-inspect-no-ui`\. Both have no UI\. The first needs a prompt and refuses\; the second is read\-tier at the applicable gates and returns without a prompt\. Absence of UI does not automatically deny all tools\, and it does not automatically approve a required prompt\. The stock no\-UI error lists configuration\-widening possibilities\. This workbook does not recommend them as the generic repair\. First establish why a prompt is required\, whether the operation is still intended\, and whether the owning host has a supported approval surface\. On this route\, simply record the refusal and continue reading\. **Paper checkpoint\:** is `hasUI: true` sufficient proof that a native panel or an ACP form can be used\? **Worked answer\:** no\. It can indicate only a non\-no\-op adapter\. Check the specific mode and negotiated operation capability\. **Failure boundary\:** no physical terminal\, keyboard\, full RPC client process\, or ACP client flow was exercised by the new private scenarios\. Transport\-helper success does not upgrade itself into those claims\. **Source anchors\:** `packages/coding-agent/src/extensibility/extensions/runner.ts` — `hasUI`\, `initialize`\; `packages/coding-agent/src/modes/rpc/rpc-mode.ts` — `runRpcMode`\, `requestRpcSelect`\, `requestRpcDialog`\, `dispatchRpcControlFrame`\, `RpcPendingExtensionRequests`\; `packages/coding-agent/src/modes/acp/acp-agent.ts` — `createAcpExtensionUiContext`\, `AcpAgent.#configureExtensions`\; `packages/coding-agent/src/modes/runtime-init.ts` — `initializeExtensions`\; `packages/coding-agent/src/modes/print-mode.ts` — `runPrintMode`\; `packages/coding-agent/src/main.ts` — `runRootCommand`\. ## Configuration and launch precedence A displayed setting answers a configuration question\. It does not necessarily answer the wrapper’s final policy question\. Nia’s fictional settings view says always\-ask\, yet an exec\-tier recording call proceeds without a question\. Before assuming a broken gate\, she checks whether the launch supplied `autoApprove` separately\. ### Keep persisted configuration and runtime overrides separate The supplied `Settings` implementation merges the active profile’s persisted layer\, project settings\, explicit configuration overlays\, and runtime overrides\, in that increasing order of precedence\. `get()` resolves a value from the merged view\, falling back to the schema default when it is absent\. `Settings.set()` changes the persisted layer and queues saving\. `Settings.override()` changes a non\-persisted runtime layer\. An ordinary session transition is not a factory reset of those settings\. For well\-formed object layers\, maps are deep\-merged\; arrays such as `bash.patterns` are replaced by the higher layer rather than concatenated\. Therefore the effective ordered rule list must be inspected as a list\, not imagined as every rule from every file in sequence\. The wrapper reads mode and user policies from its execute\-time `context.settings`\. A tool’s own classifier can also read settings bound to its tool instance—for example\, `BashTool.approval()` reads its session’s `bash.patterns`\. A dump from an unrelated settings instance cannot establish both inputs\. ### Read the isolated CLI observation The supplied configuration report used the installed **`omp/18.0.7`** CLI\, an exclusively owned fresh named profile with no linked authentication\, and an empty temporary working directory\. It did not inspect or change the reader’s personal settings\. This section reproduces the observation\, not an executable recipe\. The report does not include a complete profile\-creation preamble\, so no launch or profile\-creation command is invented here\. The default route is to read the recorded roundtrip\. Setting `tools.approvalMode` to `write` with JSON output returned\: ~~~json {"key":"tools.approvalMode","value":"write"} ~~~ Setting the `tools.approval` record to the JSON object `{"bash":"deny"}` returned\: ~~~json {"key":"tools.approval","value":{"bash":"deny"}} ~~~ The saved configuration was YAML\: ~~~yaml tools: approvalMode: write approval: bash: deny ~~~ Getting each setting with JSON output returned an object\, not merely its value\: ~~~json { "key": "tools.approvalMode", "value": "write", "type": "enum", "description": "Default approval behavior for tool calls. 'Always ask' auto-approves read-only tools only. 'Write' auto-approves read and workspace-write tools. 'Yolo' auto-approves all tiers; user policy may still prompt or block." } ~~~ ~~~json { "key": "tools.approval", "value": { "bash": "deny" }, "type": "record", "description": "Per-tool approval policies. Set to 'allow' to auto-approve, 'prompt' to require confirmation, or 'deny' to block. Overrides are honored in every approval mode." } ~~~ Those descriptions are the observed CLI copy\. Their shorthand about read\-only\/workspace\-write behavior does not establish containment or override the more precise resolver precedence\. The supplied capture also contains wall\-time annotations\; those are not fields in either JSON setting object\. **Recorded boundary\:** the roundtrip demonstrates configuration serialization and inspection\. It does not demonstrate an approval dialog\, a live session override\, effective wrapper policy\, or a model invocation\. `commands/config.ts` delegates to `runConfigCommand()`\; the full delegated CLI implementation is not in this selected pack\, so the observed JSON shapes are kept attached to the report\. ### Launch flags add a second source of precedence The supported built\-in long forms are `--approval-mode`\, `--auto-approve`\, and `--yolo`\. The latter two set `autoApprove: true`\. There is no listed built\-in `-y` alias in the supplied parser\. These are flag fragments to interpret\, not commands to launch for this exercise\: | Launch input | Settings value after root\-command override | Wrapper mode when the corresponding context is supplied | | --- | ---: | --- | | No approval flag | Existing resolved setting | That setting\, with the wrapper’s documented fallback if absent | | `--approval-mode always-ask` | always\-ask\, runtime only | always\-ask | | `--auto-approve` or `--yolo`\, without an explicit mode | yolo\, runtime only | yolo | | `--approval-mode always-ask` together with `--auto-approve` or `--yolo` | always\-ask remains the displayed runtime setting | yolo\, because `context.autoApprove === true` wins in the wrapper | `main.ts` deliberately preserves the explicit mode in settings when both inputs exist\. `buildSessionOptions()` separately forwards `autoApprove`\, and the SDK supplies it in the tool context\. The wrapper chooses yolo from that boolean before calling `resolveApproval()`\. Changing the order of those two different flags is not a way to make the explicit mode outrank the boolean at the wrapper\. They populate separate inputs\. **Recorded comparison\:** `boundary-auto-approve-mode` injected configured always\-ask\, `autoApprove: true`\, and no UI\. It returned with zero prompts and one inert execution\. `boundary-auto-approve-still-denied` added an effective user deny and stopped before handlers\, prompts\, or execution\. These cases verify execute\-time wrapper behavior\, not CLI parsing or a full launch\. ### Invalid input does not create a new safe mode The `--approval-mode` setter accepts exactly the three documented values\. For an invalid supplied value it logs a warning and does not install that value as the parsed mode\. That is not the same as a hard launch refusal\, nor proof that it selected always\-ask\. Other parsed inputs and the resolved settings remain relevant\. Similarly\, a type annotation on `Settings.get()` is not runtime validation of every hand\-edited value\. Keep the resolver’s normalization of individual policy strings separate from raw record shape\, launch parsing\, and other consumers\. **Paper checkpoint\:** a settings view says always\-ask\, but the execute\-time context has `autoApprove: true`\. What mode does this wrapper use\, and can an effective deny remain\? **Worked answer\:** yolo\; yes\, the resolver’s explicit deny branches still apply\. **Failure boundary\:** no configuration change is required to finish this chapter\. Do not use a personal profile to recreate the observation or treat a config getter as a diagnostic endpoint for another process’s effective policy\. **Source anchors\:** `packages/coding-agent/src/config/settings.ts` — `Settings.get`\, `set`\, `override`\, `#rebuildMerged`\; `packages/coding-agent/src/config/settings-schema.ts` — `tools.approval`\, `tools.approvalMode`\, `bash.patterns`\; `packages/coding-agent/src/commands/config.ts` — `Config.run`\; `packages/coding-agent/src/cli/args.ts` — `parseArgs`\; `packages/coding-agent/src/cli/flag-tables.ts` — `STRING_SETTERS["--approval-mode"]`\, `VALUELESS_FLAGS`\; `packages/coding-agent/src/main.ts` — `runRootCommand`\, `buildSessionOptions`\; `packages/coding-agent/src/sdk.ts` — execute\-time context construction\. CLI observations\: `proof/cli-config-proof.json`\. ## Subagents and inherited policies The preceding Tan part established that a conversation fork is not a cloned runtime\. Permission construction supplies a concrete reason\. Nia expects an unattended child to reproduce Main’s interactive approval mode\. The initial helper does something more specific\: it snapshots settings\, applies child defaults\, and permits explicit helper overrides afterward\. ### Read the helper in its actual callers `createSubagentSettings()` in `packages/coding-agent/src/task/executor.ts` reads every key in `SETTINGS_SCHEMA` from the base settings\. It creates an in\-memory settings instance with that snapshot\, then applies these defaults before spreading any explicit overrides\: - `tools.approvalMode: "yolo"`\; - `advisor.enabled: false`\. It also passes the base storage handle to the isolated settings instance\. “In\-memory settings overrides” therefore does not mean every shared runtime resource or storage service has been duplicated or removed\. `runSubprocess()` uses this helper for Task construction\. **`TanCommandController.start()` uses the same helper\.** Its call is `createSubagentSettings(this.ctx.settings)`\, with no explicit approval\-mode override at that call site\. The initial Tan SDK construction sets `hasUI: false` and disables extension discovery\. It passes enabled\-tool names and other captured context through specific options\; it does not pass Main’s live extension instances as a cloned safeguard set\. Supplied MCP proxies and custom\-tool discovery are separate mechanisms\. ### Predict a child from a small configuration Use this fictional base configuration on paper\: ~~~json { "tools.approvalMode": "always-ask", "tools.approval": { "bash": "deny" } } ~~~ **Prediction\:** after the helper’s ordinary defaults\, must the child prompt for every exec\-tier call\? Does bash become allowed\? **Source\-backed worked answer\:** the child settings mode defaults to yolo\, so tier\-only exec prompting is not inherited unchanged\. The per\-tool policy record remains relevant\: an effective bash deny still resolves to denial\. A user prompt policy can likewise leave a child needing a UI it does not have\, subject to the resolver’s tool\-policy precedence\. This example is a source\-derived calculation\, not an executed child scenario\. None of the 46 private cases launches Task or Tan\. ### Separate three meanings of inheritance | Layer | What is established | What not to infer | | --- | ---: | --- | | Initial helper defaults | Snapshot values are used\, then yolo and advisor\-off defaults are applied\. | The parent’s interactive mode was copied unchanged\. | | Explicit helper overrides | The final `overrides` spread can replace the helper’s default mode\. | Ordinary Tan launch supplies such an override\, or a new Tan flag exists\. | | Live runtime inputs | The wrapper samples its execute\-time settings and autoApprove\; specific shared callbacks\/resources can remain live\. | Every later parent setting or safeguard automatically mirrors into every child\. | The helper’s optional inherited service\-tier argument is another example of an explicit input\. It concerns provider service tiers\, not the read\/write\/exec approval tiers\. Likewise\, the SDK can carry a live extension\-root provider for certain child construction paths\. Neither establishes a universal live approval\-policy inheritance mechanism\. If another host later applies runtime inheritance\, that is a separate transition to inspect\. An initial helper result is not proof that a child remains permanently at that value\, and a conversation relationship is not proof of a later synchronization\. The complete `packages/coding-agent/src/session/agent-session.ts` implementation and host\-specific live inheritance adapters are outside this selected permissions pack\; no blanket statement about those transitions is warranted\. ### Parent approval is not an OS delegation The helper’s source explains the unattended design in terms of the parent Task approval boundary\. That does not make the child a sandbox or erase its per\-tool policies\. It also does not make a human `/tan` command identical to a model\-issued Task call\: they are different entry surfaces\. A “do not edit” assignment remains behavioral guidance\. The child’s actual tool surface\, policy record\, domain rules\, and host authority determine what it can do\. Focusing a headlessly created Tan later is not evidence that it was reconstructed with every interactive facility\. For the original launch and lifecycle qualifications\, retain [Start from Main]() and [Interrupt\, cancel\, or kill]()\. Their historical observations are not rerun by this chapter\. **Paper checkpoint\:** locate the Tan helper call\, then the helper’s merge order\. Explain how an explicit helper override could differ from the ordinary Tan call without inventing a CLI or slash\-command option\. **Worked answer\:** the helper API accepts overrides after its defaults\; the supplied Tan call does not provide them\. **Failure boundary\:** neither a conversation fork\, a settings snapshot\, nor shared storage proves identical live permissions\, loaded safeguards\, remote authority\, or cross\-process enforcement\. **Source anchors\:** `packages/coding-agent/src/task/executor.ts` — `createSubagentSettings`\, `runSubprocess`\, `createMCPProxyTools`\; `packages/coding-agent/src/modes/controllers/tan-command-controller.ts` — `TanCommandController.start`\; `packages/coding-agent/src/sdk.ts` — `CreateAgentSessionOptions`\, `createAgentSessionScoped`\; `packages/coding-agent/src/extensibility/extensions/wrapper.ts` — execute\-time approval inputs\. ## Approval is not a sandbox Boundary Desk ends by separating two claims that often get compressed into one\: “the application admitted the call” and “the environment allowed the effect\.” Approval is an application\-level decision\. It neither changes the process’s OS authority nor certifies every action the implementation may perform\. A successful call can still have effects outside the boundary its name suggests\, and an approved call can still fail later\. ### Provider safety is an independent required decision Inspect `boundary-provider-check-no-ui`\. It combines a read declaration\, yolo\, `autoApprove: true`\, user allow\, no UI\, and synthetic pending computer safety metadata\. **Prediction\:** does any of that automatic approval acknowledge the pending safety check\? **Recorded answer\:** no\. The wrapper emitted an approval lifecycle pair ending false\, executed nothing\, and reported that pending provider safety checks had no interactive UI\. `providerSafetyApproved` remained false\. In `boundary-provider-check-approved`\, the recording adapter selected Approve\. The prompt included `Fictional seed shelf check`\; the context flag became true and the inert executor recorded one call\. The source makes pending checks independently require approval\, regardless of yolo\, ordinary user allow\, or forwarded xdev admission\. It obtains computer actions and pending checks from provider metadata\, not by treating arbitrary prose as a safety grant\. The proof here is deliberately narrow\: synthetic metadata passed through the actual wrapper\. No provider delivered a request\, no screenshot was taken\, and no desktop input occurred\. This local acknowledgement mechanism is also not the entirety of a provider’s safety policy or refusal behavior\. ### An OS error arrives at another seam Now inspect `boundary-fallback-no-handler`\. The actual `writeFileWithFallback()` helper received an injected BunFile\-shaped primitive whose `write()` throws a synthetic `EACCES` error\. No fallback handler was registered\. **Recorded answer\:** one primitive attempt\, zero successful effects\, and the identical error object rethrown\. There was no privileged channel and no recovered write\. Compare the two error\-classification cases\: | Case | Error data | Recorded classification | | --- | ---: | --- | | `boundary-fallback-code-precedence` | Structured code `ENOENT`\; message mentions a path containing `EACCES` | Not permission\-denied\. | | `boundary-fallback-message` | No structured code\; Error message contains `EACCES` | Permission\-denied\. | `isPermissionDeniedError()` treats a structured code as authoritative\. Only when that structured information is absent does its message fallback apply\. A word in a pathname is not an OS denial\, and a classified denial is not an acquired grant\. ### What a file fallback contract actually provides The source supports a later host seam for selected native ordinary\-file byte writes and unlinks after permission errors\. Direct `EPERM`\, `EACCES`\, and `EROFS` can qualify\. A registered write fallback also enables a special check for a denied parent\-directory creation that Bun initially presents as `ENOENT`\; an ordinary missing or invalid path is not automatically a permission boundary\. The destination is resolved according to the primitive’s semantics\. Writes follow the final symlink target\; unlinks leave the final link itself as the object to remove\. An unverifiable write destination is not handed to a handler\. Delete handlers use a separate registry\, and `confirmedFile: false` does not authorize recursive removal\. Those registries are process\-wide\. A request’s origin session can differ from the session that registered a handler and owns its UI\. Returning true tells native code to proceed as though the supported primitive succeeded\; it is not itself proof that bytes became durable\. These are host contracts to understand\, **not a broker exercise for this route**\. The existing [Permission\-denied file fallbacks]() chapter retains the complete adapter and its missing real\-broker prerequisites\. No elevated writer is supplied here\. ### Several effects remain outside this particular seam A native byte\-write fallback is not exhaustive syscall interception\. It does not universally cover arbitrary extension filesystem calls\, shell or subprocess writes\, archive\-member rewrites\, SQLite row operations\, ACP client\-side writes\, independent LSP workspace edits\, or formatter subprocess mutations\. Similarly\, the approval wrapper is not a restriction on arbitrary imported JavaScript\. The supplied `isProjectTrusted()` compatibility method returns true\; it does not establish a per\-directory consent prompt or OS sandbox\. Tool selection\, approval\, and trust in loaded code must remain separate subjects\. Canonical path handling reduces particular misrouting risks\. Do not promote it into a general claim that every race\, host process\, network route\, or external side effect is constrained by the same policy\. The private verifier’s launcher used a clean environment and an OS sandbox with named restrictions\. Those restrictions describe that evidence\-producing child\, not an OMP feature installed for the reader and not a full sandbox validation suite\. Its effect counters cover instrumented seams\, not every possible effect of arbitrary imports\. **Paper checkpoint\:** can Approve repair `EACCES`\, and does a fallback returning true independently prove durable bytes\? **Worked answer\:** neither\. Approval admits an application call\. The OS\/host still governs the primitive\; a handler’s success is a contract that a real implementation must satisfy and verify\. **Failure boundary\:** the private fallback case was injected\, while the existing focused tests include local kernel\-permission fixtures and stand\-ins\. Neither establishes a real privileged broker or blanket OS isolation\. **Source anchors\:** `packages/coding-agent/src/extensibility/extensions/wrapper.ts` — `computerSafetyChecks`\, `approvalArgs`\, `ExtensionToolWrapper.execute`\; `packages/coding-agent/src/tools/file-write-fallback.ts` — `isPermissionDeniedError`\, `writeFileWithFallback`\, `deleteFileWithFallback`\, `withFileMutationSession`\; `packages/coding-agent/src/tools/path-utils.ts` — `resolveSyscallTarget`\; `packages/coding-agent/src/extensibility/extensions/runner.ts` — `createContext`\, fallback initialization\/disposal\. ## Recovery without widening permission Nia can now replace “permissions are broken” with a specific account\: the target\, the applicable gate\, the observed refusal or admission\, and the effect count\. Recovery begins with that account\. It does not begin by changing the whole session to yolo\. ### Start with the exact observed target and current scope Before any later retry\, establish\: 1. The current persistent conversation and cwd when relevant—not merely a title from an old screenshot\. 2. The exact tool and call\, including any outer `write` envelope and inner device name\. 3. The original arguments\, supported replacements\, and actual destination or action under review\. 4. The tool declaration\, effective policy key\, mode\, and execute\-time autoApprove input\. 5. The host’s relevant UI capability and any independent provider safety requirement\. 6. Whether execution occurred\, which result belongs to which call\, and which effects remain uninspected\. On the paper route\, use only the supplied fictional records\. If a fact is not in the record\, mark it unknown\. Do not create certainty by substituting your own settings or making a provider request\. ### Use the recovery matrix | Observation | Boundary to investigate | Bounded recovery | What not to do | | --- | ---: | --- | --- | | Tool absent or `No such tool` | Enabled registry and actual direct\/mounted route | Confirm the exact known name and current availability\; use an already available appropriate surface or report the missing capability\. | Assume a user allow installs or discovers a tool\. | | `blocked by tool policy` | The declaration’s effective deny\, including a selected bash deny | Read the exact reason and arguments\; preserve the refusal unless the responsible policy owner identifies an authorized correction\. | Expect yolo or a generic user allow to erase a tool deny\. | | `blocked by user policy` | The effective normalized key\, including dispatcher fallback | Identify whether the key is the device or invoking tool\; compare the policy with the intended scope\. | Remove unrelated denies or treat the stock hint as authorization to change policy\. | | `Tool call denied by user` after a selection | One\-call response\, dismissal\, or adapter returning no positive value | Retain the declined outcome\; reconsider the operation and input before any separately authorized retry\. | Treat it as a persisted deny\, or retry just to pressure another answer\. | | Required approval but no UI | Runner UI installation and required operation | Stop\; identify whether the owning host has an appropriate supported approval surface\. Reading the refusal completes this workbook case\. | Widen the mode merely to make unattended execution continue\. | | Prompt or result refers to revised input | Supported handler replacement and reclassification | Review the effective operation again\; correlate prompt\, tier\, and execution evidence\. | Approve by remembering the original input or assume every metadata field was rewritten\. | | Domain stale\-revision refusal | The domain’s own object and revision contract | Inspect the current object and reconsider the action\. | Substitute a fresh token into an unchanged request without review\. | | Malformed device JSON or schema error | Envelope decoding and inner validation | Compare the fictional payload with the actual schema\; repair only the intended input in a separately authorized real workflow\. | Loosen approval policy to repair invalid data\. | | Pending provider safety checks | Provider metadata and explicit acknowledgement path | Keep the required decision separate from ordinary allow\/yolo behavior\; stop if it cannot be obtained appropriately\. | Treat autoApprove or xdev forwarding as acknowledgement\. | | `EPERM`\, `EACCES`\, or `EROFS` after execution begins | Actual OS\/host primitive and resolved target | Preserve the error and relevant cause\; hand the exact authorized operation to the host’s normal diagnostic process outside this workbook\. | Assume another tool approval grants privilege or activate an elevated writer as practice\. | | Extension handler block or timeout | Pre\-execution handler and its active\-work failure | Identify the failing handler and preserve the blocked call\; investigate compatibility or the supported domain path\. | Interpret a stalled gate as silent consent\. | | A call ran without asking | The full resolution path | Check tier defaults\, tool allow\, selected rule\, policy key\, launch autoApprove\, child construction\, and supported forwarding\. | Infer either safety or a bypass from zero prompts alone\. | The matrix deliberately distinguishes a policy denial from a declined call\. It also distinguishes a stale domain object from a handler\-revised tool input\: the generic approval wrapper is not itself a domain revision system\. ### Worked recovery\: an unexpected no\-prompt result Read `dispatch-specific-allow` again\. The outer name is `write`\, generic write policy is deny\, and the fictional action is exec\-tier\. A superficial account says the gate ignored deny\. A complete account says\: - The target is `xd://seed_slot` and the outer declaration supplies that policy key\. - The valid `seed_slot: allow` replaces the invoking `write` fallback\. - The inner declaration does not deny this fictional action\; its user allow applies\. - The report records zero prompts and one inert execution\, not a real publication\. The immediate repair is the explanation\. Whether a real device\-specific allow is intended is a separate policy\-owner decision\. It is not permission to rewrite the reader’s configuration\. Now compare `boundary-auto-approve-mode`\. Its no\-prompt result has another cause\: execute\-time autoApprove selects wrapper yolo despite configured always\-ask\. Do not diagnose it as a device\-policy issue\. ### Worked recovery\: an error result after outer admission In `dispatch-inner-tool-deny`\, the outer transport reaches dispatch\. The inner policy then refuses\, and the dispatcher returns an error result\. There is one outer `tool_call` and no inert inner execution\. A retry with the same denied action is not a missing\-dialog repair\. The operator must address the actual inner\-policy reason or leave the action blocked\. A transport return and an outer event are not evidence that the inner effect occurred\. For a later real file error\, inspect the relevant effect before retrying\. Approval and cancellation are not rollback\, and a sequence of primitives can have partial results\. The prior Tan and Continuity chapters retain their own phase\-aware recovery boundaries\; this permission chapter does not replace them with a universal transaction guarantee\. ### Finish the exercise without resetting anything Nothing must be cleared\, dropped\, or reset to complete these cases\. The fixtures are reading material\. Retain your written predictions and corrections if useful\. Do not use session resets\, memory deletion\, policy removal\, or personal\-profile changes as workbook cleanup\. **Paper checkpoint\:** write a three\-sentence recovery note for `boundary-no-ui`\, naming the fictional target\, the actual stopped gate\, and the effect count\. **Worked answer\:** the exec\-tier `seed_note` call requires approval in always\-ask\. The supplied runner has no UI\, so the wrapper resolves false before execution\. The inert execution count is zero\; changing mode is not required to learn or explain the result\. **Failure boundary\:** a useful diagnosis may end at an unavailable host capability or missing observation\. That is more accurate than manufacturing success through a wider grant\. **Source trail\:** `packages/coding-agent/src/tools/approval.ts` — `denyError`\; `packages/coding-agent/src/extensibility/extensions/wrapper.ts` — refusal and selection paths\; `packages/coding-agent/src/tools/xdev.ts` — dispatch errors\; `packages/coding-agent/src/tools/file-write-fallback.ts` — primitive failure handling\. For separate domain recovery\, see [Review Desk]()\; for session\-state boundaries\, see [Decision Desk resetting deliberately]()\. ## Evidence and limitations A permission explanation is useful only when its evidence reaches the claimed boundary\. This part combines source reading\, two runs of existing focused tests\, a separate private scenario report executed by Main\, and an isolated installed\-CLI configuration observation\. Those are four distinguishable evidence sources\, not one end\-to\-end product test\. ### Source snapshot and exact anchors The new permissions source snapshot is dated **30 August 2026**\. Older Memory\, Tan\, Extension\, and Continuity reports retain their original dates and qualifications\. A shared version string does not establish identical custom APIs or behavior across installations\. | Subject | Supplied source anchors | | --- | ---: | | Declaration and loop contracts | `packages/agent/src/types.ts` — `ToolTier`\, `ToolApprovalDecision`\, `ToolApproval`\, `AgentLoopConfig.beforeToolCall` | | Resolution and provenance | `packages/coding-agent/src/tools/approval.ts` — `normalizeDecision`\, `normalizePolicy`\, `resolveToolTier`\, `resolveApproval`\, `requiresApproval`\, `denyError` | | Per\-call gate and forwarding | `packages/coding-agent/src/extensibility/extensions/wrapper.ts` — `ExtensionToolWrapper.execute`\, `approvalArgs`\, `computerSafetyChecks` | | Runner\/UI and handler behavior | `packages/coding-agent/src/extensibility/extensions/runner.ts` — `initialize`\, `hasUI`\, `emitToolCall`\, marker methods\, preview waiter\, `invokeNativeTool` | | Approval event and UI types | `packages/coding-agent/src/extensibility/extensions/types.ts` — `ToolApprovalRequestedEvent`\, `ToolApprovalResolvedEvent`\, `ExtensionUIContext` | | Shell classification | `packages/coding-agent/src/tools/bash.ts` — `BashTool.approval`\, ordered\-rule helpers\, `CRITICAL_BASH_PATTERNS` | | Path\/device classification | `packages/coding-agent/src/tools/write.ts` — `WriteTool.approval`\, `execute`\; `tools/xdev.ts` — `resolveXdevTool`\, `parseDeviceArgs`\, `dispatchXdevTool`\; `tools/path-utils.ts` — `pathTargetsSsh`\, `resolveFileWriteApprovalTier` | | Nonuniform read effects | `packages/coding-agent/src/tools/read.ts` — `ReadTool`\; `tools/grep.ts` — `GrepTool`\; `tools/hub/index.ts` — `hubApproval`\, `HubTool.execute`\; `tools/manage-skill.ts` — `ManageSkillTool`\; `tools/eval.ts` — `EvalTool` | | Configuration and launch | `packages/coding-agent/src/config/settings.ts` — `Settings`\; `config/settings-schema.ts` — approval settings\; `commands/config.ts` — `Config.run`\; `cli/args.ts` — `parseArgs`\; `cli/flag-tables.ts` — approval setters\; `main.ts` — `runRootCommand`\, `buildSessionOptions`\; `sdk.ts` — session\/context construction | | Protocol and print hosts | `packages/coding-agent/src/modes/rpc/rpc-mode.ts` — `runRpcMode`\, select\/control helpers\; `modes/acp/acp-agent.ts` — `createAcpExtensionUiContext`\, `#configureExtensions`\; `modes/runtime-init.ts` — `initializeExtensions`\; `modes/print-mode.ts` — `runPrintMode`\; `modes/controllers/extension-ui-controller.ts` — `ExtensionUiController` | | Child construction | `packages/coding-agent/src/task/executor.ts` — `createSubagentSettings`\, `runSubprocess`\; `modes/controllers/tan-command-controller.ts` — `TanCommandController.start` | | Later OS\/host seam | `packages/coding-agent/src/tools/file-write-fallback.ts` — write\/delete fallback helpers and error classifier\; `tools/path-utils.ts` — `resolveSyscallTarget` | Paths abbreviated within a table cell retain that cell’s `packages/coding-agent/src/` prefix\. The fixtures supply line references for selected anchors\: approval lines 104–233\; wrapper lines 177–346\; bash lines 264–300 and 553–579\; write lines 515–560 and 1104–1205\; xdev lines 406–474\. These are supplied snapshot references\, not newly measured line numbers\. Implementation takes precedence over broad comments\. In particular\, a comment calling coordination operations read\-only cannot override `hubApproval()` assigning read tier to cancellation and messaging\. A stale UI comment cannot override RPC adapter construction\. ### Recorded evidence\: existing focused tests `proof/existing-tests.json` records **96 passes\, zero failures\, 230 assertions across four files**\: - `packages/coding-agent/test/tools/approval.test.ts`\; - `packages/coding-agent/test/tools/approval-mode.test.ts`\; - `packages/coding-agent/test/tools/ssh-url-approval-gate.test.ts`\; - `packages/coding-agent/test/tools/file-write-fallback.test.ts`\. `proof/additional-tests.json` records a **separate run of 105 passes\, zero failures\, 362 assertions across two files**\: - `packages/coding-agent/test/write-xdev-dispatch.test.ts`\; - `packages/coding-agent/test/extensions-runner.test.ts`\. These are **201 passing existing tests in two runs**\. They are not one newly rerun aggregate of earlier workbook suites\. The existing tests include actual local tool and file contracts as well as injected seams\; they should not all be described as inert classification cases\. SSH\-shaped calls in the dedicated gate tests are rejected before connection\. File\-permission fixtures do not supply a real elevated broker\. ### Recorded evidence\: the separate private scenario report After Main’s execution\, `proof/report.json` reports `passed: true`\: **46 executed cases\, 46 passes\, zero failures**\, four separately labeled source\-only items\, ten inert tool executions\, and one injected denied\-primitive attempt\. The launcher reports exit code zero and no timeout\. | Public fixture | Executed cases | Meaning of the executed route | | --- | ---: | --- | | `source-workbooks/permissions/site/examples/approval-desk/cases.json` | 22 | Actual resolver calls\, including actual BashTool declarations\; no bash execution\. | | `source-workbooks/permissions/site/examples/dispatch-desk/cases.json` | 9 | Actual write\/device dispatch and wrappers around a fictional in\-memory executor\. | | `source-workbooks/permissions/site/examples/boundary-desk/cases.json` | 15 | Wrapper responses\, RPC helpers\, synthetic safety metadata\, and a denied primitive\/error classifier\. | The report captures the exact fixture bytes and their supplied hashes\. The public fixtures still describe authored expected outcomes\; reading their `expected` fields is not itself execution evidence\. The separate report is what records the completed checks\. The earlier `proof/report-contract.json` label `READY_TO_RUN_NOT_EXECUTED_BY_AUTHOR` is historical preparation state\. The completed report supersedes it for these 46 named cases only\. It does not turn its four source\-only items into executed scenarios\. The private runner did not launch a provider\, real shell command\, SSH route\, real remote device\, auth store\, privileged broker\, or desktop input operation\. Its tool counters mean in\-memory ledger appends\. Its denied writer throws before placing bytes\. Full `runRpcMode()` initialization\, actual runner UI construction\, and a real client display were not exercised by this scenario harness\. ### Recorded evidence\: installed configuration CLI `proof/cli-config-proof.json` records the installed `omp/18.0.7` set\/get JSON roundtrip in an owned named profile and empty temporary cwd\. It establishes the shown output objects and saved YAML\, not effective policy in a live session\. The combined launch\-flag behavior is source\-backed\; the injected autoApprove cases verify the wrapper half separately\. No personal settings\, credentials\, private memory\, hidden reasoning\, or unrelated session material is needed for the public practice route\. Private runner contents and generated private reports are not additional downloadable workbook exercises\. ### What remains unproved No supplied result establishes physical keyboard behavior\, every TUI\/ACP\/RPC capability\, actual provider tool delivery\, remote SSH permission\, durable privileged writing\, a full OS sandbox\, or blanket cross\-process enforcement\. Source hashes identify bytes\; they do not prove that every branch in a file executed\. The selected pack does not provide the complete live session inheritance\/revival implementation or a reader’s current child context\. Configuration inspection does not fill that gap\. Likewise\, a nested replacement’s tier report does not make every returned argument field a final\-input record\. The finished manuscript and its editorial connections add explanations\, not new runtime results\. Conversion\, catalog generation\, browser behavior\, preservation of existing routes\, and publication require the owning publisher’s separate verification\; no such action is asserted here\. **Final paper checkpoint\:** assign these claims to their evidence\: the mode matrix\, two prompts for an explicit device policy\, Tan’s initial helper mode\, the JSON config getter shape\, and a working physical approval dialog\. **Worked answer\:** recorded resolver cases\; recorded dispatch case\; supplied source construction\; isolated CLI report\; not established by this evidence\. That last answer is a successful boundary judgment\, not an incomplete lesson\. ## Tool permissions and approvals\: next steps You can now explain a permission outcome without treating every refusal as a request for a wider grant\. You can distinguish an absent tool\, an effective deny\, a declined call\, unavailable UI\, revised input\, and a later host error\. You can also explain why no prompt is not proof of either safety or a broken gate\. ### Carry the operator contract into design The next part asks how a capability should expose those boundaries\. Host approval is only one layer\. Seed Desk’s branch\-persisted authority\, Review Desk’s one\-action revision grant\, and Field Notes’ factory\-local selection have different lifetimes\. None should be silently replaced by a generic approval answer\. Continue to [Extensions inside those boundaries]()\. Read its complete examples as designs whose domain checks\, host wiring\, delivery\, and verification must agree—not as a way to bypass an operator’s policy\. The shared connection [Permission belongs to an operation\, a revision\, and a lifetime]() compares the layers without merging their grants\. ## Extensions inside those boundaries The earlier parts established what the runtime keeps\, what it shares\, and what an operation does not prove\. This part turns those lessons into interface design\. Start with the smallest appropriate surface\. A human command can answer locally\. A model\-callable tool needs a schema and a useful result contract\. A skill supplies guidance\, not executable enforcement\. An SDK host owns initialization and disposal\. A plugin selects distribution entries\; installing it and executing a factory are different events\. ### Follow the progressive projects **Seed Desk** begins with a welcome command and a read\-only tool over the same fictional information\. It grows into inventory queries\, then branch\-local reservations with exact IDs\, revision checks\, human\-granted authority\, and persisted state\. Load only one complete Seed Desk stage at a time\: all stages intentionally own `/seeds`\. **Review Desk** keeps a different promise\. A person can edit and accept a release note locally\; acceptance does not publish it\. The agent’s one\-action grant is held in memory and tied to the session and revision\. Pending dialogs must be aborted and generation\-invalidated so a late positive response cannot restore revoked authority\. Standard dialogs and a native panel expose the same small domain through different presentation capabilities\. **Package Lab** follows Field Notes from one file to helpers\, a manifest\, optional features\, and an embedded SDK host\. Its selection is factory\-local\, not transcript\-local\: a new conversation can reuse the same closure\. The package chapters make that lifetime correction explicit rather than concealing it behind the word session\. All supplied files remain available under their original paths in [the complete archive]()\, including adjacent descriptions\, JSON fixtures\, manifests\, and helper modules\. Additional complete exercises printed in the chapters remain printed exercises\; they are not silently relabelled as separately observed downloads\. ### Match the host before claiming the behavior The examples target the recorded custom build\. Bun and the named runtime packages are real prerequisites where used\. Do not replace an unavailable custom dependency with an unrelated upstream package and call the original example verified\. Binding a factory is not initializing its live actions\. A session reload is not necessarily a factory reimport\. `hasUI` is not proof that a native component works in RPC or ACP\. A provider appearing in a catalog is not proof of authentication or inference\. A file\-fallback adapter is not an elevated writer without a real host broker and policy\. Those distinctions are part of the teaching\, not unfinished work to paper over with successful no\-ops\. ### Keep authority inside the domain Host approval\, the example’s human grant\, and operating\-system authority are separate gates\. In\-process extension code is trusted code\; `isProjectTrusted()` is not a sandbox in the described build\. Revisions prevent stale actions only when the domain validates them\, and cancellation before commit is different from cancellation after a stored effect\. Read the focused laboratories after the progressive projects\, then use the complete public feature inventory and all 46 event descriptions as references\. The final debugging and distribution chapters explain what evidence is needed at each layer\. No real provider\, authentication\, privileged\-broker\, or publication exercise is added by this unified edition\. ## Orientation An independent\, source\-grounded workbook for the current custom Oh My Pi build identified in the recorded checks as **OMP 18\.0\.7**\. It is not a compatibility promise for every upstream or npm release carrying that version\. [Download the complete example bundle]() ## Choose what to build Start with the outcome\, not the API\. ### “I want my agent to do X—build Y” | I want… | Build… | Why this surface fits | | --- | --- | --- | | A human to type `/seeds hours` and receive a local answer | An **extension slash command** | The command handler can answer without asking a model\. | | The model to query inventory or reserve a specific item | A **model\-callable tool** | It has a parameter schema\, structured results\, cancellation and errors\. | | Several commands\, tools and lifecycle handlers to share one domain | An **executable extension** | One default factory registers the related capabilities\. | | A key chord to insert a useful phrase or open a local view | An **extension keyboard shortcut** | It is an operator convenience\, not a model tool\. | | A startup option such as `--seed-quiet` | An **extension CLI flag** | The extension declares the flag before the CLI’s extension\-aware argument pass\. | | To inspect\, block or transform a tool call | An **extension event handler** | `tool_call` and `tool_result` are the supported interception surfaces\. | A slash command is **not** a tool the model can call\. Register a tool when the model needs a permanent domain capability\. Share a domain function between the command and tool rather than asking the model to “run the slash command\.” “Human command” also does not mean “cryptographically proven human keystroke\.” An SDK or RPC host can deliberately submit slash\-command text through the command\-dispatch path\. Extensions run in\-process\; this workbook’s authorization examples are domain checks\, not a sandbox\. ### When code is unnecessary | I want… | Build… | Important boundary | | --- | --- | --- | | A reusable instruction such as “summarize a fictional field observation” | A **prompt template** | It expands text\; it does not itself execute a TypeScript factory\. | | A named text workflow invoked through a slash command | A **file\-based slash command** | Markdown command expansion is different from `registerCommand()` executing code locally\. | | A reusable body of expertise\, instructions and supporting files | A **skill** | Discovery makes guidance available\. It does not automatically execute every script in the skill directory\. | | Standing or conditionally applied instructions | A **rule** | Rules guide model behavior\. They are not filesystem or network enforcement\. | | Different colors and visual styling | A **theme** | A theme changes presentation\, not tool authority\. | | A different input\-editor frame | An **extension composer shape** | A shape is executable rendering code\, separate from a theme\. | ### When the integration belongs elsewhere | I want… | Build… | Important boundary | | --- | --- | --- | | Only a model\-callable function\, especially in an existing tool package | A **standalone custom tool** | Its factory returns tools\, and its legacy `execute` argument order differs from native extension tools\. | | To maintain an existing event\-only integration | A **legacy hook**\, or migrate it to an extension | JS\/TS hook factories can enter the extension loading pipeline\. New combined integrations are usually clearer as extensions\. | | A new model endpoint\, transport or login flow | A **model\-provider registration** | This requires real provider configuration\. Registering metadata does not prove inference works\. | | Tools or resources supplied by a separate process or remote service | An **MCP server** | The server owns a protocol endpoint\; the OMP client connects to it\. | | To distribute extensions\, tools\, commands and optional features together | A **plugin bundle** | A package manifest selects entries\. Installation\, discovery and execution remain distinct steps\. | | To embed OMP in an application | An **SDK host with inline extension factories** | The host owns session creation\, runtime initialization\, UI and disposal\. | | To expose a Gemini\-style extension description | A **declarative `gemini-extension.json` manifest** | In this snapshot\, it is a metadata capability—not an automatic launcher for tools\, factories\, context or MCP servers named inside it\. | There is overlap by design\. A plugin may contain an executable extension\, a skill and a prompt\. An executable extension may register a tool and a human command\. An MCP tool may ultimately appear in the same tool registry as a local tool\. The useful question is always\: > Which component discovers this file\, which component executes it\, and which interface can actually invoke the resulting capability\? ### The workbook’s route Three projects carry the main progression\: 1. [Seed Desk\: welcome and inventory]()\: a volunteer and an agent learn the same fictional desk information\. 2. [Seed Desk\: reservations]()\: reads become revision\-checked\, branch\-aware actions\. 3. [Review Desk]()\: a release note is inspected\, edited\, accepted\, rejected or cancelled—never published\. 4. [Package Lab]()\: a notebook moves from one file to helpers\, a manifest and SDK embedding\. Focused laboratories then cover native UI\, interception\, session navigation\, background delivery\, providers\, resources and file fallbacks\. Use the [public feature reference]() and [all 46 events]() as lookup chapters\. ### How to read claims This workbook uses three labels\: - **Observed\:** a completed check is recorded in the supplied execution report\. - **Source\-backed\:** the behavior follows from the supplied implementation or public type contract\. - **Exercise\:** a proposed experiment or new small example\. Its expected result is explained\, but it is not added to the recorded proof count\. The stories use fictional people and data\. The observations describe the recorded checks\, not real seed\-library operations\, a real release\, or a provider account\. The workbook website and its downloads do not operate your OMP session\. There is no tutorial\-browser control API implied by these lessons\. ## Prepare a reversible lab Before adding convenience\, make failure inexpensive\. Mara\, a seed\-library volunteer\, wants to experiment without filling her normal project with extension state\. She chooses an explicit entry path and a scratch working directory\. That gives her a reproducible launch command and a clear place to inspect the session file\. ### Prerequisites You need\: - The workbook\-compatible custom `omp` on `PATH`\. - Bun\; the recorded checks used **Bun 1\.3\.14**\. - The complete example directory structure\, preferably from [the ZIP]()\. - Matching runtime dependencies where an example imports them\. Check the installed versions\, but do not treat a matching version string as proof that an unrelated distribution contains the same custom APIs\. **Terminal shell—inspect your installed programs\:** ~~~sh omp --version bun --version ~~~ The Seed Desk stages are complete\, independent entries\. Load **one at a time**\: all three intentionally own `/seeds`\. Package Lab’s command\-line entries use type\-only SDK imports and injected schema builders\. Seed Desk stage 3 additionally imports matching `@oh-my-pi/omptype` and `@oh-my-pi/pi-tui` runtime packages\. Review Desk imports the TUI package through the compatible host’s extension loader\. Do not fix a missing custom package by silently substituting an incompatible upstream package\. ### Establish the workspace once Start in the extracted directory that contains `seed-desk`\, `review-desk` and `package-lab`\. **Terminal shell—create the workbook workspace\:** ~~~sh EXAMPLES="$PWD" LAB="$(mktemp -d)" mkdir -p "$LAB/work" "$LAB/agent" export PI_CODING_AGENT_DIR="$LAB/agent" export PI_PROFILE= cd "$LAB/work" ~~~ Later commands assume these shell variables remain available\. This is a **reversible workspace**\, not complete isolation\: - `PI_CODING_AGENT_DIR` selects the lab’s agent directory\. - `--no-extensions` suppresses ambient extension\-factory discovery\, while explicit entries still load\. - Other discovery families\, environment credentials\, package installation and host startup activity have their own behavior\. - Neither an empty working directory nor `--no-session` is an OS security boundary\. The recorded isolated scenarios used an additional OS policy denying network access and restricting writes\. Ordinary reader launch commands below do not install that policy\. ### An extension is a factory\, not a command\-line program A module loaded with `-e` exports a **default function**\. OMP calls that function with `ExtensionAPI`\. **Complete TypeScript exercise—save as `lab-status.ts` in the lab working directory\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function labStatus(pi: ExtensionAPI): void { pi.setLabel("Workbook lab"); pi.on("session_start", (_event, ctx) => { pi.logger.debug("Workbook lab session started"); if (ctx.hasUI) { ctx.ui.notify("Workbook lab loaded.", "info"); } }); } ~~~ **Terminal shell—load that exercise\:** ~~~sh omp --no-extensions -e ./lab-status.ts ~~~ **Expected checkpoint\:** in a TUI\, the session\-start handler produces `Workbook lab loaded.` In a default headless context\, the notification is absent\; that absence is not a load failure\. Running `bun lab-status.ts` merely evaluates a module that exports a function\. It does not supply OMP’s extension runtime\. ### Registration first\, initialized actions later The lifecycle has two important phases\: 1. **Factory binding\:** register commands\, tools\, flags\, handlers\, renderers and fallback handlers\. 2. **Runtime initialization\:** the host wires session actions and UI\, then dispatches events and invocations\. Methods such as `sendMessage()`\, `appendEntry()`\, `getAllTools()` and `setModel()` depend on the initialized runtime\. Calling them during factory loading raises `ExtensionRuntimeNotInitializedError`\. An async factory is valid\. Seed Desk uses one to read `tool.txt` before registering a tool\. Async initialization does not make runtime actions available early\. Register providers at factory time if needed\: their registrations are queued for the model registry\. That is a special registration path\, not an exception allowing arbitrary session actions during loading\. ### Keep the lifetimes separate | Lifetime | What belongs here | What does not follow automatically | | --- | --- | --- | | Process | Loaded libraries\, process\-wide registries\, explicitly shared buses | One user\, one session or one authorization scope | | Module evaluation | Static fixtures and helper definitions | Fresh mutable state for every SDK session | | Factory binding | Closures created when the factory is called | Automatic reset on `/new` or session switching | | Session\/transcript | A session ID\, header and journal | A global shared database | | Current branch | The path from root to the active leaf | Every entry in the session file | | Invocation | The current handler\/tool context and abort signal | A context object safe to cache indefinitely | The Field Notes selection later demonstrates the distinction\: it survives a transcript change because the factory binding survives\. ### Trust is already being granted **Source\-backed\:** `ExtensionContext.isProjectTrusted()` always returns `true` in this build\. It is a compatibility method reflecting that project\-local inputs are already trusted by default\. It is not a prompt\, sandbox or per\-directory permission store\. Review the selected module’s entire import graph\. Package dependencies and helper modules have the same in\-process JavaScript authority as the entry\. **Exercise\:** move `pi.sendMessage()` into the factory body of a copy of `lab-status.ts`\. What should happen\? **Answer\:** loading should report an uninitialized\-runtime error\. Move the action into a handler\; do not add a delay and hope startup finishes first\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/loader.ts`\, `getExtensionFactory`\, `ExtensionRuntime`\, `ConcreteExtensionAPI`\; `packages/coding-agent/src/extensibility/extensions/runner.ts`\, `initialize`\, `createContext`\.* ## Seed Desk\: welcome and inventory Mara’s first goal is modest\: stop repeating the fictional seed desk’s opening hours\. Her obstacle is that a friendly human command alone would leave the agent without a supported way to retrieve the same information\. She chooses two entrances to one small domain\: a human command and a read\-only tool\. ### Milestone\: a welcoming desk for both readers **Starting state\:** no reservation state\, no inventory mutation and no external service\. Files\: - [Stage 1 entry]() - [Tool description]() - [Seed Desk instructions]() **Terminal shell—launch stage 1\:** ~~~sh omp --no-extensions --no-skills -e "$EXAMPLES/seed-desk/01-welcome/index.ts" ~~~ **Human OMP slash commands—enter in the composer\:** ~~~text /seeds welcome /seeds hours ~~~ The hours response is\: **Expected local output\:** ~~~text Our fictional desk opens Saturday, 10:00-12:00. No booking has been made. ~~~ The machine interface is `seed_welcome`\. **Model tool arguments—call `seed_welcome`\:** ~~~json {"op":"discover"} ~~~ **Model tool arguments—call `seed_welcome`\:** ~~~json {"op":"inspect","topic":"hours"} ~~~ The first operation advertises `discover` and `inspect`\, the topics\, scope and quiet flag in structured `details`\. The second returns the same hours text used by the slash command\. Important distinction\: `details` is useful to SDK callers\, hosts and renderers\. It is not automatically model\-visible\. This stage’s ordinary text content tells the model which topics it can inspect\; the quiet flag is in `details`\, not duplicated into that text\. #### What the code changes The async factory reads its description from a real adjacent file\. It registers\: - `seed_welcome`\, with `approval: "read"` and `loadMode: "essential"`\; - the boolean flag `seed-quiet`\; - a `session_start` notification\; - `/seeds`\, including argument completion\. It does **not** register a reservation operation\. **Exact excerpt—completion behavior in [stage 1’s entry]()\; not a standalone replacement file\:** ~~~ts getArgumentCompletions(prefix) { const matches = choices.filter(value => value.startsWith(prefix.trimStart())); // A completed sole match MUST release Enter to submit the command. if (matches.length === 1 && matches[0] === prefix.trim()) return null; return matches.length ? matches.map(value => ({ value: `${value} `, label: value })) : null; }, ~~~ Mara types `/seeds wel`\. The completion offers the full argument text `welcome `\. When `welcome` is already the sole exact match\, returning `null` lets Enter submit rather than continually reaccepting the completion\. A completion\-array equality test is helpful\, but it is not a terminal\-key\-dispatch test\. #### Inspect progress **Observed\:** - `wel` produced `welcome `\. - `welcome` and `welcome ` produced no completion\. - The tool’s greeting matched the headless command’s greeting\. - Quiet startup produced zero startup notices\. - A headless command produced one custom message\. The supplied Seed Desk proof simulated confirmation\/notification UI\. It did not exercise actual terminal autocomplete and Enter behavior\. #### Quiet is a startup choice\, not a permission Exit the stage and restart it with the flag\. **Terminal shell—suppress the startup notice\:** ~~~sh omp --no-extensions --no-skills -e "$EXAMPLES/seed-desk/01-welcome/index.ts" --seed-quiet ~~~ This suppresses only the startup notification\. Commands and tools still work\. Register flag names without the leading `--`\; use the leading `--` in the shell\. In this parser\, a boolean flag’s presence means `true`\. Do not assume `--seed-quiet=false` means false\; omit the flag to use its false default\. #### Failure and mode boundaries - An inspect request without a topic throws an error\. - An unknown human verb produces guidance and changes nothing\. - The tool checks its `AbortSignal` before doing work\. - With UI\, the command uses `notify()`\. - Without UI\, it uses `sendMessage(..., { triggerTurn: false })`\, so the answer is not lost in an inert notification\. - Reloading code is not accomplished by directly running the TypeScript file\. Restart the explicit launch when testing an edit\. **Exercise\:** ask the agent to reserve basil through `seed_welcome`\. **Checkpoint\:** it should report that no stock\-changing operation exists\, not invent `reserve` or attempt to invoke `/seeds`\. ### Milestone\: the desk gains a real query surface The next Saturday\, Mara’s fictional desk has three seed varieties\. Repeating a prose list has become awkward\: the agent needs stable IDs\, family filters and a clear error for an invented ID\. She replaces stage 1 with stage 2\. These stages are independent\, not cumulative imports\. Files\: - [Stage 2 entry]() - [Shared catalog functions]() - [Fictional inventory]() - [Tool description]() **Terminal shell—after exiting stage 1\:** ~~~sh omp --no-extensions --no-skills -e "$EXAMPLES/seed-desk/02-catalog/index.ts" ~~~ **Human OMP slash commands\:** ~~~text /seeds query /seeds query herb /seeds inspect basil-genovese ~~~ **Model tool arguments—call `seed_catalog`\:** ~~~json {"op":"query","family":"herb"} ~~~ **Model tool arguments—call `seed_catalog`\:** ~~~json {"op":"inspect","id":"basil-genovese"} ~~~ Stage 2 supports **`query` and `inspect` only**\. It does not have a `discover` operation merely because stage 1 had one\. #### One shared domain\, two entrances This is the complete small helper used by both interfaces\. **TypeScript source—[stage 2’s `catalog.ts`]()\:** ~~~ts import fixture from "./inventory.json"; export interface Seed { id: string; name: string; family: string; packets: number; } export const inventory: readonly Seed[] = fixture; export function inspect(id: string): Seed { const seed = inventory.find(item => item.id === id); if (!seed) throw new Error("Unknown seed ID. Query the catalog for valid IDs. Nothing changed."); return seed; } export function query(family?: string): readonly Seed[] { return family ? inventory.filter(seed => seed.family === family) : inventory; } export function summary(seeds: readonly Seed[]): string { return seeds.length ? seeds.map(seed => `${seed.id}: ${seed.name}, ${seed.packets} fictional packets (${seed.family})`).join("\n") : "No fictional seeds match that family."; } ~~~ **Expected output for the herb query\:** ~~~text basil-genovese: Genovese basil, 8 fictional packets (herb) ~~~ The tool returns that summary in `content`\, and records in\: - `details.scope: "fictional-fixture"` - `details.seeds` This is better than asking the agent to scrape a notification\. The tool gives it stable targets\, while the host gets structured records\. #### Inspect progress and failure **Observed\:** the real loader\, runner and intercepted tool adapter returned only `basil-genovese` for the herb query\. Slash\/tool summaries matched\. Unknown inspection IDs threw\. A pre\-aborted call was refused through the intercepted path\. The family match is exact and case\-sensitive\. An unknown family gives an empty query result\; an unknown inspect ID is an error\. No read appends reservation state\. **Exercise\:** compare these two requests\: **Model tool arguments—call `seed_catalog`\, one request at a time\:** ~~~json {"op":"query","family":"unknown-family"} ~~~ ~~~json {"op":"inspect","id":"unknown-seed"} ~~~ **Answer\:** the query reports no matches\. The inspection fails because it promises to identify one existing target\. ### What changes next\? Mara can now ask\, “Which herbs are available\?” But the eight packets are still a static fixture\. To represent a reservation\, she needs a state model\, an ownership scope and a concurrency check—not merely another button\. That is the next chapter\. *Source\, snapshot 2026\-08\-29\: the linked Seed Desk files\; `packages/coding-agent/src/extensibility/extensions/types.ts`\, `ToolDefinition`\; `packages/coding-agent/src/extensibility/extensions/wrapper.ts`\, `RegisteredToolAdapter`\, `ExtensionToolWrapper`\.* ## Seed Desk\: reservations on the active branch Mara wants the agent to help hold fictional packets while she works through a conversation\. Her obstacle is no longer retrieval\. It is stale decisions\: a reservation based on an old availability view must not silently overwrite a newer one\. She chooses **current\-branch reconstruction plus revision\-checked actions**\. This is still not a stock system\. Separate sessions and processes do not coordinate physical inventory\. ### Milestone\: a confirmed human reservation **Starting state\:** the stage\-3 fixture has eight basil packets\, five bean packets and three marigold packets\. Reservations are empty\. Agent actions are disabled\. Files\: - [Stage 3 entry]() - [Reservation domain and reconstruction]() - [Inventory]() - [Package manifest]() - [Tool description]() For a standalone download\, install the matching dependencies in this stage\. This is package\-manager work and may access your registry\. If those custom versions are unavailable\, use the matching installed source workspace instead\. **Terminal shell—dependency installation\, then launch\:** ~~~sh cd "$EXAMPLES/seed-desk/03-reservations" bun install cd "$LAB/work" omp --no-extensions --no-skills -e "$EXAMPLES/seed-desk/03-reservations/index.ts" --session "$LAB/seed-session.jsonl" ~~~ **Human OMP slash commands\:** ~~~text /seeds query /seeds reserve basil-genovese 2 ~~~ Cancel the first confirmation\. Then repeat the reservation command and confirm\. **Expected state after confirmation on a fresh branch\:** ~~~text basil-genovese: 6 available, 2 reserved ~~~ The query also supplies a revision\. Its concrete value comes from your session\, so it will not match a printed workbook token\. #### What changed in the code\? The domain separates\: - the immutable fictional fixture\; - a persisted snapshot containing `version`\, `agentEnabled` and reservation `quantities`\; - a derived revision\; - domain validation in `changeReservation()`\. A successful change appends a custom entry named `seed-desk-state-v1`\. It then reconstructs state\, refreshes the status and emits `workbook:seed-desk:changed`\. The extension does not write a separate inventory file\. #### Why the second revision check matters A confirmation dialog is an `await`\. During that wait\, another action or a session\-tree movement may occur\. **Exact excerpt—post\-dialog check in [stage 3’s entry]()\; read in its surrounding command handler\:** ~~~ts // Re-read after the dialog: another action or tree navigation may have happened. const current = reconstruct(ctx); if (current.revision !== initial.revision) throw new DeskRefusal("stale-revision", "The branch changed during confirmation; try again."); const snapshot: Snapshot = grant ? { version: 1, quantities: current.quantities, agentEnabled: value === "on" } : changeReservation(current, verb, value ?? "", Number(count), initial.revision, "human"); const saved = commit(ctx, snapshot, grant ? `agent-${value}` : verb); ~~~ After validation\, the commit path has no asynchronous gap before `appendEntry()`\. That prevents JavaScript invocations from interleaving inside this small validation\-and\-append segment\. It is not a cross\-process transaction or a durable database lock\. **Observed\:** cancellation appended no state entry\. A confirmation\-race scenario changed state while the dialog was open\; the waiting human reservation was then refused\, leaving bean reservations at zero\. **Exercise\:** reserve two basil packets\, then cancel a request to release one\. **Checkpoint\:** basil remains at two reserved\. Cancellation before commit is not a release\. ### Milestone\: grant the agent a bounded domain capability Mara now wants the agent to make fictional reservations without opening a dialog for every domain decision\. She does not want the tool to grant itself that authority\. **Human OMP slash command\:** ~~~text /seeds agent on ~~~ Confirm the scoped dialog\. The model\-facing interface is now `seed_desk`\. **Model tool arguments—call `seed_desk`\:** ~~~json {"op":"discover"} ~~~ ~~~json {"op":"query"} ~~~ ~~~json {"op":"inspect","id":"basil-genovese"} ~~~ The tool supports\: | Operation | Purpose | | --- | --- | | `discover` | Explain supported operations\, action prerequisites and the current state revision | | `query` | Return valid IDs\, available\/reserved quantities and a revision\; optionally filter by exact family | | `inspect` | Read one exact seed ID | | `act` | Reserve or release a positive integer quantity using the current revision and a human\-granted permission | The structured response includes `ok`\, `scope`\, and\, when available\, `revision`\, `agentEnabled`\, `code` and `data`\. The text response includes the domain outcome and revision\. Do not assume every field in `details`\, including permission status\, is automatically sent to the model\; a host exposing structured details has more information than ordinary text\-only model replay\. #### Ask the agent for the right sequence **Agent request—use in an authorized model session\:** ~~~text Use seed_desk to query current fictional availability. Choose bean-scarlet only if at least one packet is available. Reserve one packet using the exact revision returned by that query. If the operation is refused, explain the refusal and query again before deciding whether another action is appropriate. Do not retry blindly. ~~~ A model session requires your normal provider configuration and may incur charges\. The recorded example checks did not use provider inference\. For readers inspecting the schema\, this is the action shape\: **Illustrative model\-tool argument template—not usable until the revision is replaced with the actual latest returned value\:** ~~~json { "op": "act", "action": "reserve", "id": "bean-scarlet", "packets": 1, "expectedRevision": "COPY_THE_LATEST_RETURNED_REVISION" } ~~~ A successful action returns a new revision\. Reusing the old one is a refusal\, not a second reservation\. #### Refusals are part of the interface | Condition | Domain code | Correct next action | | --- | --- | --- | | No human grant | `agent-disabled` | Ask the human whether to enable the domain capability | | Old revision | `stale-revision` | Query again\; reconsider the intended action | | Invented ID | `invalid-target` | Use an ID from query results | | Zero\, negative or unsafe quantity | `invalid-quantity` | Supply a positive safe integer | | More than available | `insufficient-availability` | Reduce the quantity or choose another item | | Release exceeds this branch’s holding | `insufficient-reservation` | Inspect current reservations | | Incompatible or invalid persisted snapshot | `corrupt-state` | Stop and navigate to a valid earlier branch | | Human mutation without UI | `ui-required` | Use a supported interactive confirmation path | The schema can reject malformed inputs before the domain runs\. The domain also validates action\, quantity and target\. These are complementary checks\. Seed Desk returns ordinary domain refusals as `details.ok: false` with explanatory text\. It does not mark every such refusal as a thrown transport\/tool error\. An SDK caller must inspect `ok`\, not merely whether a promise resolved\. **Observed\:** the recorded checks covered disabled authority\, stale revision\, invalid target\, invalid quantity\, insufficient availability and excess release without appending state\. #### Host approval is a separate gate The mixed read\/write `seed_desk` tool is conservatively declared `approval: "write"` for all operations\. That host approval tier and Mara’s `/seeds agent on` grant are different\: - Host approval controls whether the wrapped tool call may execute under the configured approval policy\. - Seed Desk’s grant controls whether its own `act` operation may mutate this domain state\. - Neither prevents other extension JavaScript or independently permitted tools from acting elsewhere\. Do not weaken a host’s approval configuration merely to make a test pass\. ### Milestone\: reconstruct the branch\, not the whole file Mara tries a different plan from an earlier point in the conversation\. Her first instinct is to scan all saved entries and select the latest snapshot\. That would mix sibling branches\. Instead\, `reconstruct()` walks `ctx.sessionManager.getBranch()`\. Its revision is\: - session ID plus `root`\, before any Seed Desk state entry\; - session ID plus the latest Seed Desk state entry’s ID afterward\. Consequences\: - Ordinary conversation does not stale the domain revision\. - A reservation or permission change does\. - A sibling state snapshot cannot be reused as the current branch’s revision\. - A new session has a distinct identity\. - A branch inherits the reservations and grants in its ancestry\. The domain validates every matching stored snapshot it encounters\. It does not skip a corrupt Seed Desk entry and silently trust a later one\. #### Inspect the journal **Terminal shell—inspect only the lab’s Seed Desk state records\:** ~~~sh grep '"customType":"seed-desk-state-v1"' "$LAB/seed-session.jsonl" ~~~ This is a journal inspection\, not a request to edit the journal while OMP owns it\. Exit and reopen with the same launch command and session path\. Then query again\. **Observed\:** - Real JSONL entries survived reopen\. - The restored reservation was two packets\. - The revision was preserved\. - Rewinding before a reservation showed zero reserved\. - A sibling branch could hold one packet while the original branch retained two\. - A sibling revision token was rejected\. - A fresh session had no carried reservation and agent authority was off\. A plain leaf movement is not the same thing as a newly appended branch record\. The session loader reconstructs its position from journal structure\; do not assume every transient UI navigation choice is independently durable without a subsequent journal change\. Always query after reopen\. #### Revoke deliberately **Human OMP slash command\:** ~~~text /seeds agent off ~~~ This also asks for confirmation and appends a new snapshot\. Unlike Review Desk’s in\-memory revocation later\, **Seed Desk refuses both grant and revoke commands without UI**\. A persisted grant may therefore still permit tool acts after headless reopen\, subject to host approval\. That is the supplied stage’s exact policy\, not a general recommendation for all applications\. ### Persistence and cancellation limits `appendEntry()` stores extension state outside model\-visible conversation\. It returns no persistence receipt\. The current file session manager normally hands completed appends to the OS synchronously once persistence is materialized\, but it does not provide a power\-loss\/fsync guarantee through this extension API\. Storage failures can be latched and surfaced by the host\. The Seed Desk checks did not exercise disk\-failure recovery\. Before commit\, cancellation changes nothing\. After commit\, cancellation cannot undo a reservation\. Query before retrying\. Status notifications and bus events do not start an agent turn\. The optional `renderResult()` is presentation only\; it does not replace the result’s text and structured details\. **Exercise\:** should a real multi\-user seed library use this journal as its stock database\? **Answer\:** no\. It would need a shared authoritative store\, atomic stock operations\, durable request identity and coordination across users and processes\. This stage deliberately teaches fictional branch\-local reservations\. *Source\, snapshot 2026\-08\-29\: linked stage\-3 files\; `packages/coding-agent/src/session/session-manager.ts`\, `ReadonlySessionManager`\, `appendCustomEntry`\, `getBranch`\; `packages/coding-agent/src/tools/approval.ts`\, `resolveApproval`\.* ## Review Desk\: edit and decide locally Imani prepares a fictional release note\. Her goal is to let a person review the wording before it is treated as accepted\. Her obstacle is that “accept” is often confused with “publish\.” She makes a narrower decision\: acceptance will be **a local status change only**\. The extension contains no send\-to\-service or publish operation\. Review Desk is one complete downloadable module set\. The milestones below explain its progression\; they are not separate downloadable versions\. ### The project Files\: - [Entry and runtime coordination]() - [Domain transitions]() - [Native panel and bounded text]() - [UI and tool copy]() - [Fictional release\-note fixture]() - [Story and protocol notes]() **Terminal shell—launch the complete Review Desk\:** ~~~sh omp --no-extensions -e "$EXAMPLES/review-desk/index.ts" --session "$LAB/review-session.jsonl" ~~~ The compatible loader resolves the runtime TUI import\. If that fails\, investigate host\/package compatibility rather than replacing `panel.ts` with an inert mock\. ### Milestone\: inspect without changing the draft **Starting state\:** fixture text\, revision `0`\, status `draft`\, no agent grant\. **Human OMP slash command\:** ~~~text /review-desk show ~~~ **Model tool arguments—call `review_desk`\:** ~~~json {"op":"discover"} ~~~ ~~~json {"op":"inspect"} ~~~ ~~~json {"op":"query"} ~~~ `inspect` returns the complete draft\, status\, revision and authorization status\. `query` is smaller\: revision\, status\, authorization\, whether a dialog is busy\, and the extension mode\. **Expected query result in a fresh TUI session\:** ~~~json { "revision": 0, "status": "draft", "authorized": false, "busy": false, "mode": "tui" } ~~~ The tool duplicates its structured result as JSON text in `content`\, so its machine contract is also model\-visible\. `show` refreshes the status\/widget and sends a custom review message\. It does not increment the draft revision\, but it is not completely journal\-inert\: the custom message is conversation data\. **Observed\:** the loaded SDK tool exposed `discover`\, `inspect`\, `query` and `act`\, and refused an unauthorized mutation without changing the draft\. **Exercise\:** is a status widget a substitute for `inspect`\? **Answer\:** no\. The widget is a short human summary\. `inspect` is the supported way to retrieve the actual domain state\. ### Know the mode before opening a review The same property can exist in every mode while doing useful work in only some of them\. | Host | What Review Desk can use | Degraded behavior | | --- | --- | --- | | TUI | Standard editor\/selector dialogs\, status\, string widget\, custom message renderer and native overlay | Requires real terminal presentation and input | | RPC | Editor\, confirm and labeled select requests answered by a connected client\; passive status\/widget frames | No native component factory or synchronous composer read | | ACP | The supplied ACP adapter exposes semantic forms and initializes extensions with `mode: "rpc"` | Form support depends on negotiated `elicitation.form`\; terminal presentation remains unavailable | | Default print\/JSON context | Read tools and explanatory custom messages | The example refuses its interactive review\, overlay and delegation paths | **Source\-backed ACP nuance\:** the ACP extension context can report UI availability even when form elicitation is unsupported\. Its dialog methods then return defaults\. Because Review Desk accepts `mode: "rpc"`\, an ACP `review` with no form capability can receive `undefined` from `editor()` and record a **cancelled review outcome**\. Delegation receives false and grants nothing\. That differs from the explicit print\-mode guard\, which changes neither draft nor authorization\. The recorded Review Desk protocol scenario exercised RPC\, not a Review Desk\-specific ACP client flow\. ### Milestone\: edit and accept locally Imani asks for a review rather than directly replacing the draft\. **Human OMP slash command\:** ~~~text /review-desk review ~~~ The standard flow is\: 1. Open a multiline editor with sanitized draft text\. 2. Edit the note\. 3. Submit the editor\. 4. Choose **Accept locally**\, **Reject**\, or **Cancel**\. In the TUI multiline editor\, Enter inserts a newline\. Submit with the editor’s configured follow\-up chord—by default Ctrl\+Q or Ctrl\+Enter\. The core editor also exposes its normal Ctrl\+G external\-editor shortcut\; this extension does not invoke an external editor programmatically\. For the following checkpoint\, use this text\: **Text to enter in the review editor\:** ~~~text Release 1.4 A human-reviewed local note. Nothing is published. ~~~ Choose **Accept locally**\. **Observed RPC checkpoint\:** the edited text became revision `1`\, status `accepted`\, with `authorized: false`\. The selector carried labels and aligned descriptions\. Status and string\-widget frames were emitted\. The original `release-note.txt` fixture was not overwritten\. The draft is reconstructed from custom session entries named `workbook-review-desk-state`\. ### Milestone\: rejection and cancellation are distinct outcomes Imani next tries an edit she does not like\. Rather than hiding what happened\, the domain records a review outcome while preserving the pre\-dialog text\. | Human outcome | Stored text | Status | Revision | | --- | --- | --- | --- | | Accept locally | Edited text | `accepted` | Increases once | | Reject | Original pre\-dialog text | `rejected` | Increases once | | Escape from editor | Original pre\-dialog text | `cancelled` | Increases once | | Cancel or dismiss selector | Original pre\-dialog text | `cancelled` | Increases once | **Observed\:** after the accepted revision\, rejection produced revision `2`\, and editor cancellation produced revision `3`\. Both retained the accepted note’s text\. This is an important vocabulary distinction\: - **Cancel a review\:** record that the review was cancelled\; revision increases\. - **Abort presentation because authority was invalidated or the session moved\:** do not record a review on a different branch\. - **Revoke agent authority\:** leave draft text\, status and revision unchanged\. Blank or over\-12\,000\-character replacement text fails domain validation\. The tool additionally constrains its `text` parameter\. Rejection and cancellation cannot be used to smuggle replacement text through the domain function\. **Exercise\:** after accepting revision `1`\, open the editor\, replace all text\, submit\, then choose Reject\. Which text remains\? **Answer\:** the pre\-dialog revision\-1 text\, now with status `rejected` and revision `2`\. ### Milestone\: authorize one agent action on one revision Imani wants the agent to shorten the draft once\. She does not want a permanent permission recovered from the transcript\. **Human OMP slash command\:** ~~~text /review-desk delegate ~~~ Confirm the dialog\. The grant is\: - in memory only\; - associated with the current session ID\; - associated with the inspected numeric revision\; - consumed by a successful mutation\. The tool cannot grant itself permission\. If you followed the accepted\/rejected\/cancelled sequence and `inspect` reports revision `3`\, the following is an exact next action\. **Model tool arguments—call `review_desk` only after checking that the current revision is `3` and the human grant is active\:** ~~~json { "op": "act", "action": "revise", "expectedRevision": 3, "text": "Agent revision, still local." } ~~~ **Observed result\:** ~~~json { "revision": 4, "status": "draft", "text": "Agent revision, still local.", "authorized": false, "published": false } ~~~ If your revision differs\, inspect and use that revision instead\. Never substitute a guessed counter\. Other agent actions are `accept`\, `reject` and `cancel`\. They preserve the inspected text and do not accept a `text` argument\. To change text\, use `revise`\. A stale action fails without mutation\. A failed stale attempt does not consume the valid grant\; a successful action does\. A second successful attempt requires another human grant\. An open dialog blocks tool mutations with `Review dialog open. Nothing changed.` ### Milestone\: revocation defeats a late positive answer The first implementation of revocation had a classic asynchronous bug\: clearing the current grant did not invalidate a confirmation already awaiting a response\. A late positive answer could restore authority\. Imani’s decision changes from “clear the value” to “retire the pending decision\.” **Exact excerpt—authority invalidation in [Review Desk’s entry]()\:** ~~~ts function invalidateAuthority(): void { generation++; grant = undefined; pending?.abort(); } pi.on("session_before_switch", invalidateAuthority); pi.on("session_before_branch", invalidateAuthority); pi.on("session_before_tree", invalidateAuthority); ~~~ The handler remembers the generation before awaiting the dialog\. **Exact excerpt—the delegation result is accepted only in the same generation\:** ~~~ts if (verb === "delegate") { const approved = await ctx.ui.confirm(copy.grantTitle, copy.grantMessage, { signal: controller.signal }); if (epoch !== generation) return; grant = approved ? { sessionId: ctx.sessionManager.getSessionId(), revision: state.revision } : undefined; present(ctx, state); ctx.ui.notify(approved ? `One agent change authorized for revision ${state.revision}.` : "No agent change authorized. Draft unchanged."); return; } ~~~ **Human OMP slash command\:** ~~~text /review-desk revoke ~~~ **Observed correction\:** revoking during a real pending RPC confirmation emitted a matching cancel frame\. A delayed positive response to the retired request did not restore authority\. The draft was unchanged\, and `busy` became false after the pending handler settled\. The same invalidation machinery handles session switching\, branching\, tree navigation and shutdown\. A same\-session reload that uses the switch path also invalidates authority\. #### Honest limits - The numeric revision is a domain counter\, not Seed Desk’s session\-plus\-entry\-ID token\. - Navigation hooks invalidate the grant so sibling revisions cannot retain it through the supported flow\. - This is not protection against arbitrary in\-process code rewriting domain entries\. - `stateFor()` skips stored entries that fail `isReviewState()`\. Unlike Seed Desk\, it does not fail closed on every malformed matching snapshot\. Treat this as a small teaching fixture\, not a complete corruption\-recovery system\. **Exercise\:** revoke while a delegate confirmation is pending\, then have the client answer the old request positively\. **Checkpoint\:** no authorization\, no draft mutation\, and no revived dialog\. *Source\, snapshot 2026\-08\-29\: linked Review Desk files\; `packages/coding-agent/src/modes/rpc/rpc-mode.ts`\, `requestRpcDialog`\, `requestRpcEditor`\; `packages/coding-agent/src/modes/acp/acp-agent.ts`\, `createAcpExtensionUiContext`\, `#configureExtensions`\.* ## Review Desk\: a native panel and portable dialogs Imani’s standard editor works in both terminal and RPC review flows\. Now she wants a compact local panel for quickly accepting or rejecting a long note\. Her obstacle is portability\. A terminal component is not automatically a remotely inspectable form\. She keeps the domain tool and standard dialogs\, then adds the panel as an optional TUI presentation\. ### Milestone\: open a focused native overlay **Human OMP slash command—TUI only\:** ~~~text /review-desk overlay ~~~ The supplied `ReviewPanel` supports\: - Up\/Down to scroll\; - `a` to accept locally\; - `r` to reject\; - Escape to cancel\. The overlay does not edit the note\. Accepting from it retains the existing text\. The body shows an eight\-line scrolling window\. Text rows are bounded to the smaller of the available width and 100 columns\. **Exact excerpt—untrusted text handling in [panel\.ts]()\:** ~~~ts export function safeText(text: string): string { return replaceTabs(Bun.stripANSI(text)).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, ""); } ~~~ The note is data\. It is not trusted ANSI styling\, terminal control\, clipboard control or bidirectional layout instruction\. #### Inspect progress **Observed\:** - The loader\-registered expanded custom renderer was checked at widths `0`\, `1`\, `4`\, `24`\, `80` and `160`\. - Every rendered row stayed within the applicable bound\. - Injected control sequences were removed\. - Real controller\/TUI focus dispatch through a terminal emulator accepted the overlay\. - Cleanup hid and disposed it\. - The surrounding composer text remained unchanged\. - Aborting a custom UI signal rejected the promise and removed the overlay\. This was real controller and terminal\-emulator behavior with a surrounding mode fixture\. It was not a physical\-terminal visual audit or a full Seed Desk composer smoke\. **Exercise\:** open the overlay\, scroll\, then Escape\. **Checkpoint\:** the panel closes\; the domain records a cancelled review\. An externally aborted presentation caused by revocation\/navigation instead must not commit to another branch\. ### Choose semantic dialogs before custom controls The portable baseline is\: | Method | Result | Cancellation distinction | | --- | --- | --- | | `select(title, options, dialogOptions?)` | Selected **label**\, even for an option object | `undefined` on dismissal\/cancellation | | `confirm(title, message, dialogOptions?)` | Boolean | Decline and cancellation both resolve false | | `input(title, placeholder?, dialogOptions?)` | Text | `undefined` means no answer\; an empty string is a separate value | | `editor(title, prefill?, dialogOptions?, editorOptions?)` | Multiline text | `undefined` means cancelled | | Optional `askDialog(questions, dialogOptions?)` | A structured ask result | Can be cancelled\, submitted\, or redirected to chat | `input`’s second argument is a placeholder\, not an initial document\. `editor`’s second argument is the prefill\. Its fourth argument may set `promptStyle`\. Feature\-detect `askDialog`\; do not assume it exists because `hasUI` is true\. ### Rich ask data A rich ask question contains\: - `id`\: stable question identity\; - `question`\: full question text\; - optional `header`\; - `options`\; - optional `multi`\; - optional zero\-based `recommended`\. Each option has `label`\, optional `description`\, and optional `preview`\. A submitted result has `kind: "submit"` and ordered `results`\. Each result item contains\: - `id`\, `question`\; - `options` as labels\; - `multi`\; - `selectedOptions`\; - optional `customInput`\, `note`\, `timedOut`\. `kind: "chat"` means the user chose to discuss the question\. It is not cancellation and it is not an answer\. ACP’s rich ask adapter can produce recommended fallback answers marked `timedOut: true`\. A permission system must not interpret such a fallback as explicit consent\. Descriptions and previews are presentation capabilities\, not a guarantee that every protocol adapter transmits them\. For example\, the supplied ACP basic select translates labels to an enum\; its rich ask path carries richer descriptions\. ### Dialog options are not universally portable `ExtensionUIDialogOptions` includes all of the following\: | Family | Members | Use | | --- | --- | --- | | Cancellation and timing | `signal`\, `timeout`\, `onTimeout`\, `onTimeoutStart`\, `onTimeoutReset` | Cancel work and observe a host\-managed timeout | | Initial selector presentation | `initialIndex`\, `outline`\, `helpText` | Position and explain a TUI selector | | Selector actions | `onLeft`\, `onRight`\, `onExternalEditor` | TUI\-specific callbacks | | Selection markers | `selectionMarker`\, `checkedIndices`\, `markableCount` | Radio\/checkbox presentation for leading options | Timeouts are milliseconds\. `timeoutStartsOnPresentation` is an optional UI capability\: the TUI sets it true so a queued selector’s timeout need not expire before it appears\. Do not infer that every option applies to every method\. In particular\, the supplied standard multiline editor path honors cancellation but does not implement the same dialog timeout plumbing as the selector\/input paths\. ### RPC is semantic UI\, not a terminal The current wired RPC extension context reports `hasUI: true` and `mode: "rpc"`\. This outranks the stale type comment saying RPC has no UI\. The protocol uses requests and correlated responses\. **RPC client input—request the human review command\:** ~~~json {"type":"prompt","id":"review-1","message":"/review-desk review"} ~~~ The client must continue reading output\, present the emitted editor\/selector requests\, and reply using each request’s actual ID\. It must not wait for the review to finish before processing the dialog requests needed to finish it\. **Illustrative RPC response shapes—`dialog-1` represents an ID received from the server\, not a reusable workbook ID\:** ~~~json {"type":"extension_ui_response","id":"dialog-1","value":"Accept locally"} ~~~ ~~~json {"type":"extension_ui_response","id":"dialog-1","confirmed":true} ~~~ ~~~json {"type":"extension_ui_response","id":"dialog-1","cancelled":true} ~~~ Use the appropriate variant\, not all three\. RPC specifics\: - Select sends string `options`\; optional `optionDetails` align descriptions by position\. - Select returns a label\, not an index\. - Select\, confirm and input transmit timeout information\. - Editor transmits `title`\, `prefill` and optional `promptStyle`\; it has no timeout field or local editor timeout scheduler in this adapter\. - Aborting an active dialog emits `method: "cancel"` with `targetId` equal to the original request ID\. - Pre\-aborted signals suppress presentation\. - Disconnect rejects pending and future requests\. - Local select\/confirm\/input timer expiry can settle without a cancel frame\, so clients must honor the transmitted timeout too\. RPC supports fire\-and\-forget notifications\, status\, string\-array widgets and editor\-text requests\. Title emission is opt\-in through `PI_RPC_EMIT_TITLE=1`\. It does not serialize TUI component factories\. `custom()` returns without invoking the factory\. Component widgets\, terminal listeners\, custom editor replacement and autocomplete factories are unsupported there\. ### Passive presentation is not persistence | UI method | Useful role | Current implementation boundary | | --- | --- | --- | | `notify` | Brief result or warning | Not a durable domain record | | `setStatus(key, text)` | Small named status indicator | Clear with `undefined` | | `setWorkingMessage(message?)` | Streaming activity wording | TUI support\; RPC\/ACP inert | | `setWidget(key, content, options?)` | Summary above\/below editor | TUI supports strings or factories\; RPC supports strings only | | `setTitle` | Terminal\/window title | Not the persisted session name | | `setFooter`\, `setHeader` | Advertised component replacement surfaces | No\-op in the supplied TUI controller\, as well as RPC\/ACP | | `custom(factory, options?)` | Focused terminal component | Guard with `ctx.mode === "tui"` | For string widgets\, the TUI takes the first ten supplied strings and adds a truncation notice when necessary\. This is not a promise that arbitrary long strings wrap into only ten terminal rows\. `ExtensionCustomOptions` contains\: - `overlay`\; - static or lazy `overlayOptions`\; - `onHandle`\, receiving an overlay handle\; - `signal`\. A component should implement `render(width)` and `invalidate()`\, optionally input handling and `dispose()`\. Cleanup must be idempotent\. Review Desk’s panel becomes inert after disposal\. ### What changes next\? If Imani needs screen\-reader\-friendly or remotely operated review controls\, she should extend the **semantic domain interface** or use host\-supported forms\. A custom terminal drawing does not become accessible merely because it is visible\. `review_desk inspect/query/act` is the agent\-facing interface\. The panel is one human\-facing view of that interface\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/types.ts`\, UI interfaces\; `packages/coding-agent/src/modes/controllers/extension-ui-controller.ts`\, `showHookCustom`\, `#presentDialog`\; `packages/coding-agent/src/modes/rpc/rpc-mode.ts`\; linked Review Desk panel\.* ## Editors\, themes and composer shapes Luis likes Review Desk’s separation between data and presentation\. His next goal is a more comfortable authoring environment\: a phrase shortcut\, a theme picker and a quieter composer frame\. He chooses independent UI conveniences rather than changing the review tool’s meaning\. The examples in this chapter are **new complete exercises**\, not additional files in the observed downloadable suite\. ### Milestone\: insert text without submitting it **Complete TypeScript exercise—save as `phrase-key.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function phraseKey(pi: ExtensionAPI): void { pi.registerShortcut("ctrl+shift+y", { description: "Paste a fictional-observation prefix", handler(ctx) { if (ctx.mode !== "tui") return; ctx.ui.pasteToEditor("Fictional observation: "); }, }); } ~~~ **Terminal shell—from the directory containing that exercise\:** ~~~sh omp --no-extensions -e ./phrase-key.ts ~~~ **Expected checkpoint\:** the key chord pastes text through the editor’s paste handling\. It does not submit a prompt or call a provider\. The custom host already uses `ctrl+shift+x` for its built\-in autoresearch overlay\. This exercise uses `ctrl+shift+y` instead\: a valid chord can still lose to a later registration\. Verify the final handler in your host\, not merely that your factory registered it\. `setEditorText()` replaces the editor text\. `pasteToEditor()` follows the TUI paste path\, including large\-paste handling\. `getEditorText()` reads the current TUI text\. RPC’s `pasteToEditor()` falls back to a `set_editor_text` request\. Its synchronous `getEditorText()` returns an empty string\; the remote host must track its own composer state\. **Exercise\:** should a timer call `pasteToEditor()` to force an agent turn\? **Answer\:** no\. Editor mutation is not prompt submission\. Use an explicit message API if an agent turn is intended\, with the appropriate ownership and cost policy\. ### Milestone\: select a theme that actually exists Luis does not hard\-code a theme name or invent a theme\-file schema\. He asks the host for its available themes\. **Complete TypeScript exercise—save as `theme-picker.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function themePicker(pi: ExtensionAPI): void { pi.registerCommand("workbook-theme", { description: "Choose an available TUI theme", async handler(_args, ctx) { if (ctx.mode !== "tui") { pi.sendMessage( { customType: "workbook.theme", content: "Theme selection requires the TUI.", display: true }, { triggerTurn: false }, ); return; } const themes = await ctx.ui.getAllThemes(); const choice = await ctx.ui.select("Workbook theme", themes.map(theme => theme.name)); if (choice === undefined) return; const result = await ctx.ui.setTheme(choice); ctx.ui.notify( result.success ? `Theme selected: ${choice}` : result.error ?? "Theme selection failed.", result.success ? "info" : "warning", ); }, }); } ~~~ **Human OMP slash command\, after loading the file\:** ~~~text /workbook-theme ~~~ `getTheme(name)` loads a theme without selecting it\. `ui.theme` is the current styling object\. Although the type permits `setTheme(Theme)`\, the supplied TUI implementation accepts names and returns failure for a direct theme object\. RPC and ACP return theme\-switching failures and no available theme list\. For authoring a new declarative theme file\, start from the matching host’s actual theme schema and a real theme file\. That schema is not included in the supplied extension evidence\, so this workbook does not invent theme JSON keys\. **Exercise\:** cancel the picker\. **Checkpoint\:** no theme change\. A present method or a successful headless no\-op would not prove theme switching\. ### Milestone\: register a composer shape A composer shape owns the editor’s frame\, not its domain state\. **Complete TypeScript exercise—save as `workbook-dock.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; import type { ComposerStyle } from "@oh-my-pi/pi-tui"; const style: ComposerStyle = { id: "workbook-field-dock", sideBorders: false, verticalChrome: 1, statusAttachment: "none", bottomBar: "full", bottomBarGap: true, defaultPromptGutter: "> ", defaultPaddingX: () => 0, sideChromeWidth: () => 0, renderTop: ({ box, width, borderColor }) => borderColor(box.horizontal.repeat(width)), renderRow: ({ gutter, text, pad }) => [gutter + text + pad], renderBottom: () => undefined, }; export default function workbookDock(pi: ExtensionAPI): void { pi.registerComposerShape({ label: "Workbook Field Dock", description: "A single rule above the prompt", style, }); } ~~~ Load it explicitly\, then choose **Workbook Field Dock** in Appearance → Composer Shape\. Registration adds a choice\; it does not automatically select it\. The shape contract includes\: - `id`\, persisted as `composer.shape`\; - `sideBorders`\, which affects cursor reserve\, IME behavior and scrollbar layout\; - `verticalChrome`\, the exact fixed chrome\-row count\; - `statusAttachment`\: `top-border`\, `top-rule-chip` or `none`\; - `bottomBar`\: `none`\, `left` or `full`\; - `bottomBarGap`\; - `defaultPromptGutter`\; - `defaultPaddingX()` and `sideChromeWidth()`\; - `renderTop()`\, `renderRow()` and `renderBottom()`\. Renderer contexts supply width\, padding\, box glyphs and border\/accent\/surface styling functions\. Row contexts also supply the already\-rendered `gutter`\, `text`\, `pad`\, last\-row information\, cursor overflow\, IME\-safe\-tail state and scrollbar\-thumb state\. Preserve those prepared content pieces\. Do not reflow or arbitrarily truncate them inside frame code\. Normal rows must occupy the expected visible width\; ANSI bytes are not visible columns\. Built\-in IDs cannot be replaced\: `box`\, `claude`\, `pi`\, `borderless`\, `rule`\, `field`\, `rail`\. If the configured extension shape is unavailable\, the editor falls back to `box`\. **Exercise\:** test the shape at a narrow width and with a long line ending at the cursor\. **Checkpoint\:** no unexpected wrapping caused by frame\-width miscalculation\. A pure `renderRow()` unit test alone does not establish live editor\/IME behavior\. ### Milestone\: replace the editor only when a shortcut is insufficient A custom editor must be a **`CustomEditor` subclass**\, not merely a plain TUI `Editor` or an arbitrary component\. The host expects application action keys and callbacks\. This source\-checkout exercise uses the supplied class’s exact repository location\. Save it at the matching repository root and use a host built from that same checkout\; do not mix a copied source class with an unrelated binary\. **Complete TypeScript source\-checkout exercise—save as `workbook-editor.ts`\:** ~~~ts import type { ExtensionAPI } from "./packages/coding-agent/src/extensibility/extensions/types"; import { CustomEditor } from "./packages/coding-agent/src/modes/components/custom-editor"; import { matchesKey } from "@oh-my-pi/pi-tui"; class FictionalEditor extends CustomEditor { override handleInput(data: string): void { if (matchesKey(data, "ctrl+shift+y")) { this.insertText("[fictional] "); this.tui?.requestRender(); return; } super.handleInput(data); } } export default function workbookEditor(pi: ExtensionAPI): void { pi.registerCommand("workbook-editor", { description: "Use the fictional-prefix editor: on | off", async handler(args, ctx) { if (ctx.mode !== "tui") { ctx.ui.notify("Custom editors require the TUI.", "warning"); return; } if (args.trim() === "on") { ctx.ui.setEditorComponent( (tui, theme, keybindings) => new FictionalEditor(tui, theme, keybindings), ); } else if (args.trim() === "off") { ctx.ui.setEditorComponent(undefined); } else { ctx.ui.notify("Use /workbook-editor on or /workbook-editor off.", "warning"); } }, }); } ~~~ **Terminal shell—from the matching source repository root\:** ~~~sh omp --no-extensions -e ./workbook-editor.ts ~~~ Do not load this and the phrase\-key exercise together\: they intentionally demonstrate two ways to own the same chord\. **Expected checkpoint\:** ordinary typing and application shortcuts still pass to `super.handleInput()`\. Turning the editor off restores the default editor\. Custom input behavior needs real composer tests\, including paste\, Escape\, autocomplete and submission\. Avoid adding a global raw\-input listener merely to implement an editor\-local key\. ### Autocomplete\, terminal listeners and renderers `addAutocompleteProvider(factory)` wraps the current provider\. A good wrapper\: - handles only its own prefix\; - delegates other suggestions and completion application\; - preserves built\-in slash\/file completion\; - tolerates being reapplied when command metadata refreshes\. The supplied controller stacks factories in registration order\. Contract tests cover healthy wrappers surviving a broken sibling factory\. Headless adapters accept and ignore these factories\. `onTerminalInput(handler)` is lower\-level\. A handler may return `{ consume: true }` or replacement `data`\; it returns an unsubscribe function\. Use it only in TUI mode\, clean it up\, and do not confuse terminal input with desktop\-wide keystroke control\. `getToolsExpanded()` and `setToolsExpanded()` control TUI tool\-output expansion\. RPC\/ACP return false and ignore the setter\. A supplemental thinking renderer can add presentation after already\-visible thinking text\. **Complete TypeScript exercise—save as `thinking-length.ts`\:** ~~~ts import type { ExtensionFactory } from "@oh-my-pi/pi-coding-agent"; import { Container, Text } from "@oh-my-pi/pi-tui"; const extension: ExtensionFactory = pi => { pi.registerAssistantThinkingRenderer((context, theme) => { const container = new Container(); container.addChild(new Text(theme.fg("dim", `thinking chars: ${context.text.length}`), 0, 0)); return container; }); }; export default extension; ~~~ Its context includes `contentIndex`\, `thinkingIndex`\, visible `text` and `requestRender()`\. It must not mutate the message\. It does not reveal otherwise unavailable reasoning\, and it does not change provider context\. Custom message renderers\, thinking renderers and tool renderers are different extension points\. Review Desk uses the first\; Seed Desk stage 3 uses a tool\-result renderer\. *Source\, snapshot 2026\-08\-29\: `packages/tui/src/components/composer/types.ts`\, `ComposerStyle`\; `packages/coding-agent/src/modes/components/custom-editor.ts`\, `CustomEditor`\; `packages/coding-agent/src/modes/controllers/extension-ui-controller.ts`\; `packages/coding-agent/test/issue-4919-extension-autocomplete-provider.test.ts`\; `packages/coding-agent/examples/extensions/thinking-note.ts`\.* ## Package Lab\: one file to an embedded host Theo maintains fictional field observations\. His first notebook fits in one file\. Later he wants reusable helpers\, optional package features and an application that embeds OMP\. His obstacle is architectural\: an imported helper\, an extension entry and an installed plugin are not the same thing\. [Package Lab’s complete instructions]() accompany the [source bundle]()\. ### Milestone\: one file is enough Files\: - [Single\-file entry]() - [Package Lab root manifest]() **Terminal shell\:** ~~~sh omp --no-extensions -e "$EXAMPLES/package-lab/single/field-notes.ts" ~~~ **Human OMP slash command\:** ~~~text /field-notes reed ~~~ **Model tool arguments—call `field_notes`\:** ~~~json {"op":"discover"} ~~~ ~~~json {"op":"inspect","value":"reed"} ~~~ ~~~json {"op":"query","value":"marsh"} ~~~ **Observed discovery details\:** ~~~json { "operations": ["discover", "inspect", "query"], "ids": ["reed", "fern"], "writes": false } ~~~ Inspection returns the fictional reed beside the footbridge\. The tool lowercases and trims its search value\. Query searches ID\, habitat and text\. The slash command is narrower\: it lists all notes or matches an exact lowercased ID\. Unknown tool inspection IDs throw\. Unknown human IDs produce a warning\. This entry does not declare `approval` or `loadMode`\. Therefore the current defaults apply\: an execution\-tier approval declaration and discoverable presentation\, despite the domain being read\-only\. Descriptions do not set approval policy\. The command uses notifications without a headless message fallback\. Its machine tool remains useful without the notification\. **Exercise\:** query `woodland`\. **Checkpoint\:** the tool finds `fern`\. Do not assume `/field-notes woodland` performs the same full\-text query\; it is an ID\-oriented human command\. ### Milestone\: helpers become ordinary imports Theo adds a current selection\. He wants both `/notebook fern` and a tool act to change the same selection\, without duplicating lookup logic\. Files\: - [Multi\-file entry]() - [Notebook helper]() **Terminal shell—after exiting the single\-file launch\:** ~~~sh omp --no-extensions -e "$EXAMPLES/package-lab/multi" ~~~ The directory resolves to `index.ts`\. `notebook.ts` is imported as a helper\; it is not independently bound as another extension\. **Complete helper source—[`multi/notebook.ts`]()\:** ~~~ts export const notes = [ { id: "reed", text: "Fictional reeds border the marsh trail." }, { id: "fern", text: "Fictional ferns shade the woodland path." }, ] as const; export function inspectNote(id: string): (typeof notes)[number] { const note = notes.find(candidate => candidate.id === id); if (!note) throw new Error(`Unknown note id: ${id}. Discover ids before selecting.`); return note; } ~~~ **Model tool arguments—call `notebook`\, one at a time\:** ~~~json {"op":"discover"} ~~~ ~~~json {"op":"inspect","id":"reed"} ~~~ ~~~json {"op":"act","id":"reed"} ~~~ ~~~json {"op":"query"} ~~~ **Human OMP slash commands\:** ~~~text /notebook fern /notebook ~~~ **Observed\:** command and tool shared the factory’s state\. An invalid action left the earlier selection intact\. Exact completed arguments returned no completion\. #### The lifetime correction The selection is declared inside the factory\: **Exact excerpt from [multi\/index\.ts]()\:** ~~~ts // Factory-local state belongs to one binding, not Bun's cached module. let selected: string | null = null; ~~~ That prevents this variable from being shared merely because a cached module is rebound\. It does **not** make it transcript\-local\. **Observed SDK lifecycle checks\:** | Operation | Transcript identity | Factory selection | | --- | --- | --- | | Select `reed` | Unchanged | `reed` | | `newSession()` | Changes | Still `reed` | | Select `fern`\, then `switchSession()` | Changes to a real target header | Still `fern` | | Construct a separate SDK host | Separate binding | Starts at `null` | | Rebind prepared factories | Fresh runtime and extension objects | Starts at `null` | The corrected teaching language is **factory\-local** or **binding\-local**\, not session\-local\. The public helpers deliberately do not reset on `session_switch` and do not append selection entries\. **Exercise\:** select `fern`\, use `/new`\, then run `/notebook`\. **Checkpoint\:** within the reused binding\, it remains selected\. If you want transcript\-local selection\, add explicit lifecycle reset or branch reconstruction in a new exercise\; do not claim the supplied stage already does that\. ### Milestone\: a manifest declares several entries Theo now wants a catalog and a reusable prompt\. An optional summary tool should be available only when selected as a package feature\. Files\: - [Manifest]() - [Catalog entry]() - [Resource entry]() - [Optional summary entry]() - [Prompt file]() **Exact config file—[`manifest/package.json`]()\:** ~~~json { "name": "omp-workbook-field-notes", "version": "1.0.0", "private": true, "type": "module", "description": "Fictional field notes with an optional plugin summary", "omp": { "extensions": ["./entries/catalog.ts", "./entries/resources.ts"], "features": { "summary": { "description": "Add the fictional habitat summary tool", "default": false, "extensions": ["./entries/summary.ts"] } } } } ~~~ **Terminal shell—load the base manifest entries\:** ~~~sh omp --no-extensions -e "$EXAMPLES/package-lab/manifest" ~~~ The base catalog registers `field_catalog` and `/field-catalog`\. **Model tool arguments—call `field_catalog`\:** ~~~json {"op":"discover"} ~~~ ~~~json {"op":"query","habitat":"marsh"} ~~~ Explicit `-e` directory loading reads the base `extensions` list\. It does **not** select plugin features\. To try the optional entry without installation\: **Terminal shell\:** ~~~sh omp --no-extensions -e "$EXAMPLES/package-lab/manifest" -e "$EXAMPLES/package-lab/manifest/entries/summary.ts" ~~~ **Model tool arguments—call `field_summary`\:** ~~~json {} ~~~ **Expected result details\:** ~~~json {"fictional":true,"habitats":["marsh","woodland"]} ~~~ `field_summary` has no `op` parameter\. **Observed\:** default installed\-plugin feature resolution selected two entries\; enabling `summary` selected three\. Explicit base\-manifest directory discovery did not include the optional entry\. Resource registration is explained in [Resources\, event buses\, MCP and Gemini manifests]()\. Its runner\-level proof does not establish automatic prompt\-menu rendering\. **Exercise\:** why not import `summary.ts` for its side effects from the base catalog\? **Answer\:** that would undermine the feature\-selection boundary\. A feature is meaningful only if its code is not activated through another unconditional path\. ### Milestone\: embed a factory in an SDK host Theo’s final goal is to include the notebook in another application without installing a global plugin\. Files\: - [Inline factory creator]() - [Session construction]() - [Runnable host script]() `createFieldNotesExtension(name)` returns an `ExtensionFactory`\. The SDK’s `extensions` option takes **functions**\, not file paths\. File paths belong in `additionalExtensionPaths`\. **Exact excerpt—session options in [inline\/session\.ts]()\; use the linked complete module\:** ~~~ts const result = await createAgentSession({ cwd: scratchDirectory, agentDir: path.join(scratchDirectory, "agent"), authStorage: auth, modelRegistry: new ModelRegistry(auth, path.join(scratchDirectory, "models.yml")), settings: Settings.isolated(), sessionManager: SessionManager.inMemory(scratchDirectory), disableExtensionDiscovery: true, extensions: [createFieldNotesExtension("Fictional field notebook")], enableMCP: false, enableLsp: false, skipPythonPreflight: true, preloadedCustomToolPaths: [], skills: [], rules: [], contextFiles: [], promptTemplates: [], slashCommands: [], toolNames: [], }); ~~~ The complete module constructs an in\-memory auth store\, closes auth on failure\, and returns a `close()` function that disposes the session before closing auth\. Install the **workbook\-compatible** SDK package into the environment that runs the script\. Package Lab marks it as an optional peer\; the example is private and is not presented as a registry\-published package\. **Terminal shell—with that runtime dependency available\:** ~~~sh bun "$EXAMPLES/package-lab/inline/run.ts" ~~~ The script prints metadata containing `providerPromptSent: false`\, the `inline_notebook` tool and the registered command names\, then disposes the host\. It never calls `session.prompt()`\. That is not a blanket no\-network guarantee for arbitrary host startup\: model registries and other host configuration can perform discovery\. The recorded isolated run had network denied\. #### Binding is not initialization `createAgentSession()` builds the session and binds factories\. A mode adapter subsequently initializes the extension runner’s live actions\/UI\. The public metadata script does not pretend to be a full TUI\/RPC host\. Its notebook tool uses closure state\, so the proof could exercise it through the real adapter without needing message actions\. An embedding that uses `appendEntry()`\, message delivery\, dialogs or session actions must wire the real runtime—not replace those methods with successful no\-ops\. The inline tool’s `discover`\, `inspect` and `query` all return its notebook contract and current selection\. It does not implement a separate per\-note inspection record\. `act` requires `reed` or `fern`\. #### Prepared factories versus bound instances Prepared factories can be rebound to a fresh runtime\. Already\-bound extension instances close over their original API and must not be forwarded to an independently constructed SDK session\. The CLI’s early preload is a special same\-owner optimization for flag parsing\. It is not a general pattern for sharing a parent’s loaded instances with a child\. **Exercise\:** share a module\-scope mutable selection between two SDK hosts\. What risk have you introduced\? **Answer\:** the module may be cached\, so both factory bindings can reach the same mutable variable\. Put binding state inside the factory\, and use explicit storage for any state intentionally shared across bindings\. *Source\, snapshot 2026\-08\-29\: linked Package Lab files\; `packages/coding-agent/src/sdk.ts`\, `CreateAgentSessionOptions`\, `createAgentSessionScoped`\; `packages/coding-agent/src/extensibility/extensions/loader.ts`\, `loadExtensions`\, `bindPreparedExtensions`\; recorded loading\/rebinding scenarios\.* ## Discovery\, installation and reload Theo can now distribute a working folder\, but another maintainer cannot find the tool\. The obstacle is not TypeScript\: it is discovery scope\. He separates four questions\: 1. Is the package installed or linked\? 2. Is its entry selected by discovery\? 3. Did the factory bind successfully\? 4. Is the tool enabled and presented in the expected way\? ### Creation and loading formats | Format | Exact entry contract | Typical use | | --- | --- | --- | | Single `.ts` or `.js` file | Default factory | First extension or tightly focused integration | | Async default factory | Returns `Promise` | Read adjacent assets before registration | | Directory with `index.ts` \/ `index.js` | Default factory in the selected index | Entry plus ordinary helpers | | Directory with `package.json` | `omp.extensions`\; legacy `pi.extensions` fallback | Several explicit entries | | Explicit `.mjs` \/ `.cjs` file | ESM default factory or compatible CommonJS factory export | JavaScript distribution without TypeScript | | Installed plugin manifest | Base entries plus enabled feature entries | Managed distribution | | SDK inline factory | Function passed to `extensions` | Host\-owned composition | | Prepared factory rebinding | Imported factory called against a fresh API\/runtime | Avoid repeated module evaluation without sharing bound state | For normal ESM modules\, an arbitrary named export is not enough\. **Complete JavaScript exercise—save as `format-note.mjs`\:** ~~~js export default function formatNote(pi) { pi.registerCommand("format-note", { description: "Identify the explicitly loaded module format", async handler(_args, ctx) { ctx.ui.notify("Explicit ESM extension loaded.", "info"); }, }); } ~~~ **Complete CommonJS exercise—alternative file `format-note.cjs`\; do not load both alternatives together\:** ~~~js module.exports = function formatNote(pi) { pi.registerCommand("format-note", { description: "Identify the explicitly loaded module format", async handler(_args, ctx) { ctx.ui.notify("Explicit CommonJS extension loaded.", "info"); }, }); }; ~~~ **Terminal shell—choose one explicit file\:** ~~~sh omp --no-extensions -e ./format-note.mjs ~~~ ### Scanning and manifest resolution are not identical Native and configured directory scanning automatically discover direct `.ts`\/`.js` files and immediate child entry packages\. They do not recursively import arbitrary helpers\. Installed\-plugin manifest expansion is broader\: it supports `.ts`\, `.js`\, `.mjs` and `.cjs`\, and corresponding index files\. There are additional implementation differences worth knowing\: - Native discovery uses globbing with gitignore\/hidden filtering\; explicit configured\-directory scanning uses `readdir` and does not apply that same filtering\. - Native child manifests with declared entries suppress index fallback\. - Installed\-plugin directory manifests are authoritative even when a declared entry is missing\; a stale index is not substituted\. - The explicit\-directory resolver falls back to an index when no declared entry survives its existence checks\. - Installed\-plugin scanning excludes declaration files\. Do not place `.d.ts` files in loose native\/configured scan directories and assume every scanner excludes them\. - For portable manifests\, list concrete entry files\. Do not depend on every loader resolving directory\-valued manifest entries in exactly the same way\. ### Where native extension factories come from The ambient native project root is **cwd\-only**\: - `/.omp/extensions` - the active agent directory’s `extensions` folder The default user agent directory is `~/.omp/agent`\. A named profile uses `~/.omp/profiles//agent`\; `PI_CODING_AGENT_DIR` can override it\. Native discovery also reads legacy `settings.json` extension lists\. The main startup path adds merged `extensions` settings\, normally from the active agent `config.yml` and project configuration\. Plain `/extensions` is not the same as `/.omp/extensions`\. The former needs explicit\/configured loading\; the latter is a native ambient root\. Legacy `pi` package metadata and some `.pi` compatibility lookups remain supported\. `.pi/extensions` is not a native ambient module root in this snapshot\. Skill ancestor traversal must not be used to infer extension\-module traversal\. ### Ordered inputs and two layers of deduplication The module discovery pipeline appends\: 1. native extension\-module capability items\; 2. discovered JS\/TS hook factories\; 3. enabled installed\-plugin extension entries\; 4. explicit\/configured paths\. Within the SDK’s configured lane\, CLI additional paths precede settings paths\. There are two different identity operations\: - Capability discovery can deduplicate by derived extension **name**\. Native project items precede user items\. - The final path list deduplicates normalized absolute **paths**\, first seen wins\. The final path deduplication is not a universal realpath\-equivalence guarantee\. Two different symlink spellings are not necessarily one path\-list identity\. Imports may be prepared concurrently\, but factories are bound sequentially in path order\. Do not rely on module\-scope side effects occurring in factory order\. ### Explicit\-only and trusted\-file loading `--no-extensions` means explicit\-only for this extension\-factory path and its OMP extension\-package sibling roots\. Explicit `-e`\, `--extension` and `--hook` entries remain eligible\. It is not full isolation\. Other tools\, skills\, rules\, prompts and MCP discovery families have their own controls\. `--trusted-extension` is stricter about **entry selection**\: - it requires an existing **absolute module file path**\; - it rejects directories\; - it canonicalizes the selected file’s real path\; - it cannot be combined with `-e`\, `--extension` or `--hook`\; - a trusted entry load failure aborts that startup path rather than merely becoming an ordinary per\-module warning\. **Terminal shell—trusted\-file selection using the actual absolute example path\:** ~~~sh omp --trusted-extension "$EXAMPLES/package-lab/single/field-notes.ts" ~~~ Do not copy the relative trusted\-path form from older example prose\: the supplied current `parseArgs()` requires an absolute path\. Trusted\-file selection does **not**\: - sandbox the factory\; - authenticate its dependencies\; - restrict ordinary imports\; - remove in\-process filesystem or network authority\; - create a universal prohibition on unrelated discovery systems\. ### Disable an entry without deleting it A derived ID looks like\: - `extension-module:field-notes` for `field-notes.ts`\; - `extension-module:multi` for `multi/index.ts`\. **Config file—an example setting in the active agent’s `config.yml`\:** ~~~yaml disabledExtensions: - extension-module:multi ~~~ In normal settings\-aware discovery\, this filters the directory\-discovered `multi/index.ts` entry\. An explicitly configured **file** remains an override in this build\. **Observed\:** the disabled directory case selected zero entries\; the explicit file case selected one\. Under `disableExtensionDiscovery`\, the SDK does not use the normal ambient disabled\-ID list for the explicit lane\. Do not use `--no-extensions` to test whether normal ambient disabling works\. Other capability families use their own IDs in `disabledExtensions`\. A hook’s disabled identity is not automatically its extension\-module name\. ### Installation is an opt\-in change to your environment The workbook requires no plugin installation\. Explicit `-e` is enough\. If you intentionally want to try native plugin management\, these commands change the user plugin installation state\. The scratch agent directory above is not a guarantee that plugin storage is project\-local\. **Terminal shell—optional developer installation\:** ~~~sh omp plugin link "$EXAMPLES/package-lab/manifest" omp plugin list --json omp plugin features omp-workbook-field-notes omp plugin features omp-workbook-field-notes --enable summary ~~~ A linked plugin starts with feature defaults\. `summary` defaults off\. Launch normally\, without `--no-extensions`\, when checking ambient installed\-plugin discovery\. `omp plugin install ./local-directory` routes to the same link operation\. It is not a package copy into the current project\. Current installation boundaries\: | Operation | What it does | | --- | --- | | `plugin link ` | Symlinks into the user plugin `node_modules` tree and records runtime state | | `plugin install ` | Routes to link | | npm or git installation | Runs package\-manager work and may fetch dependencies | | `plugin install name@marketplace --scope project` | Uses the distinct marketplace project\-scope route | | `plugin disable ` | Disables an installed plugin without removing its source | | `plugin enable ` | Re\-enables it | | `plugin uninstall ` | Removes installation\/runtime registration through the appropriate route | Adding `--scope project` does not make local\/npm installation project\-scoped\. The local\/npm install handler warns that scope is supported only for marketplace installs\. Runtime discovery can read both user and project plugin roots\. Enabled project packages shadow user packages with the same package name\. That does not imply every installer writes to the project root\. ### Features and settings Install\-spec feature syntax is\: - `package`\: default features\; - `package[summary]`\: selected features\; - `package[*]`\: all optional features\; - `package[]`\: no optional features\. Quote bracketed shell arguments so your shell does not expand them\. Use a real package spec\; the workbook’s private teaching package is not claimed to exist in a registry\. Plugin feature metadata supports `description`\, `default`\, and additional `extensions`\, `tools`\, `hooks` and `commands`\. Plugin settings support\: - string\, number\, boolean and enum types\; - descriptions and defaults\; - `secret` display masking\; - an `env` fallback declaration\; - numeric `min`\, `max`\, `step`\; - enum `values`\. A settings declaration is not executable behavior\. The supplied `getPluginSettings()` helpers merge saved global\/project values\; they do not inject a settings object into `ExtensionAPI` or magically apply all defaults\/environment fallbacks to extension code\. A consumer must resolve and validate its settings deliberately\. The CLI supports `plugin config list|get|set|delete|validate`\. In this snapshot\, the parsed `--local` flag is not forwarded into the manager’s setter\: do not advertise it as a reliable project\-local write route\. Project overrides have their own file\: **Config\-file exercise—`.omp/plugin-overrides.json`\, selecting the real example feature\:** ~~~json { "features": { "omp-workbook-field-notes": ["summary"] } } ~~~ The same override structure supports `disabled` package names and per\-package `settings`\. `secret: true` is not secure credential storage\. Human CLI display may mask a value while JSON output still exposes it\. Keep real credentials out of source\, screenshots\, transcript details and published config\. ### Collisions have family\-specific rules | Registration family | Current behavior | | --- | --- | | Same tool\/command name inside one factory | Later Map entry replaces earlier | | Tools across extension instances | Registrations are retained\; effective lookup is later\-extension\-wins | | Commands across extension instances | Effective command lookup is later\-extension\-wins | | Aggregated built\-in command collision | Filtered with diagnostics | | Event handlers | Append and run in registration\/load order\, subject to event\-specific short\-circuiting | | Custom message renderer lookup | First extension with that type wins | | Assistant thinking renderers | All returned components append in registration order | | Flags and composer\-shape IDs | Aggregate last\-wins | | Nonreserved shortcut collision | Warning\; later normalized key wins | | Reserved shortcut | Rejected from the effective shortcut set | Do not load all Seed Desk stages together and infer which version won from one notification\. Registered CLI flags can shadow same\-named built\-ins in the extension\-aware parser\. Prefer namespaced flags so startup behavior is not surprising\. The current CLI validates requested tool names against the fully discovered session registry\. Older custom\-tool documentation saying only built\-in names are validated is stale\. Still\, `--tools`\/`--no-tools` is not a universal isolation switch\: unrestricted extension\/custom tools have their own inclusion behavior\. ### Reload means what the host actually reloads This snapshot contains a particularly important distinction\: - `AgentSession.reload()` reopens the current session file through `switchSession()`\. - The supplied TUI command\-context `reload()` calls that session reload and rebuilds presentation\. - RPC\/ACP plugin\-refresh code clears caches and refreshes skills\/file\-command metadata\, but does not itself reimport every extension factory\. - The module loader supports cache\-busted imports when a host actually invokes it again\. Therefore\: > For editing extension code\, restarting the explicit launch is the reliable workbook procedure\. Do not promise that `ctx.reload()` hot\-rebinds the factory\. Treat `await ctx.reload(); return;` as the end of the current command handler\. Factory\-local notebook state need not reset on a session reload\. The loader’s same\-process source cache\-busting also has platform\-specific behavior\. In particular\, the supplied compatibility loader notes a Windows `file://` query limitation\. A fresh process avoids treating an unverified hot\-reload path as proof\. ### Failure recovery and removal An ordinary invalid export\, import failure or factory exception becomes a path\-specific loader error\; later modules still bind\. Factory failure restores the queued provider\-registration list\, including earlier registrations the failed factory removed\. It is **not** a transaction over arbitrary side effects\. Recorded checks showed a failed factory’s flag default surviving that rollback\. Inline `loadExtensionFromFactory()` rejects its promise instead of returning a per\-path loader error record\. For recovery\: 1. Restart with only one explicit reviewed entry\. 2. Read the named load error\. 3. Check adjacent assets and dependencies\. 4. Restore a known\-good source version\. 5. Restart and inspect tool\/command metadata before invoking a mutation\. For removal\: - remove the explicit\/configured path\, or move the authored entry outside discovery\; - disable\/uninstall an installed plugin through its installation route\; - restart and verify that no second path still loads it\; - keep session files unless you intentionally want to discard their data\. **Terminal shell—optional installed\-plugin lifecycle checks\:** ~~~sh omp plugin disable omp-workbook-field-notes omp plugin enable omp-workbook-field-notes omp plugin uninstall omp-workbook-field-notes omp plugin list --json ~~~ Inspect the result\. A linked source directory remains your source\; uninstalling is not a request to delete that checkout\. **Exercise\:** an extension remains active after disabling its plugin\. What is the first likely duplicate route to inspect\? **Answer\:** an explicit `-e` or `extensions:` path\, or a loose copy in a native extension directory\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/loader.ts`\; `packages/coding-agent/src/discovery/builtin.ts`\, `helpers.ts`\; `packages/coding-agent/src/extensibility/plugins/loader.ts`\, `manager.ts`\, `types.ts`\; `packages/coding-agent/src/cli/args.ts`\, `plugin-cli.ts`\; `packages/coding-agent/src/main.ts`\, `buildSessionOptions`\; `packages/coding-agent/src/session/agent-session.ts`\, `reload`\.* ## Tools\, interception and native delegation Rowan wants extensions that an agent can use reliably\, not merely tools that appear in a list\. The obstacle is an attractive but weak interface\: “do something with this text” gives the model no stable targets\, no revision and no useful failure vocabulary\. Rowan adopts the patterns already earned by Seed Desk and Review Desk\. ### Design a composable domain interface A useful capability often separates\: 1. **Discover\:** what operations and targets exist\? 2. **Inspect\:** what is the exact object and contract\? 3. **Query\:** what is currently available\? 4. **Act\:** make a bounded change with explicit identity and preconditions\. 5. **Wait\:** observe a real asynchronous operation until a bounded deadline\. 6. **Diagnose\:** explain unavailable dependencies\, authority or failed progress\. These are design patterns\, not six mandatory OMP method names\. The supplied synchronous Seed Desk and Review Desk tools do not implement `wait` or `diagnose`\. Do not invent them in a request\. When adding real background work\, define a stable job ID and a truthful pending\/completed\/error contract before adding those operations\. A good action result says\: - which target changed\; - what changed\; - which revision now applies\; - what is available next\; - how to inspect the result\; - whether retry is safe\. It should never infer authorization from a note’s prose or from a rendered control\. ### The native tool signature A registered extension tool executes as\: **TypeScript API signature—reference\, not a standalone file\:** ~~~ts execute(toolCallId, params, signal, onUpdate, ctx) ~~~ The third argument is the abort signal\. Some older repository examples use legacy parameter names in the wrong positions\; unused parameters can hide that mistake\. Parameters may use\: - `pi.zod`\: the injected Zod\-compatible omptype builder\; - `pi.arktype`\: the injected native omptype builder\; - `pi.typebox`\: the compatibility facade\. Use the compatible injected builders rather than assuming any arbitrary upstream schema\-package version has identical behavior\. Type validation and provider wire schema generation are related but distinct\. `strict` controls provider structured\-output grammar opt\-in\/out\; it does not replace runtime domain validation\. ### Tool fields\, without conflation | Fields | Meaning | | --- | --- | | `name`\, `label`\, `description` | Machine identity\, human label and model\-facing contract | | `parameters` | Runtime\/wire parameter schema | | `execute` | Actual implementation | | `hidden` | Excluded from normal initial inclusion unless explicitly selected | | `defaultInactive` | Registered\, but not automatically enabled\; the extension owns later activation | | `loadMode` | Presentation of an enabled tool\: **`essential` or `discoverable` only** | | `deferrable` | The tool may stage changes requiring explicit resolve\/discard\; separate from discovery | | `approval` | Static or argument\-dependent tier\/policy declaration | | `strict` | Provider strict\-grammar choice\; explicit false is meaningful | | `mcpServerName`\, `mcpToolName` | MCP provenance\/search metadata | | `shellEnv` | Environment contribution for the supported user\-shell seam | | `sourcePath` | Originating custom\-tool file metadata | | `onSession` | Host\-dispatched tool lifecycle callback | | `renderCall`\, `renderResult` | Optional TUI presentation | There is no `loadMode: "deferred"` in this source\. Discoverable tools are kept off the normal top\-level schema where the host’s discovery transport permits it—through `xd://` mounting or tool search\. That is presentation\, not disabled authority\. An essential tool stays top\-level\. `getActiveTools()` is wired by the supplied TUI\/ACP adapters to the enabled set\, including discoverable tools\. It is not necessarily identical to `agent.state.tools`\, the directly presented top\-level array\. `setActiveTools(names)` is asynchronous\. Await it\. Unknown names are ignored by the session setter\; inspect the resulting set rather than assuming every requested name exists\. ### Content\, details and streaming Return\: - `content`\: text\/image blocks intended for model\-visible results\; - optional `details`\: structured host\/rendering metadata\; - optional `isError`\: a nonthrowing failure indicator\. Put decision\-critical machine fields in content too when the model needs them\. Review Desk’s JSON text is one approach\. `onUpdate()` emits partial results\. It is progress\, not a commit receipt\. `renderResult()` receives `expanded`\, `isPartial` and optional `spinnerFrame`\; native extension renderers may also receive original arguments as a fourth parameter\. A tool should\: - check an already\-aborted signal\; - pass cancellation into subprocess\/network work\; - validate again before a side effect when asynchronous work intervenes\; - distinguish cancellation before and after commit\. ### Milestone\: a standalone custom tool with real work Rowan has an existing tool\-only package\. A custom\-tool factory is appropriate here\; it returns a tool instead of calling `registerTool()`\. This complete exercise requires Git and a Git working tree\. It counts tracked TypeScript files\; it does not contact a remote\. **Complete TypeScript exercise—save as `.omp/tools/workbook-repo-stats.ts` in a test repository\:** ~~~ts import type { CustomToolFactory } from "@oh-my-pi/pi-coding-agent"; const factory: CustomToolFactory = pi => ({ name: "workbook_repo_stats", label: "Workbook repository stats", description: "Count tracked TypeScript files in the current Git working tree.", approval: "exec", loadMode: "essential", parameters: pi.zod.object({ glob: pi.zod.string().optional(), }), async execute(_callId, params, onUpdate, ctx, signal) { signal?.throwIfAborted(); onUpdate?.({ content: [{ type: "text", text: "Reading the tracked file list." }], }); const result = await pi.exec("git", ["ls-files", "-z", "--", params.glob ?? "*.ts"], { cwd: ctx.sessionManager.getCwd(), signal, timeout: 5000, }); if (result.killed) throw new Error("Tracked-file query was cancelled."); if (result.code !== 0) throw new Error(result.stderr || "git ls-files failed."); const files = result.stdout.split("\0").filter(Boolean); const details = { count: files.length, files }; return { content: [{ type: "text", text: JSON.stringify(details) }], details, }; }, }); export default factory; ~~~ **Model tool arguments—call `workbook_repo_stats` after discovery\/loading\:** ~~~json {} ~~~ The legacy custom\-tool order is\: **TypeScript API signature—standalone custom\-tool reference\:** ~~~ts execute(toolCallId, params, onUpdate, ctx, signal) ~~~ The SDK bridge converts that order to the native extension order\. The conservative `exec` approval tier reflects launching a program\. Host policy may require approval even though this particular Git operation reads metadata\. `pi.exec()` takes a program plus argv\, not an automatically interpreted shell expression\. Its options are `signal`\, `timeout` in milliseconds and `cwd`\; results are `stdout`\, `stderr`\, `code` and `killed`\. For native extensions\, `pi.exec()` defaults to the factory\-bound cwd\. Pass `ctx.cwd` explicitly when you need the current workspace after a move\. **Expected checkpoint\:** the result’s count matches the returned file array\. Outside a Git repository\, the tool fails instead of returning a fake zero\. **Exercise\:** abort during a slower subprocess version\. **Checkpoint\:** the signal reaches the subprocess and `killed` is handled\; no success result is fabricated\. #### Standalone\-tool boundaries The loader also discovers metadata records in some tool directories\. A `.md` or `.json` tool record is not automatically an executable factory\. Standalone custom\-tool name conflicts are rejected against built\-ins and previously loaded custom tools\. That differs from extension re\-registration\, which can intentionally replace a built\-in\. The legacy custom\-tool type includes compatibility members that do not all survive the ordinary bridge\. In particular\, its approval\-formatting callback is not propagated through the supplied `customToolToDefinition()` path\, and that bridge does not forward original arguments to the legacy result renderer’s optional fourth argument\. SDK `customTools` uses the legacy contract\; SDK `toolDefinitions` uses the native contract\. Restricted sessions exclude ambient extensions\/custom tools\. Explicit SDK tools require `allowRestrictedCustomTools: true` and selection in `toolNames` when used with `restrictToolNames: true`\. ### Milestone\: intercept a tool without rewriting its domain Rowan wants `first` to be a deliberate alias for the reed note when inspecting through `field_notes`\, and wants an oversized query refused\. This is an additional exercise\, not a change to the downloaded entry\. **Complete TypeScript exercise—save as `field-guard.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function fieldGuard(pi: ExtensionAPI): void { pi.on("tool_call", event => { if (event.toolName !== "field_notes") return; if (event.input.op === "inspect" && event.input.value === "first") { return { input: { op: "inspect", value: "reed" } }; } if ( event.input.op === "query" && typeof event.input.value === "string" && event.input.value.length > 80 ) { return { block: true, reason: "Field-note queries are limited to 80 characters." }; } }); pi.on("tool_result", event => { if (event.toolName !== "field_notes" || !event.isError) return; return { content: [ ...event.content, { type: "text", text: "Use field_notes discover before choosing an inspection ID." }, ], isError: true, }; }); } ~~~ **Terminal shell—load the real domain and the new middleware\:** ~~~sh omp --no-extensions -e "$EXAMPLES/package-lab/single/field-notes.ts" -e ./field-guard.ts ~~~ **Model tool arguments—call `field_notes`\:** ~~~json {"op":"inspect","value":"first"} ~~~ **Expected checkpoint\:** the effective tool input becomes inspection of `reed`\. For model\-issued calls\, `tool_call` runs at argument\-preparation time\. Replacement input is revalidated and becomes the input used for scheduling\, execution events\, persisted assistant tool\-call arguments and approval\. For direct or nested dispatches not passing through that agent\-loop preparation path\, the wrapper applies the replacement before its approval gate\. Do not assume a direct `tool.execute()` SDK call reproduces the loop’s schema revalidation\. All `tool_call` handlers see the original normalized event view\, not a middleware chain of earlier rewrites\. The current runner retains the last returned result object unless a block short\-circuits\; a later empty object can discard an earlier rewrite\. Coordinate policy handlers instead of assuming field\-by\-field merging\. Normalized event input may contain derived fields\, such as hashline edit `path`\/`paths`\, that are not valid execution parameters\. Return the tool’s actual input shape\, not a copied gate\-only view\. Computer provider calls have a synthetic view and do not apply these input replacements\. A revised nested `xd://` call forfeits an outer approval bypass and faces the appropriate gate again\. The slash command `/field-notes first` does **not** traverse this tool middleware\. Put mandatory shared policy in the shared domain if both entrances must enforce it\. ### Milestone\: delegate to the original built\-in Rowan next wants to add logging around one ordinary file write without reimplementing native snapshots and editing bookkeeping\. `ctx.invokeTool()` is available only when the registered tool shadows a native built\-in of the **same name**\. It is not a general “invoke arbitrary tool” API\. This deliberately narrow exercise replaces `write` and permits only `workbook-note.txt`\. Use it in a scratch workspace\; it will refuse other writes\. **Complete TypeScript exercise—save as `one-file-write.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function oneFileWrite(pi: ExtensionAPI): void { const parameters = pi.zod.object({ path: pi.zod.string(), content: pi.zod.string(), }); pi.registerTool({ name: "write", label: "Workbook one-file write", description: "Write workbook-note.txt through the native write implementation. Other targets are refused.", approval: "write", loadMode: "essential", parameters, async execute(_callId, params, signal, _onUpdate, ctx) { signal?.throwIfAborted(); if (params.path !== "workbook-note.txt") { throw new Error("This exercise permits only workbook-note.txt."); } if (!ctx.invokeTool) { throw new Error("The native write implementation is unavailable in this host."); } pi.logger.debug("Delegating workbook file write", { path: params.path }); return await ctx.invokeTool(params); }, }); } ~~~ The bare delegate inherits the caller’s signal\, progress callback and relevant native tool context\. The native call is not re\-gated\; the outer same\-tool call already passed approval\. Delegation depth is guarded\. That narrow delegation mechanism is not a restriction on arbitrary JavaScript imported by the extension\. Do not describe it as a sandbox\. **Exercise\:** rename the tool to `workbook_write` without changing the delegate\. **Checkpoint\:** it no longer shadows `write`\, so `ctx.invokeTool` is absent\. Share a domain function or use an explicit host adapter\; do not invent an arbitrary\-target overload\. ### Approval\, result transforms and session hooks Approval declarations can be\: - `read`\, `write` or `exec`\; - an object with `tier`\, `reason`\, `override`\, `policy` and optional `policyKey`\; - a function of arguments returning such a decision\. The current tier comparison is\: - `always-ask` automatically admits read\-tier operations\; - `write` admits read\/write tiers\; - `yolo` admits all tiers by default\. The name `always-ask` therefore does not mean every read prompts\. Explicit deny policies remain important\. `override: true` alone is not an unbypassable prompt in yolo mode\. These host policies must not replace a domain\-specific human grant\. `tool_result` patches `content`\, `details` and `isError` in sequence\; later handlers see earlier changes\. It cannot undo an external side effect\. One current wrapper detail matters for diagnostics\: its event `isError` is initialized from a thrown execution error\. A domain refusal\, or a nonthrowing result’s own failure flag\, should not be inferred solely from that event flag\. Seed Desk’s `details.ok` is intentionally explicit\. Test nonthrowing failures before writing result middleware that could erase their meaning\. `ToolDefinition.onSession` has reasons `start`\, `switch`\, `branch`\, `tree` and `shutdown`\, with `previousSessionFile`\. It is host\-dispatched\; the TUI controller has an explicit dispatcher\. The standalone custom\-tool bridge also maps additional reliability events\. For cross\-mode domain lifecycle behavior\, use and test explicit `pi.on(...)` handlers as the principal examples do\. `shellEnv` receives `command`\, `cwd` and a copy of the shell environment\. In the supplied `BashRunner`\, the registered `bash` definition’s hook contributes environment values when `useUserShell` is enabled\. It is not an all\-subprocess environment interceptor and does not automatically affect `pi.exec()`\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/types.ts`\, `ToolDefinition`\; `wrapper.ts`\; `runner.ts`\, `emitToolCall`\, `emitToolResult`\, `invokeNativeTool`\; `packages/coding-agent/src/sdk.ts`\, `customToolToDefinition`\; `packages/coding-agent/src/session/bash-runner.ts`\; `packages/coding-agent/src/exec/exec.ts`\; `packages/coding-agent/src/tools/approval.ts`\.* ## Session navigation and event\-driven behavior Lena works through a long fictional review\. She wants a checkpoint command that can inspect the current session and move to a deliberate place in its history\. Her obstacle is lifecycle timing\: a tool executes inside an agent operation\, while session navigation may need to abort\, restore history or wait for the operation to settle\. She keeps navigation on a command context\. ### Milestone\: explicit session controls The following is a complete source\-backed exercise\. It is not a new Seed Desk or Review Desk stage\. **Complete TypeScript exercise—save as `session-desk.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function sessionDesk(pi: ExtensionAPI): void { pi.registerCommand("workbook-session", { description: "Session controls: status | new | reload | compact | tree | branch | switch ", async handler(args, ctx) { const trimmed = args.trim(); const split = trimmed.indexOf(" "); const verb = split < 0 ? trimmed : trimmed.slice(0, split); const target = split < 0 ? "" : trimmed.slice(split + 1).trim(); if (!verb || verb === "status") { const current = ctx.models.current(); const details = { sessionId: ctx.sessionManager.getSessionId(), sessionFile: ctx.sessionManager.getSessionFile() ?? null, leafId: ctx.sessionManager.getLeafId(), cwd: ctx.cwd, model: current ? `${current.provider}/${current.id}` : null, contextUsage: ctx.getContextUsage() ?? null, asyncJobs: ctx.getAsyncJobSnapshot(), pendingMessages: ctx.hasPendingMessages(), }; pi.sendMessage( { customType: "workbook.session-status", content: JSON.stringify(details), details, display: true }, { triggerTurn: false }, ); return; } await ctx.waitForIdle(); if (verb === "reload") { await ctx.reload(); return; } if (verb === "compact") { await ctx.compact("Preserve concrete decisions, unresolved questions and stable domain IDs."); return; } let result: { cancelled: boolean }; if (verb === "new") { result = await ctx.newSession(); } else if (verb === "tree" && ctx.sessionManager.getEntry(target)) { result = await ctx.navigateTree(target, { summarize: false }); } else if (verb === "branch") { const entry = ctx.sessionManager.getEntry(target); if (entry?.type !== "message" || entry.message.role !== "user") { throw new Error("branch requires an existing user-message entry ID."); } result = await ctx.branch(target); } else if (verb === "switch" && target) { if (!(await Bun.file(target).exists())) { throw new Error("The target session file does not exist."); } result = await ctx.switchSession(target); } else { throw new Error("Use status, new, reload, compact, tree , branch , or switch ."); } ctx.ui.notify(result.cancelled ? "Session operation cancelled." : "Session operation completed."); }, }); } ~~~ **Human OMP slash command—after loading the exercise\:** ~~~text /workbook-session status ~~~ Use actual entry IDs from the current session manager\/tree\, not a workbook placeholder\, for navigation\. The status command is a snapshot\. It also appends a custom message\, so its displayed `leafId` is the position just before that status message was appended\. #### What the controls mean - `waitForIdle()` waits through the host’s wired idle operation\. It is not an exclusive lock against another caller starting work\. - `newSession()` starts a fresh transcript and returns `{ cancelled }`\. - `newSession({ parentSession, setup })` can associate a parent and run an initialization callback\. That callback receives the full session manager for deliberate setup\. - `branch(entryId)` uses a user\-message entry to create a new session file from its preceding history\. - `navigateTree(targetId, { summarize })` changes the current path in the same file\. - `switchSession(path)` restores another session\. - `reload()` reopens the current session\, as discussed earlier\. - `compact()` requests context compaction\. A user\-message tree target normally moves to its parent and offers that message for editing\. A non\-user target generally lands on the selected node\. Do not equate every target ID with “include this entry as the new leaf\.” **Expected checkpoint\:** navigating before a Seed Desk reservation changes the query result because that extension reconstructs the current branch\. Field Notes’ binding\-local selection does not change merely because the transcript moves\. **Failure boundary\:** pre\-navigation handlers may cancel\. Missing\/invalid targets fail\. Summarization and compaction may need a configured model\/provider and may incur costs\. The exercise uses `summarize: false` for ordinary tree navigation\. **Exercise\:** call `ctx.newSession()` from a tool by casting its context\. **Answer\:** do not\. General tool\/event contexts intentionally omit these command\-only navigation methods\. A cast does not make the lifecycle operation safe\. ### Compaction is not domain persistence Compaction changes the model’s retained conversational context\. It is not a replacement for reconstructing extension state from journal entries\. The supported compaction surfaces are\: - `session_before_compact`\: cancel or supply a complete custom compaction result\; - `session.compacting`\: add summary context\, replace the summarizer prompt or attach `preserveData`\; - `session_compact`\: observe the resulting entry\. `CompactOptions` contains\: - `onComplete`\; - `onError`\; - `mode`\; - `internalGuidance`\. A string passed to `ctx.compact()` is public custom instructions\. An options object can request a one\-off supported compaction mode\. The supplied type commentary names `soft`\, `remote` and `snapcompact`\; use the matching host’s `CompactMode` rather than inventing another value\. `internalGuidance` is for native summarizer guidance\, not the user’s `customInstructions` visible to the pre\-compaction hook\. The general context also exposes `compact()`\, but lifecycle\-sensitive compaction is best driven from a command or a host\-controlled safe boundary\. Awaiting maintenance from inside work that maintenance itself must drain can create a deadlock\. ### Change a prompt through the supported return shape Lena wants a temporary instruction to label fictional output\, without permanently editing the base prompt\. **Complete TypeScript exercise—save as `fictional-turn.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function fictionalTurn(pi: ExtensionAPI): void { pi.on("before_agent_start", event => ({ systemPrompt: [ ...event.systemPrompt, "Clearly distinguish fictional workbook data from real observations.", ], })); } ~~~ This returns the complete replacement block array for that turn\, preserving existing blocks\. There is no current native `systemPromptAppend` result member\. The older pirate example uses that stale name\; do not copy it as a working contract\. `context` is the per\-model\-call message transformation surface\. Return new arrays and objects\. The runner attempts a structured clone\, but falls back to a shallow array copy for noncloneable data\; in\-place mutation is therefore a poor portability strategy\. Never remove one half of a tool\-call\/tool\-result pair casually\. ### Handler timing and errors Most event handlers run in extension order with a **30\-second** budget\. Important exceptions and qualifications\: - `tool_call` uses `extensionHandlers.toolCallTimeoutMs`\, defaulting to 30 seconds when unset or invalid\. - `tool_call` errors\/timeouts block execution\. - Its budget pauses while awaiting supported human dialogs\; asynchronous custom\-component setup still consumes budget until the component is ready\. - Other event handlers do not inherit that same paused human\-dialog budget\. - `session_shutdown` handlers run concurrently with a two\-second per\-handler cap\. - Factory loading and command handlers are not automatically covered by that event\-handler budget\. - Most other event\-handler failures are reported and dispatch continues\. A failed pre\-switch handler is not automatically a veto\. - A timeout cannot preempt synchronous JavaScript or magically cancel an arbitrary detached promise\. Code must honor cancellation and retire stale work\. `message_start`\, `message_update` and `message_end` are notifications\. `message_end` receives a detached snapshot\; changing it does not rewrite the next provider request\. `agent_end` is also notification\-only\. It may indicate an already scheduled continuation through `willContinue`\. Use `session_stop` for a supported stop\-time continuation request\, not an assumed return value from `agent_end`\. **Exercise\:** throw from `user_bash` to prohibit a shell command\. **Answer\:** that is not a reliable veto\. Its handler errors are isolated\, and the default path can continue\. Use a supported interception result or an actual enforcement boundary appropriate to the operation\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/session/agent-session.ts`\, session navigation and event mapping\; `packages/coding-agent/src/extensibility/extensions/runner.ts`\, `#runHandlerWithTimeout`\, `emit`\, `emitBeforeAgentStart`\; `packages/coding-agent/src/extensibility/shared-events.ts`\; `packages/coding-agent/src/extensibility/extensions/compact-handler.ts`\.* ## Background work and owner\-addressed delivery Mina starts a fictional habitat check\, then moves to another conversation before the result arrives\. Her goal is to keep the result with its origin\. Her obstacle is a tempting implementation\: > “When the promise finishes\, call `sendMessage()`\.” That sends to the runtime’s current session\, not necessarily the original owner\. Mina separates **work lifetime**\, **result storage**\, **delivery admission** and **agent wake\-up**\. ### Milestone\: managed timers for a local reminder Start with a small timer that only notifies the operator\. It does not pretend to be a durable job\. **Complete TypeScript exercise—save as `clock-note.ts`\:** ~~~ts import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent"; export default function clockNote(pi: ExtensionAPI): void { let timer: Timer | undefined; function clear(ctx: ExtensionContext): void { if (timer !== undefined) ctx.clearTimer(timer); timer = undefined; } pi.registerCommand("clock-note", { description: "Schedule or stop a one-second local reminder", async handler(args, ctx) { clear(ctx); if (args.trim() === "stop") { ctx.ui.notify("Reminder stopped."); return; } if (args.trim() && args.trim() !== "start") { ctx.ui.notify("Use /clock-note start or /clock-note stop.", "warning"); return; } const owner = ctx.sessionManager.getSessionId(); timer = ctx.setTimeout(() => { timer = undefined; if (ctx.sessionManager.getSessionId() !== owner) return; pi.logger.debug("Workbook reminder fired"); if (ctx.hasUI) ctx.ui.notify("One-second workbook reminder."); }, 1000); ctx.ui.notify("Reminder scheduled."); }, }); pi.on("session_before_switch", (_event, ctx) => clear(ctx)); pi.on("session_before_branch", (_event, ctx) => clear(ctx)); pi.on("session_before_tree", (_event, ctx) => clear(ctx)); pi.on("session_shutdown", (_event, ctx) => clear(ctx)); } ~~~ **Human OMP slash commands—after loading\:** ~~~text /clock-note start /clock-note stop ~~~ **Expected checkpoint\:** start produces one reminder if the host stays alive long enough\; stop or a navigation attempt clears it\. Managed timers\: - contain synchronous callback throws and rejected native promises\; - report failures through the extension error channel\; - are unref’d\, so they do not keep the process alive alone\; - are cleared on shutdown\; - can be cleared individually with `clearTimer()`\. Clearing a timer does not cancel asynchronous work that its callback already started\. That work needs its own abort controller and stale\-result checks\. Managed timers do not automatically register jobs in `getAsyncJobSnapshot()`\. That snapshot reports the host’s session\-owned async jobs\, or null when no applicable manager is available\. **Exercise\:** remove the explicit pre\-switch clear and start a reminder before `/new`\. **Answer\:** the runner\/binding can survive `/new`\; automatic shutdown cleanup is not a session\-switch reset\. Design the intended lifetime explicitly\. ### Ordinary messages\: choose the effect deliberately | API | Intended use | Important semantics | | --- | --- | --- | | `appendEntry(type, data)` | Extension state | Not sent to the model | | `sendMessage(payload, options)` | Custom conversation\/context message | `content` participates in model context\; `details` is metadata | | `sendUserMessage(content, options)` | User\-style prompt or queued user message | Does not dispatch slash commands or expand prompt templates | | `captureSessionTarget()` \+ `deliverMessage()` | Owner\-addressed result delivery | Persistent anchor\, admission checks and deduplication receipt | `sendMessage()` and `sendUserMessage()` return `void` through `ExtensionAPI`\. Awaiting them does not produce a durable acknowledgement\. For custom messages\: - Idle\, no trigger\: append to conversation\/session without starting a turn\. - Streaming\, default delivery\: queue as steering\. - Streaming\, `followUp`\: queue behind the current work\. - Streaming\, `nextTurn`\: hold as hidden next\-turn context rather than an editable pending\-message chip\. - `triggerTurn: true`\: request a turn\; hosts may defer it\. - Idle `nextTurn` without a trigger appends immediately in this implementation\; it is not a separate durable outbox\. For `sendUserMessage()`\: - omitted `deliverAs` starts prompt flow when idle and steers while streaming\; - explicit `steer` or `followUp` enqueues through that queue\, without synchronously starting a prompt\; - host queue\-drain behavior may subsequently resume work\; - **`nextTurn` is not an option on this API\.** `display: false` hides presentation\, not model visibility\. The old repository reload\-tool example queues `"/reload-runtime"` through `sendUserMessage()`\. Current `AgentSession.sendUserMessage()` explicitly skips command handling\. Do not teach that as a supported way for a model to invoke a human command\. ### Milestone\: capture once\, deliver to that owner This complete exercise demonstrates immediate capture\/delivery and a retained retry identity\. It is not a durable background job engine\. It requires\: - an initialized extension runtime\; - a persistent session\; - enough known model context capacity for admission\. No inference is requested because `triggerTurn` is false\. Without a model\/capacity snapshot\, `context_full` can be a correct deferred result\. **Complete TypeScript exercise—save as `owner-note.ts`\:** ~~~ts import type { ExtensionAPI, ExtensionSessionTarget } from "@oh-my-pi/pi-coding-agent"; export default function ownerNote(pi: ExtensionAPI): void { const namespace = "workbook.owner-note"; let pending: { target: ExtensionSessionTarget; deliveryId: string; content: string; } | undefined; let busy = false; pi.registerCommand("owner-note", { description: "Capture and deliver a local note: new | retry | status", async handler(args, ctx) { const input = args.trim(); if (input === "status") { ctx.ui.notify(pending ? `Pending delivery: ${pending.deliveryId}` : "No pending delivery."); return; } if (busy) throw new Error("A delivery operation is already in progress."); busy = true; try { if (input.startsWith("new ")) { if (pending) throw new Error("Retry the existing pending delivery before creating another."); const content = input.slice(4).trim(); if (!content) throw new Error("A nonblank note is required."); const requestId = crypto.randomUUID(); const target = await pi.captureSessionTarget({ namespace, requestId, data: { kind: "fictional-workbook-note" }, }); pending = { target, deliveryId: requestId, content }; } else if (input !== "retry") { throw new Error("Use new , retry, or status."); } if (!pending) throw new Error("No captured note is waiting for delivery."); const receipt = await pi.deliverMessage( { customType: namespace, content: pending.content, display: true }, { target: pending.target, namespace, deliveryId: pending.deliveryId, triggerTurn: false, }, ); ctx.ui.notify( `${receipt.state}; reason=${receipt.reason ?? "none"}; wake=${receipt.wake}`, receipt.state === "deferred" ? "warning" : "info", ); if (receipt.state !== "deferred") pending = undefined; } finally { busy = false; } }, }); } ~~~ **Human OMP slash commands—after loading with a persistent session\:** ~~~text /owner-note new The fictional marsh check is complete. /owner-note status /owner-note retry ~~~ Use `retry` only if the previous operation retained a pending item\. A successfully committed item is cleared by this small example\. The note’s retry state is binding\-local\. If the process exits before delivery\, this exercise has no durable outbox from which to recover it\. A real background system must persist the target\, stable delivery ID and complete body with its job\. #### Capture contract `captureSessionTarget({ namespace, requestId, data? })` appends an anchor and returns\: - `sessionId`\; - `sessionFile`\; - `anchorEntryId`\. Identifiers must be nonempty\. `data` must be structured\-cloneable\. Capture requires persistence and can fail during a conflicting transition\. Capture once before launching work\. Repeated calls with the same request ID are not an instruction to find and reuse an earlier anchor\. #### Receipt contract `deliverMessage(payload, { target, namespace, deliveryId, triggerTurn })` returns\: | Receipt field | Meaning | | --- | --- | | `deliveryId` | Your stable delivery identity | | `state: "deferred"` | No new body appended by this attempt | | `state: "committed"` | Body persisted and published to the owner’s live context | | `state: "already_committed"` | Existing entry reused\; no duplicate body | | `entryId` | Committed journal entry\, when available | | `reason` | Admission or wake condition | | `wake` | `not_scheduled`\, `scheduled` or `pending` | Reasons are\: - `owner_inactive`\; - `branch_inactive`\; - `session_busy`\; - `context_full`\; - `host_defers_turn`\. Inspect state and wake separately\. A committed body can still have a pending wake\. A scheduled wake is not proof that the model has replied\. #### Ownership and deduplication The coordinator checks\: - the original session identity and file lineage\; - the anchor on the active branch\; - reset boundaries\; - busy session work\; - context capacity\. A recorded move can preserve owner identity\. A fork creates a new session ID and does not inherit delivery authority\. Navigating away from the anchor or crossing a reset boundary can make the branch inactive\. A namespace\/delivery\-ID retry with different content\, owner or anchor throws a conflict\. The hash represents typed content segments\, not every presentation field in the payload\; keep the entire payload stable rather than expecting changed details to update an existing delivery\. Text is split into blocks of at most 65\,536 UTF\-16 code units without splitting surrogate pairs\. The coordinator does not truncate or compact the result to make it fit\. `details["omp.delivery"]` is reserved for delivery identity\. Already\-compacted messages are not resurrected\. Retrying a delivery can repair a pending\/failed wake without adding another body\, but a later successful assistant entry suppresses another wake\. **Observed contract tests\:** real session persistence and coordinator scenarios covered duplicate delivery\, conflict\, failed persistence\, owner transitions\, large complete bodies and wake retry\. Some lifecycle tests used a mock model to test the agent loop\. That is not live\-provider evidence\. ### What changes next\? For a real service job\, Mina needs an additional durable job\/outbox store and retry policy\. No public `ExtensionAPI.startJob()` or magic shared durable backend exists in this inventory\. A useful new tool should then expose\: - a stable job ID\; - `inspect/query` for state\; - a bounded\, cancellable `wait`\; - `diagnose` for a deferred owner\, unavailable service or pending wake\; - explicit action retry rules\. Independent processes writing the same transcript need an external owner lock\. Delivery serialization is session\-local\. **Exercise\:** a receipt says `state: "committed"`\, `reason: "host_defers_turn"`\, `wake: "pending"`\. Should the worker resend under a new delivery ID\? **Answer\:** no\. Retain the same identity\. The body is already committed\; the outstanding issue is consumption\, not missing storage\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/managed-timers.ts`\; `packages/coding-agent/src/session/extension-delivery.ts`\, `ExtensionDeliveryCoordinator`\; `packages/coding-agent/src/session/agent-session.ts`\, message APIs and async snapshots\; `packages/coding-agent/test/extension-delivery.test.ts`\, `extension-delivery-lifecycle.test.ts`\.* ## Models\, providers\, credentials and memory Sora embeds OMP for a fictional research team\. She wants to select an appropriate model and later connect a real organizational gateway\. Her obstacle is a false sense of progress\: a model appearing in a catalog does not establish valid authentication\, compatible streaming or useful inference\. She develops these as separate milestones\. ### Milestone\: query the host’s models without copying its heuristics `ctx.models` is the read\-only query facade\: | Member | Contract | | --- | --- | | `list()` | Models considered available by the registry’s configured\-auth\/keyless\-provider rules\; not a live health test | | `current()` | Lazily read current model | | `resolve(spec)` | Resolve provider\/ID\, bare model selector or configured role alias using host matching preferences | | `family(model)` | Opaque lineage token for comparison\; do not persist its vocabulary | Thinking\/routing suffixes accepted by resolution identify the base model\; apply effort separately\. **Complete TypeScript exercise—save as `model-desk.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function modelDesk(pi: ExtensionAPI): void { pi.registerCommand("workbook-model", { description: "List available models or select one by a real host selector", async handler(args, ctx) { const spec = args.trim(); if (spec) { if (!ctx.isIdle()) throw new Error("Select a model after the current operation settles."); const target = ctx.models.resolve(spec); if (!target) throw new Error("No available model matches that selector."); if (!(await pi.setModel(target))) { throw new Error("No usable API key was available for that model."); } } const current = ctx.models.current(); const details = { current: current ? `${current.provider}/${current.id}` : null, available: ctx.models.list().map(model => ({ selector: `${model.provider}/${model.id}`, sameFamilyAsCurrent: current ? ctx.models.family(model) === ctx.models.family(current) : null, })), thinkingLevel: pi.getThinkingLevel() ?? null, serviceTiers: pi.getServiceTiers(), }; pi.sendMessage( { customType: "workbook.models", content: JSON.stringify(details), details, display: true }, { triggerTurn: false }, ); }, }); } ~~~ **Human OMP slash command—after loading\:** ~~~text /workbook-model ~~~ Use an actual returned selector as the argument when selecting\. `setModel()` can resolve credentials\, refresh OAuth or run a configured credential program through host code\. It is not necessarily an offline metadata\-only call\. It returns false for unavailable credentials and can throw on other failures\. The command rereads `ctx.models.current()` after selection\. This matters because the supplied command\-context construction spreads a base context and can snapshot `ctx.model`\; the model facade keeps its lazy getter\. General event contexts preserve the live model accessor\, except provider hooks deliberately bind it to that request’s model\. **Exercise\:** save `ctx.model` at factory time for use by every future request\. **Answer\:** there is no invocation context at factory time\, and model choice can change\. Use the current invocation or the lazy facade\. ### Thinking and service tiers `getThinkingLevel()` reads the effective level\. `setThinkingLevel(level)` changes the current session’s supported thinking level\. The extension\-facing setter takes `ThinkingLevel`\; the broader session\/settings `auto` selector is not an invented additional extension setter mode\. `getServiceTiers()` returns a detached snapshot\. Mutating the returned object does not change the session\. `setServiceTier(family, tier)` affects subsequent requests\: - OpenAI\: `auto`\, `default`\, `flex`\, `scale`\, `priority`\; - Anthropic\: `priority`\; - Google\: `flex`\, `priority`\; - `undefined`\: clear that family’s override\. Invalid family\/tier combinations throw\. An older embedding that did not wire these actions throws an unsupported\-action error rather than pretending success\. Changes do not alter an already in\-flight request\. A configured tier is not a guarantee of provider availability\, latency\, billing or acceptance\. Session journals also record model\/thinking\/service\-tier state for restoration\. Do not confuse those snapshots with a provider having successfully served a request\. ### Milestone\: register a real provider configuration The public bundle supplies a host adapter\, not a pretend provider\. **Complete public TypeScript source—[provider\-registration\.ts]()\:** ~~~ts import type { ExtensionFactory, ProviderConfig } from "@oh-my-pi/pi-coding-agent"; /** Host-owned configuration only. No endpoint, credentials, or fake transport is bundled. */ export function createProviderExtension(name: string, config: ProviderConfig): ExtensionFactory { if (!name.trim()) throw new Error("Provider name is required."); return pi => { pi.registerProvider(name, config); }; } ~~~ Import the creator into an SDK host and pass its returned factory in `extensions`\. It has no default export and is not a standalone `-e` entry\. **Missing prerequisite\:** a real `ProviderConfig` owned by the host\, including the actual endpoint\/API choice and valid authentication or a real custom transport\. No such service is bundled or exercised here\. Sora can verify registration and rollback without using real credentials\. She cannot honestly label inference “working” until a genuine provider scenario has been run\. ### `ProviderConfig` field guide | Member | Author decision | | --- | --- | | `baseUrl` | Actual endpoint base\; required for defined models under the public contract | | `apiKey` | Trusted key value or supported configuration reference\, such as an environment\-variable name | | `api` | Existing API identifier\, or custom API identifier paired with a real stream implementation | | `streamSimple` | Custom stream implementation returning `AssistantMessageEventStream` | | `headers` | Provider request headers\; never publish secrets in examples | | `authHeader` | Whether the resolved key is added as a Bearer authorization header | | `models` | Static model definitions | | `usage` | A normalized `UsageProvider` for host usage reporting | | `oauth` | Login\, refresh and credential\-aware routing contract | | `fetchDynamicModels` | Async live\-catalog callback | The public `streamSimple` field returns an event stream\, not the broader promise\-returning `StreamFn` used elsewhere in agent internals\. Build asynchronous transport work into a correct stream implementation\. The registry’s internal `ProviderConfigInput` has additional members\. Do not assume every internal field is part of the public extension `ProviderConfig`\. #### Replacement versus override The documented registration intent distinguishes\: - a nonempty `models` list for defining\/redefining provider models\; - a base\-URL\/header\-only registration for overriding existing model transport\; - `streamSimple` for a custom stream API\. The current implementation replaces that provider’s runtime model\-definition list when the nonempty\-model branch runs\. It also composes runtime overlays with static\/configured catalogs during lazy rebuilds\. Therefore do not use `models: []` as a delete\-all operation\, or rely on a one\-time replacement to establish a permanent exclusion filter over every built\-in model\. Inspect the composed catalog after refresh\. `unregisterProvider(name)` removes the runtime provider override and rebuilds static\/configured model state\. Source cleanup also owns custom API\/OAuth registrations\. These are registration\-lifetime mechanisms\, not a permission check limiting an extension to a provider it “owns\.” ### `ProviderModelConfig` field guide | Members | Meaning | | --- | --- | | `id`\, `name` | Stable model ID and display name | | `api` | Optional per\-model API override | | `reasoning`\, `thinking` | Whether extended thinking is supported and its canonical capability metadata | | `input` | Supported `text`\/`image` modalities | | `cost` | Input\/output\/cache\-read\/cache\-write costs per million tokens | | `premiumMultiplier` | Premium Copilot request accounting metadata\, not a token price | | `contextWindow`\, `maxTokens` | Context and output limits | | `preferWebsockets` | Codex transport preference where applicable | | `headers` | Per\-model headers | | `compat` | Supported OpenAI compatibility metadata | Do not invent capacities or set costs to zero merely to make a fixture look complete\. Incorrect limits affect compaction and delivery admission\. ### OAuth is a contract with a real authentication system The `oauth` object contains\: - `name`\: login UI label\; - `login(callbacks)`\: returns host\-compatible OAuth credentials or a plain API\-key string\; - optional `refreshToken(credentials)`\; - optional `getApiKey(credentials)`\; - optional `modifyModels(models, credentials)`\. A real implementation needs the provider’s actual authorization flow\, callback or device\-code requirements\, expiry\/refresh semantics and credential storage policy\. Use host callbacks for authorization URLs\, progress and requested input\. Do not fabricate a successful login or persist a placeholder token\. RPC login can emit an `open_url` UI request and accept a later pasted code\/redirect through input\. Its supplied login handler rejects a provider that asks for pre\-URL interactive input it cannot support\. ACP authentication and extension UI capability negotiation are separate host concerns\; do not promise an identical login UI in every client\. `modifyModels()` receives a clone of the **whole composed catalog**\, not merely the provider’s own models\. Preserve unrelated models\. It is reapplied during catalog rebuilding when stored OAuth credentials exist\; a throwing modifier is logged and falls back to the earlier catalog\. In this registry implementation\, installation of that modifier occurs in the nonempty static `models` branch\. Do not assume a dynamic\-only registration automatically installs the same modifier path\. ### Dynamic catalogs and usage `fetchDynamicModels(apiKey)` receives a resolved key or `undefined` and returns model definitions\. It is driven by registry refresh\, not by the factory merely declaring the callback\. The runtime uses the same SQLite model\-cache machinery as built\-ins\, with a default 24\-hour TTL\. Static models can remain as fallbacks alongside a live catalog\. An outage should be represented as an error\, not silently recast as an authoritative empty successful catalog\. The callback itself has no public abort\-signal parameter\. Its transport needs bounded network behavior\; a host timeout is not a guarantee that an underlying request was cancelled\. SDK startup first hydrates cached runtime providers offline\, then starts or awaits online discovery as appropriate for the host and model selector\. A “not found” result immediately after cold startup can therefore be a catalog\-timing issue\. `usage` receives normalized credential information and returns normalized usage data for AuthStorage’s cache\/history\/display path\. It is distinct from token usage on an assistant turn\. The recorded checks covered registration\, replacement and rollback\, including a synthetic usage\-provider contract\. They did not contact a real provider\. ### Trusted credential references Credential references are executable configuration decisions\: - an environment\-variable reference requires the real variable\; - command\-backed key\/header configuration can execute a trusted local program\; - a stored credential reference requires the matching host store\; - changing a provider URL can redirect where credentials are sent\. Do not derive endpoint or credential\-program configuration from untrusted model output\, draft text or a downloaded manifest merely because project inputs are trusted by default\. ### Milestone\: optional memory without assuming a backend Sora wants the extension to report whether memory is available\, not silently pretend every host has the same memory service\. **Complete TypeScript exercise—save as `memory-status.ts`\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function memoryStatus(pi: ExtensionAPI): void { pi.registerTool({ name: "workbook_memory_status", label: "Workbook memory status", description: "Report the configured memory runtime's status without saving anything.", approval: "read", loadMode: "essential", parameters: pi.typebox.Type.Object({}), async execute(_id, _params, signal, _update, ctx) { signal?.throwIfAborted(); const details = ctx.memory ? await ctx.memory.status() : { available: false, message: "This host supplied no memory runtime." }; signal?.throwIfAborted(); return { content: [{ type: "text", text: JSON.stringify(details) }], details }; }, }); } ~~~ The optional `MemoryRuntimeContext` provides\: - `status()`\: backend\, active\/writable\/searchable state and optional scope\/diagnostic fields\; - `search(query, { limit?, signal? })`\: count and content items\, with optional IDs\, sources\, timestamps and scores\; - `save(string | { content, context?, source?, importance? })`\: stored count\, optional IDs\, queued status and message\. Backend IDs in the supplied contract are `off`\, `local`\, `hindsight` and `mnemopi`\. Search cancellation is best\-effort and backend\-dependent\. Memory is not automatically a transactional reservation store\, not automatically branch\-local\, and not a delivery outbox\. A selected backend may need local components or an external service not supplied here\. **Exercise\:** `ctx.memory` exists but status says `writable: false`\. Should a save button claim success\? **Answer\:** no\. Availability of an object is not availability of every operation\. Inspect capability status and the real save result\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/model-api.ts`\; `types.ts`\, provider and model interfaces\; `packages/coding-agent/src/config/model-registry.ts`\, registration\/refresh\/auth methods\; `packages/coding-agent/src/memory-backend/types.ts`\; linked provider adapter\.* ## Resources\, event buses\, MCP and Gemini manifests Theo wants the notebook package to bring along guidance\. Rowan wants another extension to hear about a selected note\. Sora wants an external MCP service to contribute tools\. These are three different integration problems\. They should not be hidden behind the word “extension\.” ### Milestone\: return module\-relative resource paths Theo’s resource entry returns the location of a prompt\, rather than embedding all guidance inside a tool description\. **Complete public TypeScript source—[resources\.ts]()\:** ~~~ts import * as path from "node:path"; import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; export default function fieldResources(pi: ExtensionAPI): void { pi.on("resources_discover", () => ({ promptPaths: [path.join(import.meta.dir, "../prompts/field-observation.md")], })); } ~~~ **Complete public Markdown resource—[field\-observation\.md]()\:** ~~~markdown --- description: Describe a fictional field observation --- Use field_catalog to query the fictional notebook. Summarize one returned note. Clearly label the observation as fictional; do not claim a real survey occurred. ~~~ The module\-relative absolute path works from a different cwd\. `resources_discover` handlers may return\: - `skillPaths`\; - `promptPaths`\; - `themePaths`\. The event includes `cwd` and reason `startup` or `reload`\. The runner aggregates each path with the originating `extensionPath`\. **Observed\:** explicit runner dispatch returned the real prompt path and retained `entries/resources.ts` provenance\. **Boundary\:** the supplied `AgentSession` startup path does not call `emitResourcesDiscover()`\. Registering this handler does not prove that a normal launch consumed its paths or populated a prompt menu\. A host must emit and consume the results\. OMP extension\-package sibling discovery is a separate path\: configured\/explicit package roots can contribute conventional `skills`\, `hooks`\, `tools`\, `commands`\, `rules`\, `prompts` and MCP resources\. A prompt appearing through that route would not prove the resource event fired\. **Exercise\:** launch from another directory and inspect the runner’s resource result in a host test\. **Checkpoint\:** the prompt path still resolves to the package’s file\. Then separately test whether your actual frontend consumes it\. ### Milestone\: choose a skill\, prompt or rule deliberately Theo decides that a reusable workflow belongs in a skill\, while a short invocation belongs in a prompt\. **Complete Markdown exercise—save as `.omp/skills/fictional-field-guide/SKILL.md`\:** ~~~markdown --- name: fictional-field-guide description: Inspect and summarize the workbook's fictional field catalog --- Use the available field_catalog tool to discover valid note IDs and query a habitat. Label every observation as fictional. If field_catalog is unavailable, explain that the extension must be loaded; do not invent inventory or tools. Do not claim that a real survey occurred. ~~~ The native skill scanner requires a description\. Native project skills can be discovered through ancestor traversal within its configured boundary\, unlike cwd\-only extension modules\. When skill commands are enabled\, the human command is\: **Human OMP slash command\:** ~~~text /skill:fictional-field-guide ~~~ That introduces guidance into the agent flow\. It is not the same as executing a local `registerCommand()` handler\. For a standing instruction\: **Complete Markdown exercise—save as `.omp/rules/fictional-data.md`\:** ~~~markdown --- description: Keep workbook data distinct from real observations alwaysApply: true --- Treat Seed Desk, Review Desk and Field Notes records as fictional fixtures. Never describe a workbook reservation as a physical stock change. ~~~ Rule files can carry descriptions\, globs\, always\-apply state and supported condition\/scope metadata\. The native top\-level `RULES.md` route forces sticky always\-apply behavior\. A rule cannot enforce permissions against arbitrary extension code\. Seed Desk still needs real checks in `changeReservation()`\. Prompt templates and Markdown commands likewise do not register missing tools\. Guidance should say what to do when the required capability is absent\. **Exercise\:** load only the skill\, without `field_catalog`\. **Checkpoint\:** the agent should diagnose the missing tool rather than invent a catalog result\. ### Milestone\: coordinate extensions on a process\-local bus Rowan wants selection changes to be observable without creating a model turn\. The public event\-bus entry both publishes and listens to a namespaced channel\. **Complete public TypeScript source—[event\-bus\.ts]()\:** ~~~ts import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent"; const channel = "workbook:field-notes:selection"; export default function fieldNoteEvents(pi: ExtensionAPI): void { let selected: string | null = null; const unsubscribe = pi.events.on(channel, data => { if (data === "reed" || data === "fern") selected = data; }); pi.on("session_shutdown", () => unsubscribe()); const { Type } = pi.typebox; pi.registerTool({ name: "field_events", label: "Field events", description: "Discover or inspect the field-notes channel, query last selection, or act to publish reed/fern. In-process extension-runtime bus; selection survives /new and session switches within this binding, without durable delivery.", parameters: Type.Object({ op: Type.Union([Type.Literal("discover"), Type.Literal("inspect"), Type.Literal("query"), Type.Literal("act")]), id: Type.Optional(Type.Union([Type.Literal("reed"), Type.Literal("fern")])), }), async execute(_id, params) { if (params.op === "act") { if (!params.id) throw new Error("act requires a note id; nothing published."); pi.events.emit(channel, params.id); } const details = { channel, selected, operations: ["discover", "inspect", "query", "act"], delivery: "synchronous emit; asynchronous listeners are not awaited" }; return { content: [{ type: "text", text: JSON.stringify(details) }], details }; }, }); } ~~~ **Terminal shell\:** ~~~sh omp --no-extensions -e "$EXAMPLES/package-lab/advanced/event-bus.ts" ~~~ **Model tool arguments—call `field_events`\:** ~~~json {"op":"act","id":"reed"} ~~~ ~~~json {"op":"query"} ~~~ **Observed\:** selection became `reed`\. After shutdown unsubscribed the listener\, a later bus emission did not update that selection in the isolated check\. `pi.events.on()` returns an unsubscribe function\. `emit()` invokes listeners but does not await asynchronous completion\. Listener failures are caught and logged by the bus wrapper\. The public selection update happens synchronously before the listener’s first await\, so this small tool can immediately observe it\. That does not establish an acknowledgement protocol for an asynchronous subscriber\. The bus is runtime\/process\-local coordination\. It is not\: - cross\-process messaging\; - a durable queue\; - an automatic agent turn\; - a shared backend\; - a transaction across extensions\. A host can supply an explicit shared bus to SDK sessions\; that is a deliberate scope choice\. Do not call `events.clear()` from one extension as ordinary cleanup—it clears everyone’s listeners\. The entry unsubscribes on shutdown\, not `/new`\. Its selection remains binding\-local across transcript changes\. **Exercise\:** make a subscriber save to a slow external store\. Does `emit()` mean the save completed\? **Answer\:** no\. Add an explicit result\/acknowledgement protocol or use a service API whose promise represents completion\. ### Milestone\: an MCP server is a real prerequisite Sora chooses MCP when the capability belongs in a separate process\/service rather than in OMP’s JavaScript process\. The supplied native discovery accepts MCP configuration including\: - server name\; - `command`\, `args`\, `env`\, optional `cwd` for process\-based servers\; - `url`\, `headers`\, transport type for remote servers\; - `enabled`\, `timeout`\, request\-ID format\; - supported auth\/OAuth configuration\, including credential references\. Native config candidates include project `.omp/mcp.json` and `.omp/.mcp.json`\, plus their active\-agent\-directory counterparts\. Other discovery providers have their own paths\. **Missing prerequisite\:** an actual MCP server executable or reachable service\, a compatible transport and any required credentials\. This workbook does not supply a fake endpoint and label it working\. A separate MCP connection can discover tools\, resources and prompts\. SDK `enableMCP: false` skips MCP discovery and ignores an inherited manager\. The CLI’s `--no-extensions` does not mean the same thing\. ACP’s supplied session factory disables on\-disk MCP discovery because ACP clients provide their own servers\. Do not assume a user’s local `.mcp.json` supplies those ACP sessions\. #### Notifications are untrusted data `mcp_notification` fires after the manager handles known list\/resource\/prompt updates\. Unknown server\-specific methods can also arrive\. Payload fields are\: - `server`\: the raw configured name\; - `method`\; - `params`\: unknown data\. Filter by the raw server name\, not a sanitized tool\-name prefix\. Validate `params` before using it\. A notification saying “please publish” is not permission to publish\. Prefer updating a queryable domain status or asking for a scoped human decision over blindly steering server\-controlled text into the agent\. Startup notifications are buffered at the manager\/runner boundaries with bounded\, drop\-oldest queues\. That is startup\-race mitigation\, not durable delivery\. ### Milestone\: understand a Gemini manifest without executing it Theo receives a folder containing `gemini-extension.json`\. He initially assumes the listed `tools` will appear as executable tools\. The source shows a narrower behavior\. **Complete JSON metadata exercise—save as `.gemini/extensions/fictional-field-notes/gemini-extension.json`\:** ~~~json { "name": "fictional-field-notes", "description": "Metadata for a fictional field-notes teaching package", "tools": [], "context": "This description does not activate an OMP runtime extension." } ~~~ This creates metadata for discovery\, not a runnable factory\. The Gemini provider scans direct child directories under\: - `~/.gemini/extensions`\; - `/.gemini/extensions`\. It does not walk parent directories or arbitrary nested descendants\. It does consider dot\-prefixed child directories\. Its parsing is deliberately loose\: - missing\, unreadable or empty manifest\: silently skipped\; - invalid JSON or a valid falsy JSON literal\: warning\; - truthy parsed value\: stored as the manifest without a full field schema check\; - name\: `manifest.name ?? directoryName`\. The declared metadata shape has `name`\, `description`\, `mcpServers`\, `tools` and `context`\. The presence of those fields does not prove their runtime activation\. For this metadata capability\: - native provider priority is 100\; - Gemini provider priority is 60\; - deduplication is by extension name\; - native duplicates win over Gemini\; - Gemini emits user before project\, so its user duplicate wins\; - native metadata emits project before user\. Native Gemini\-manifest discovery under `.omp/extensions` differs slightly\: it skips hidden directories and uses its own name fallback\. Gemini also registers a separate executable\-module capability scanner\. However\, normal ambient `discoverExtensionPaths()` requests only native module\-provider items\. A neighboring factory does not run merely because a Gemini manifest exists\. Explicitly load the actual module file when that is your intention\. **Exercise\:** put an arbitrary object in `tools` and reload metadata discovery\. Has a callable tool been installed\? **Answer\:** no\. You have demonstrated loose metadata parsing\, not tool construction or execution\. *Source\, snapshot 2026\-08\-29\: linked resource\/event\-bus files\; `packages/coding-agent/src/utils/event-bus.ts`\; `packages/coding-agent/src/discovery/builtin.ts`\, `gemini.ts`\, `helpers.ts`\; `packages/coding-agent/src/capability/extension.ts`\, `extension-module.ts`\; `packages/coding-agent/src/extensibility/extensions/runner.ts`\, `emitResourcesDiscover`\; `packages/coding-agent/src/sdk.ts`\, MCP wiring\.* ## Permission\-denied file fallbacks Ada embeds OMP in a host with a real OS permission boundary\. Native writes to one approved destination are denied inside the agent process\, but the host has a privileged channel that can perform them\. Her obstacle is preserving native tool behavior\. Reimplementing `write` or hashline editing would lose snapshots and bookkeeping\. She chooses a file fallback\, while leaving permission policy with the host\. ### Milestone\: delegate exact denied bytes The public bundle provides an adapter\, not an elevated writer\. **Complete public TypeScript source—[file\-fallback\.ts]()\:** ~~~ts import * as path from "node:path"; import type { ExtensionFactory } from "@oh-my-pi/pi-coding-agent"; export interface FieldNotesWriteBroker { /** Real host broker: resolve only after exact bytes are durable at the supplied destination. */ write(destination: string, content: string): Promise; } /** Host supplies the already-canonical allowlisted destination and a real broker. No elevated writer is bundled. */ export function createFieldNotesFallback(destination: string, broker: FieldNotesWriteBroker): ExtensionFactory { if (!path.isAbsolute(destination)) throw new Error("The host must supply an absolute, canonical destination."); return pi => { pi.registerFileWriteFallback(async (request, ctx) => { if (request.sessionId !== ctx.sessionManager.getSessionId() || request.dst !== destination) return false; await broker.write(request.dst, request.content); return true; }); }; } ~~~ **Missing prerequisites\:** - a real broker implementation\; - a host\-established canonical allowlisted destination\; - a real permission\-denied native byte\-write scenario\; - initialized runtime installation of the fallback\. The adapter checks that the destination is absolute\. It does **not** itself prove canonicalization\; the host must perform that policy work\. It has a named factory creator and no default extension export\. Import it into an SDK host\; do not launch it directly with `-e`\. #### What reaches the write seam\? The seam handles native ordinary\-file byte writes used by `write`\, `edit` and `apply_patch`\, including a hashline move destination\, after permission errors\: - `EPERM`\; - `EACCES`\; - `EROFS`\. A special missing\-parent case recovers a denied `mkdir` that Bun originally surfaced as `ENOENT`\. The broker may need to create that parent\. A genuinely invalid\/missing path is not automatically a permission fallback\. Requests contain\: - `dst`\; - `content`\; - `cause`\; - `sessionId`\, possibly undefined outside a tool call\. Handlers run in order\. The first true result means the native tool may continue as though its byte write succeeded\, including native snapshot bookkeeping\. Throwing handlers are logged and skipped\, including later handlers in the same extension\. If none succeeds\, the original error is rethrown\; a recovered underlying denial may be attached as its cause\. Returning true before the bytes actually land is a correctness bug\. #### Path and session policy `dst` is the resolved destination the failed write would target\, including the final component for writes\. Do not rederive it from a lexically innocent tool path\. If the destination cannot be resolved safely enough to identify it\, the fallback is not consulted\. Fallback registries are **process\-wide**\. A handler can be consulted for another session’s denied write\. Compare request identity to the handler’s session before prompting\: `ctx.ui` belongs to the handler’s session\, not necessarily the originator\. The public adapter intentionally refuses other sessions\. Canonical path resolution reduces specific symlink misrouting risks\. It does not establish a universal sandbox or remove the need for broker\-side path policy and safe filesystem operations\. ### Milestone\: deletion remains a separate capability A write fallback must never receive a delete request and interpret missing content as an empty file\. `registerFileDeleteFallback()` is separate\. It covers ordinary native unlink paths such as hashline `REM`\, a move’s source unlink and patch deletion\. A delete request contains\: - `dst`\; - `cause`\; - `confirmedFile`\; - `sessionId`\. The final path component is **not** resolved through a symlink\: unlink removes the link itself\. A broker must use plain unlink semantics\. It must never fall back to recursive removal or realpath the final component\. On Darwin\, unlinking a directory can report `EPERM`\. The seam refuses a known directory\, but inaccessible metadata can leave the target’s type unknown\. `confirmedFile: false` can mean either unknown metadata or a symlink—not permission to recursively remove it\. This complete adapter exercise chooses an even narrower policy\: only positively identified regular files\. **Complete TypeScript host\-adapter exercise—not an elevated implementation\:** ~~~ts import * as path from "node:path"; import type { ExtensionFactory } from "@oh-my-pi/pi-coding-agent"; export interface PlainUnlinkBroker { unlink(destination: string): Promise; } export function createSingleFileDeleteFallback( destination: string, broker: PlainUnlinkBroker, ): ExtensionFactory { if (!path.isAbsolute(destination)) throw new Error("An absolute policy destination is required."); return pi => { pi.registerFileDeleteFallback(async (request, ctx) => { if (request.sessionId !== ctx.sessionManager.getSessionId()) return false; if (request.dst !== destination || !request.confirmedFile) return false; await broker.unlink(request.dst); return true; }); }; } ~~~ That stricter `confirmedFile` choice deliberately declines symlinks and metadata\-hidden targets\. A different broker policy may support them with safe plain\-unlink operations\, but recursive deletion is never the fallback contract\. `ENOENT` on delete is not diverted\. ### What is not covered These APIs do not intercept\: - arbitrary `Bun.write()` or `fs` calls made by extensions\; - shell\/subprocess writes\; - archive\-member rewrites\; - SQLite row writes\; - ACP client\-side `writeTextFile`\; - the LSP tool’s independent workspace\-edit\/code\-action writes\; - formatter subprocess mutations\. Register fallback handlers during factory loading\. They are installed at runner initialization and disposed on shutdown\. A first registration after initialization does not install a previously absent seam\. Each invocation receives a newly built context\, so current cwd\/UI information is not frozen at installation\. **Observed scope\:** existing contract tests exercised real permission\-denied native writes and follow\-up editing\. The test’s stand\-in broker temporarily changed permissions to place bytes\; it was not a real privileged broker\. The workbook’s example scenarios did not exercise elevation\. **Exercise\:** the broker succeeded at the move destination but source unlink failed\. Is the move an atomic success\? **Answer\:** no\. The two primitives have separate outcomes\. Inspect the actual files before retrying\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/tools/file-write-fallback.ts`\; `packages/coding-agent/src/extensibility/extensions/runner.ts`\, initialization\/disposal\; `packages/coding-agent/src/extensibility/extensions/wrapper.ts`\, file\-mutation session attribution\; `packages/coding-agent/test/sdk-file-write-fallback-extension.test.ts`\.* ## Public feature reference This chapter is the compact index to the entire supplied public inventory\. It is intentionally grouped by purpose rather than presented as one giant type dump\. ### `ExtensionAPI`\: registration and module access | Members | Practical contract | Worked example | | --- | --- | --- | | `logger` | File logging\; avoid console output that corrupts TUI\/RPC channels and avoid logging secrets | Lab status\; native delegation | | `typebox`\, `arktype`\, `zod` | Injected compatible schema authoring | Seed Desk\; Package Lab | | `pi` | Injected coding\-agent package exports\; availability still follows the matching host | SDK\-oriented integrations | | `on` | Subscribe using the exact supported event name and return shape | [Event reference]() | | `registerTool` | Register a schema\-shaped machine capability | Seed Desk\; Review Desk | | `registerCommand` | Register a human\/host slash\-command handler | All principal stories | | `registerShortcut` | Register a nonreserved operator key binding | Phrase\-key exercise | | `registerFlag`\, `getFlag` | Declare\/read a boolean or string flag\; read your own registered name | `seed-quiet` | | `setLabel` | Set the extension’s display label in the supplied concrete implementation | Lab status | | `registerMessageRenderer` | Render a named custom message type | Review Desk | | `registerAssistantThinkingRenderer` | Add supplemental UI after visible thinking blocks | Thinking\-length exercise | | `registerComposerShape` | Register a complete composer rendering contract | Workbook Field Dock | | `registerFileWriteFallback`\, `registerFileDeleteFallback` | Register separate native permission\-denied mutation seams | [File fallbacks]() | | `registerProvider`\, `unregisterProvider` | Register\/remove runtime model\-provider overrides | [Providers]() | | `events` | Shared runtime event bus with `on`\, `emit`\, `clear` | Field events | **`setLabel` compatibility edge\:** the public type advertises both extension\-label and entry\-label usage\, but `ConcreteExtensionAPI.setLabel(label)` only assigns the extension label in this snapshot\. Do not claim that the two\-argument form labels a journal entry here\. Do not cast the read\-only session manager to bypass the public boundary\. ### `ExtensionAPI`\: live actions | Members | Practical contract | | --- | --- | | `sendMessage` | Custom conversation\/context message\; optional steer\/follow\-up\/next\-turn and turn trigger | | `captureSessionTarget`\, `deliverMessage` | Persistent owner anchor and deduplicated complete delivery with a receipt | | `sendUserMessage` | User\-style prompt\/queue\; no slash\-command dispatch | | `appendEntry` | Custom state entry\, not model\-visible content | | `exec` | Program\/argv execution with cwd\, timeout and cancellation | | `getActiveTools`\, `getAllTools`\, `setActiveTools` | Enabled\-set inspection\, full registry metadata and asynchronous selection | | `getCommands` | Dynamic command metadata\, not a universal list of built\-ins | | `setModel` | Credential\-aware model selection | | `getThinkingLevel`\, `setThinkingLevel` | Effective thinking\-level control | | `getServiceTiers`\, `setServiceTier` | Detached per\-family tier snapshot and subsequent\-request override | | `getSessionName`\, `setSessionName` | Read\/set persisted session naming\, distinct from terminal title | `getCommands()` aggregates extension commands\, loaded custom\/MCP prompt commands and enabled skill commands through `getSessionSlashCommands()`\. Built\-ins are intentionally excluded from that helper\. Frontends may advertise a larger command list\. `RegisteredCommand` contains `name`\, optional `description`\, optional `getArgumentCompletions`\, and `handler`\. Completion values represent the complete argument text\, not just an appended fragment\. ### `ExtensionContext` | Members | What to remember | | --- | --- | | `ui`\, `mode`\, `hasUI` | Mode and actual method support matter\; `hasUI` is not “all TUI methods work” | | `cwd` | Current at context creation\; do not retain it as a permanent workspace identity | | `sessionManager` | Read\-oriented session\/journal access | | `modelRegistry` | Host registry and credential\-resolution access\; prefer `models` for selection queries | | `model`\, `models` | Current\/request\-specific model and read\-only query facade | | `localProtocolOptions` | Calling\-session `local://` mapping for compatible bridges | | `getContextUsage` | Estimated context tokens\/window\/percentage\; can be undefined | | `getAsyncJobSnapshot` | Read\-only owner\-scoped job state\; can be null | | `isIdle`\, `hasPendingMessages` | Snapshot predicates\, not locks | | `abort` | Request cancellation of the current agent operation | | `shutdown` | Request host shutdown\; host\-specific and not an immediate `process.exit` guarantee | | `getSystemPrompt` | Effective prompt blocks\; treat returned content as sensitive | | `compact` | Request host maintenance at a safe boundary | | `memory` | Optional status\/search\/save runtime | | `setInterval`\, `setTimeout`\, `clearTimer` | Managed timer lifecycle | | `invokeTool` | Optional same\-name native built\-in delegation | | `isProjectTrusted` | Compatibility method returning true\, not isolation | The read\-oriented session manager exposes identity\/cwd\/header\/leaf\/entry\/branch\/tree\/label\/usage queries\. It also includes artifact\/blob helpers such as `allocateArtifactPath`\, `saveArtifact`\, `getArtifactPath`\, `putBlob` and `putBlobSync`\. “Readonly” here does not mean every helper is side\-effect\-free\: artifact\/blob helpers can store data\. It means extensions are not handed the journal’s general navigation\/mutation API\. Use\: - `getBranch()` for branch\-derived state\; - `getEntries()` for deliberately whole\-journal inspection\; - `getEntry()` and `getTree()` for stable navigation targets\. Do not mutate returned session records in place\. ### `ExtensionCommandContext` Commands inherit the general context and additionally expose\: - `getContextUsage`\; - `waitForIdle`\; - `newSession`\; - `branch`\; - `navigateTree`\; - `switchSession`\; - `reload`\; - `compact`\. The duplicated usage\/compaction members remain the same public concepts\. The navigation methods are command\-only\. The supplied ACP shutdown action is inert\. Other hosts request deferred graceful shutdown\. Do not build essential durable cleanup around an assumption that `ctx.shutdown()` terminates every embedding\. ### Tool metadata and provenance `ToolInfo` contains\: - `name`\; - `description`\; - `parameters`\; - optional `promptGuidelines`\; - `sourceInfo`\. `SourceInfo` contains\: - `path`\; - `source`\, such as builtin\, SDK\, MCP or extension\; - `scope`\: user\, project or temporary\; - `origin`\: package or top\-level\; - optional `baseDir`\. This metadata answers “where did the tool come from\?” It is not an authorization certificate\. `ToolRenderResultOptions` contains `expanded`\, `isPartial`\, `spinnerFrame`\. `ToolSessionEvent` contains `reason` and `previousSessionFile`\. `ToolShellEnvironmentContext` contains `command`\, `cwd` and `env`\. All `ToolDefinition` fields are explained in [Tools\, interception and native delegation]()\. ### UI inventory index Every supplied `ExtensionUIContext` member belongs to one of these families\: - Dialogs\: `timeoutStartsOnPresentation`\, `select`\, `confirm`\, `input`\, optional `askDialog`\, `editor`\. - Notices and layout\: `notify`\, `setStatus`\, `setWorkingMessage`\, `setWidget`\, `setFooter`\, `setHeader`\, `setTitle`\. - Native components\/input\: `custom`\, `onTerminalInput`\. - Composer editing\: `setEditorText`\, `pasteToEditor`\, `getEditorText`\, `addAutocompleteProvider`\, `setEditorComponent`\. - Appearance\: `theme`\, `getAllThemes`\, `getTheme`\, `setTheme`\, `getToolsExpanded`\, `setToolsExpanded`\. The complete dialog\/select\/ask\/custom option shapes are explained in [Review Desk’s UI chapter]()\. Composer shape fields are explained in [Editors\, themes and composer shapes]()\. ### Named\-interface coverage index The supplied inventory’s 27 named interfaces are covered as follows\: | Family | Interfaces | | --- | --- | | Core | `ExtensionAPI`\, `ExtensionContext`\, `ExtensionCommandContext`\, `ExtensionModelQuery` | | Tools | `ToolDefinition`\, `ToolRenderResultOptions`\, `ToolSessionEvent`\, `ToolShellEnvironmentContext`\, `ToolInfo`\, `SourceInfo` | | Commands | `RegisteredCommand` | | UI | `ExtensionUIContext`\, `ExtensionUIDialogOptions`\, `ExtensionCustomOptions`\, `ComposerShapeDefinition`\, `ExtensionUISelectOption` | | Rich ask | `ExtensionAskDialogOption`\, `ExtensionAskDialogQuestion`\, `ExtensionAskDialogResultItem`\, `ExtensionAskDialogSubmitResult` | | Maintenance | `CompactOptions` | | Providers | `ProviderConfig`\, `ProviderModelConfig` | | Durable delivery | `ExtensionSessionTarget`\, `CaptureSessionTargetOptions`\, `ExtensionDeliveryReceipt`\, `DeliverExtensionMessageOptions` | ### Reserved shortcuts The supplied runner rejects these effective extension shortcuts\: `ctrl+c`\, `ctrl+d`\, `ctrl+z`\, `ctrl+k`\, `ctrl+p`\, `ctrl+l`\, `ctrl+o`\, `ctrl+t`\, `ctrl+g`\, `ctrl+q`\, `alt+m`\, `shift+tab`\, `shift+ctrl+p`\, `alt+enter`\, `escape`\, `enter`\. Other host keybindings can still conflict\. Test the actual chord in the actual terminal\. Built\-in command names are filtered by the host’s reserved command set\. Do not assume a name is available merely because an older example registered it\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/types.ts`\, supplied public inventory\; `loader.ts`\, `ConcreteExtensionAPI`\; `runner.ts`\; `get-commands-handler.ts`\; `packages/coding-agent/src/session/session-manager.ts`\, `ReadonlySessionManager`\.* ## All 46 extension events These are the complete supplied event names\. Numbers follow the supplied inventory and make omissions easy to check\. Unless stated otherwise\, a notification handler’s returned value does not control the operation\. ### Resources and session lifecycle | No\. | Event | Payload\/use | Supported result | | --- | --- | --- | --- | | 1 | `resources_discover` | `cwd`\, startup\/reload reason\; contribute resource paths | `skillPaths`\, `promptPaths`\, `themePaths`\; requires host dispatch\/consumption | | 2 | `session_start` | Initial initialized session load | Notification | | 3 | `session_before_switch` | Reason `new`\, `resume` or `fork`\; optional target file | `{ cancel }` | | 4 | `session_switch` | Completed switch\; reason and previous file | Notification\; reconstruct current state | | 5 | `session_before_branch` | Selected user\-message entry ID | `{ cancel, skipConversationRestore }` | | 6 | `session_branch` | Branch completed\; previous file | Notification | | 7 | `session_before_compact` | Preparation\, branch entries\, public instructions\, signal | `{ cancel, compaction }` | | 8 | `session.compacting` | Session ID and messages about to be summarized | `{ context, prompt, preserveData }` | | 9 | `session_compact` | Compaction entry and `fromExtension` | Notification | | 10 | `session_shutdown` | Teardown | Cleanup\; concurrent bounded handlers | | 11 | `session_before_tree` | Tree preparation and signal | `{ cancel, summary }`\; summary used only when requested | | 12 | `session_tree` | Old\/new leaf\, optional summary entry and origin | Notification | `skipConversationRestore` means the branch proceeds while in\-memory conversation restoration is skipped\. It is not cancellation\. For the cancelable pre\-events\, cancellation short\-circuits\. Otherwise the current generic runner retains the last returned result rather than deep\-merging every handler’s object\. `session.compacting` likewise uses the last returned result object\; coordinate cooperating extensions\. Seed Desk reconstructs after lifecycle events\. Review Desk invalidates pending authority before navigation\. ### Prompt and provider boundaries | No\. | Event | Payload\/use | Supported result | | --- | --- | --- | --- | | 13 | `context` | Messages before each model call | Replacement `{ messages }`\, chained | | 14 | `before_provider_request` | Provider\-specific logical payload\; request model in context | Return the replacement payload directly | | 15 | `provider_request` | Frozen event with final `payloadJson` | Observation only | | 16 | `after_provider_response` | Status\, headers\, request ID\, metadata before stream consumption | Observation only | | 17 | `before_agent_start` | Submitted prompt\, images\, current prompt blocks | Custom `message` and\/or replacement `systemPrompt` blocks | | 39 | `input` | Input text\, images and source tag | `{ handled, text, images }`\; transforms chain\, handled stops | `before_provider_request` replacements chain in load order\. Provider\-specific payloads are not one universal HTTP schema\. `provider_request` is the final logical JSON after those transforms\, not exact transport bytes or headers\. Returned values cannot change it\. Extension observer errors are isolated and are not a reliable dispatch veto\. An embedding that requires a fail\-closed final\-payload check uses the awaited SDK `onProviderRequest` callback\; rejection there stops dispatch before extension observers\. The supplied guide identifies `devin-agent` as a provider that does not fire the request hook\. Provider implementation coverage must be checked when relying on these boundaries\; no live provider was exercised for the workbook examples\. `after_provider_response` occurs before the response stream has yielded final assistant usage\. Use a completed assistant message\, commonly at `turn_end`\, for actual turn token\/cost accounting\. `input` source tags are `interactive`\, `rpc` and `extension`\. The runner supports all three labels\, but that does not mean every host path emits the event\. The supplied RPC\/ACP prompt implementations do not themselves call `emitInput()`\. Do not use it as a universal inbound\-policy gateway\. In typed interactive input flow\, naming a session from `input` can precede the normal first\-message title check\. That does not imply every initial CLI prompt takes the same path\. ### Agent\, turn and message notifications | No\. | Event | Payload\/use | Supported result | | --- | --- | --- | --- | | 18 | `agent_start` | Agent\-loop start | Notification | | 19 | `agent_end` | Messages and optional `willContinue` | Notification only | | 20 | `session_stop` | Main\-session settle context\, turn\/session IDs\, last assistant\, `stop_hook_active`\, signal | `{ continue: true, additionalContext }` or `{ decision: "block", reason }` | | 21 | `turn_start` | Turn index and timestamp | Notification | | 22 | `turn_end` | Completed turn message and tool results | Notification\; inspect completed usage here | | 23 | `message_start` | A message begins | Notification | | 24 | `message_update` | Assistant message and streaming event\/delta | Notification\; keep handlers lightweight | | 25 | `message_end` | Detached completed\-message snapshot | Notification\, not a rewrite hook | A turn is one assistant response plus its associated tool results\. A run can contain several turns and maintenance continuations\. `session_stop`\: - is awaited at eligible main\-session settle\; - does not run for task\/subagent sessions\; - requires nonempty continuation context\/reason\; - is capped at eight consecutive continuations\; - is deferred when automatic continuation or owner\-scoped pending async work means the run is not truly finished\; - can be cancelled through its signal\. Use `stop_hook_active` to avoid endlessly requesting the same extra pass\. Streaming notifications can be queued\/detached relative to other host work\. Do not base an authorization protocol on an assumed universal arrival order of every message and UI frame\. ### Tool execution and approval | No\. | Event | Payload\/use | Supported result | | --- | --- | --- | --- | | 26 | `tool_execution_start` | Call ID\, name\, arguments\, optional intent | Observation | | 27 | `tool_execution_update` | Call identity\, arguments and partial result | Observation | | 28 | `tool_execution_end` | Call identity\, result and error state | Observation | | 40 | `tool_approval_requested` | Session\/call\/tool IDs\, optional reason\, approval mode | Observation | | 41 | `tool_approval_resolved` | Session\/call\/tool IDs\, approved boolean\, optional reason | Observation | | 42 | `tool_call` | Call identity and normalized input before execution | `{ block, reason, input }` | | 43 | `tool_result` | Effective input\, content\, details and error state | Patch `{ content, details, isError }`\, chained | A `tool_execution_start` event does not prove the side effect happened\; approval may still be pending\. Approval events are emitted when the wrapper reaches a required approval gate and relevant handlers are present\. They are not a way to approve by returning a value\. Already\-denied calls can short\-circuit before `tool_call`\. Schema failures\, pre\-execution blocks and approval denials do not necessarily traverse the post\-execution `tool_result` path\. `tool_call` errors\/timeouts fail closed\. `tool_result` middleware can change what is reported\, not reverse external effects\. ### Reliability and domain reminders | No\. | Event | Payload\/use | | --- | --- | --- | | 29 | `auto_compaction_start` | Reason\: threshold\, overflow\, idle or incomplete\; selected action | | 30 | `auto_compaction_end` | Action\, optional result\, aborted\/willRetry\, optional error\/skipped | | 31 | `auto_retry_start` | Attempt\, maximum attempts\, delay\, error message and optional error ID | | 32 | `auto_retry_end` | Success\, attempt\, final error and optional retry\-error presentation updates | | 33 | `retry_fallback_applied` | From\/to model selectors and configured role | | 34 | `retry_fallback_succeeded` | Fallback model and role that actually succeeded | | 35 | `ttsr_triggered` | Rules whose stream matching interrupted generation | | 36 | `todo_reminder` | Unfinished todos and reminder attempt information | | 37 | `goal_updated` | Current goal or null and optional goal\-mode state | | 38 | `credential_disabled` | Provider and truncated diagnostic cause for automatic credential soft\-disable | These are observations\, not return\-value control hooks\. Compaction actions include `context-full`\, `remote`\, `handoff`\, `shake` and `snapcompact` in the supplied event type\. A skipped or aborted compaction is not a successful summary\. `retry_fallback_applied` means a candidate was selected\. `retry_fallback_succeeded` distinguishes actual success\. `credential_disabled` is not fired for every user logout\/removal\. Startup events can be buffered until runtime initialization\; the runner’s buffer is bounded at 32\. ### Human execution and MCP notifications | No\. | Event | Payload\/use | Supported result | | --- | --- | --- | --- | | 44 | `user_bash` | Command\, cwd and whether `!!` excludes output from model context | Full replacement `{ result }` | | 45 | `user_python` | Code\, cwd and whether `$$` excludes output from model context | Full replacement `{ result }` | | 46 | `mcp_notification` | Raw server name\, method and unknown params | Notification | `user_bash` concerns human `!`\/`!!` execution\, not every model bash tool or arbitrary `pi.exec()` call\. `user_python` concerns the corresponding `$`\/`$$` user\-code path\. The first returned user\-execution result replaces default execution\. Throwing is not a supported blocking result\. MCP notifications arrive after the manager’s known\-method processing\. Buffering is bounded at 100 with drop\-oldest behavior at the supplied startup boundaries\. Validate payloads and do not mistake notifications for durable authority\. *Source\, snapshot 2026\-08\-29\: `packages/coding-agent/src/extensibility/extensions/types.ts`\, all `on` overloads\; `packages/coding-agent/src/extensibility/shared-events.ts`\; `runner.ts`\; `wrapper.ts`\; `packages/coding-agent/src/session/agent-session.ts`\; `packages/coding-agent/src/session/bash-runner.ts`\; `packages/coding-agent/src/modes/rpc/rpc-mode.ts`\.* ## Debugging and verification A workbook milestone is complete when the intended behavior is observable at the right layer\. A successful import is not proof of a useful tool\. A successful tool adapter call is not proof that the model chooses it\. A headless no\-op is not proof of a TUI\. ### A practical debugging order #### “The extension did not load” Check\: 1. The launch selected the intended file or directory\. 2. The module has a default factory\. 3. Adjacent assets such as `tool.txt` exist\. 4. Runtime dependencies match the custom host\. 5. The file is not hidden\/ignored by the discovery route\. 6. A disabled derived ID or plugin state did not filter it\. 7. An earlier same\-name capability item did not shadow it\. Inspect the path\-specific loader error\. Do not replace a failing factory with an empty function merely to obtain “loaded\.” **Terminal shell—default\-profile log example\; use the actual active state\-root log path on your host\:** ~~~sh tail -f ~/.omp/logs/omp.$(date +%F).*.log ~~~ The log root can differ with host\/state\-root configuration\. The supplied startup watchdog prints the actual log path\. **Terminal shell—source\-backed startup diagnostics\:** ~~~sh PI_DEBUG_STARTUP=1 omp --no-extensions -e "$EXAMPLES/package-lab/single/field-notes.ts" ~~~ This reveals startup phases\; it is not an isolation flag\. #### “The command works\, but the agent cannot use it” Inspect the tool registry\. - Was a tool actually registered\? - Is it enabled\? - Is it discoverable rather than top\-level\? - Does its description explain operations and prerequisites\? - Are important result fields in model\-visible content\? - Is the agent trying to invoke a slash command\? Use a direct schema\-valid tool scenario first\. Then\, separately\, test a real model session if useful\. #### “Enter keeps completing instead of submitting” Test exact completed input\, not only partial input\. - Completion values should contain the full argument text\. - A sole exact completed match should return null\. - Test Enter with the completion menu in the state the user actually encounters\. - Do not always press Escape first and then claim the exact\-match behavior is proven\. #### “The UI is blank” Check `mode`\, not just `hasUI`\. - RPC has semantic UI but no native component factory\. - ACP needs negotiated form support\. - Print\/JSON default methods are inert\. - `setFooter` and `setHeader` are no\-op in the supplied TUI implementation\. - Theme objects are not accepted by the supplied TUI setter\. - A tool without a renderer should retain its normal content path\. For a custom component\, inspect width bounds\, focus\, abort\, disposal and restoration of the editor\. #### “State leaked into another session” Ask which lifetime owns it\. - Module\-scope mutable variable\? - Factory\-local closure reused after `/new`\? - Whole\-journal scan instead of `getBranch()`\? - Stale context cached across a workspace move\? - Parent\-bound extension instances passed to a new SDK host\? - Background `sendMessage()` sent to the current runtime instead of a captured owner\? The Field Notes result is not a leak according to its contract\: its selection is binding\-local\. Calling it session\-local would be the bug in the explanation\. #### “Permission came back after revocation” Look for an in\-flight dialog\. Clearing the current grant is insufficient\. Abort the presentation and invalidate its generation\. A late positive answer must fail the generation check\. Test the delayed positive response deliberately\; do not test only revoke\-after\-grant\. #### “Reload ignored my code edit” Determine which reload path ran\. A session reload is not a factory rebind\. Restart the explicit launch\, then inspect a changed description or deterministic behavior\. Do not use an old closure’s output as evidence that new source was imported\. #### “A result arrived twice—or in the wrong branch” Inspect\: - captured target\; - namespace and delivery ID\; - owner\/session file lineage\; - anchor presence on the active branch\; - reset boundaries\; - receipt state versus wake state\. Retry a deferred\/pending delivery with the same identity and body\. Do not recapture the active session merely because the original owner is inactive\. #### “A provider is listed but unusable” Separate\: - catalog registration\; - cached discovery\; - available\/auth\-configured selection\; - credential resolution\; - streaming transport\; - final inference\. A catalog or rollback test does not prove OAuth or provider behavior\. #### “A denied write never reaches the fallback” Check whether it is actually\: - a supported ordinary byte\-write\/unlink\; - a permission error\; - a canonicalizable destination\; - inside an initialized fallback lifecycle\; - allowed by the handler’s session\/path policy\. Archives\, SQLite\, subprocesses and remote ACP writes do not enter this seam\. ### Verification levels | Level | What it proves | What it does not prove | | --- | --- | --- | | Schema\/type checking | Public API compatibility and parameter\/result typing | Runtime discovery or useful behavior | | Pure domain tests | Transition rules\, validation and data invariants | Host wiring | | Real loader\/runner\/adapter scenario | Actual binding\, interception and event contracts | Model choice or physical UI | | Real session storage scenario | Journal\/reopen\/branch behavior | Power\-loss durability or cross\-process coordination | | Protocol roundtrip | Requests\, responses\, cancellation and degraded modes | A particular remote client’s visual\/accessibility quality | | Real TUI\/controller\/composer smoke | Actual focus\, keys\, rendering and editor preservation | Every physical terminal or IME | | Real provider\/service integration | Actual endpoint\/auth\/transport behavior | General safety for unrelated providers\/configurations | ### A small test you can run without a provider The Review Desk domain is a useful offline test target\. This is a new exercise test file\, not one of the downloaded proof runners\. **Complete TypeScript test exercise—save beside Review Desk’s `domain.ts` as `domain.test.ts`\:** ~~~ts import { expect, test } from "bun:test"; import { MAX_TEXT_LENGTH, transition } from "./domain"; test("accept keeps edited text and increments once", () => { const before = { revision: 0, status: "draft" as const, text: "Original." }; expect(transition(before, "accept", "Reviewed.")).toEqual({ revision: 1, status: "accepted", text: "Reviewed.", }); }); test("reject and cancel preserve pre-review text", () => { const before = { revision: 4, status: "draft" as const, text: "Keep this." }; expect(transition(before, "reject").text).toBe("Keep this."); expect(transition(before, "cancel")).toEqual({ revision: 5, status: "cancelled", text: "Keep this.", }); }); test("invalid replacement text fails", () => { const before = { revision: 0, status: "draft" as const, text: "Original." }; expect(() => transition(before, "revise", " ")).toThrow(); expect(() => transition(before, "revise", "x".repeat(MAX_TEXT_LENGTH + 1))).toThrow(); expect(before.revision).toBe(0); }); ~~~ **Terminal shell—from the downloaded Review Desk directory\:** ~~~sh bun test ./domain.test.ts ~~~ **Expected checkpoint\:** the three domain tests pass without model inference\. They do not test the permission\-dialog race\; that requires the real runtime\/protocol scenario\. ### Story\-level acceptance scenarios Use these as falsifiable checks\: #### Seed Desk - Welcome command and tool return the same hours\. - Exact completion does not trap Enter\. - Herb query returns only basil with eight fixture packets\. - Unknown ID fails\. - Cancelled human grant\/reservation appends no state\. - Agent act before grant fails\. - Successful act advances revision\. - Old revision fails without a second mutation\. - Reopen restores state\. - Sibling branches do not mix reservations\. - New session starts with empty reservations and authority off\. #### Review Desk - Fresh inspection reports revision 0 and no grant\. - Accept stores the edited note once\. - Reject preserves pre\-dialog text\. - Editor cancellation records a distinct cancelled outcome\. - Stale agent act fails\. - Successful act consumes the grant\. - Revocation during a pending dialog emits cancellation and defeats a late positive response\. - Overlay cleanup preserves composer text\. - Print mode refuses interactive changes\. - RPC dialogs work without invoking native component factories\. - ACP with and without form capability has explicitly tested behavior\. #### Package Lab - Single file\, index directory and manifest resolve to the expected entries\. - Helpers are not accidentally bound as extensions\. - Optional feature defaults off\. - Explicit optional entry works separately\. - Invalid selection preserves the earlier selection\. - `/new` and switching preserve binding\-local selection\. - A new binding resets it\. - Resource dispatch preserves provenance\. - Factory failure does not suppress later entries\. - Provider rollback is not mistaken for rollback of all side effects\. ### The optional local `extb` toolkit The supplied local `extension-builder` toolkit is separate from native OMP\. It is not included among this workbook’s public example download paths\, and readers should not assume a particular developer’s local installation exists\. Its `new`\, `mock`\, `smoke` and `install` commands illustrate a useful process\, but its implementation has a narrower scope\: - The mock API implements command registration\, not the full ExtensionAPI\. - Its factory call does not await async initialization\. - It cannot validate these async\, tool\-registering examples as a general OMP loader\. - Its smoke driver uses a real PTY but inherits environment\/configuration and selects a default model\. - It presses Escape before Enter\, so it does not independently prove the exact\-match\-menu case\. - Its 25\-second subprocess timeout is a template choice\, not proof that native command handlers have a universal 30\-second budget\. - Its global install path is a fixed copy target\, not a complete profile\-aware installer\. - Plain `extensions/` needs explicit loading\; native `.omp/extensions/` does not\. Use the toolkit’s process idea—small scaffold\, domain test\, real host smoke\, deliberate installation—without treating its hints as stronger than the current runtime\. *Source\, snapshot 2026\-08\-29\: supplied contract tests and observed report\; `extension-builder/bin/extb.ts`\, `harness/mock-pi.ts`\, `harness/tui-smoke.ts`\; `packages/coding-agent/src/main.ts`\; linked public examples\.* ## Build and distribution checklist Finish an extension as an operated capability\, not just a source file\. ### Domain and authority - \[ \] The goal names a real user need and the chosen extension surface\. - \[ \] Model\-required capability has a supported tool interface\. - \[ \] IDs\, revisions\, availability and errors are explicit\. - \[ \] Human commands and tools share domain rules where required\. - \[ \] No tool can infer authority from untrusted text\. - \[ \] Cancellation before\/after commit is documented\. - \[ \] Pending permission dialogs cannot restore revoked authority\. - \[ \] Host approval labels are not described as a JavaScript sandbox\. ### State and lifecycle - \[ \] Module\, binding\, transcript\, branch and process lifetimes are documented\. - \[ \] Branch\-derived state uses `getBranch()`\. - \[ \] Stored data is validated and versioned\. - \[ \] Session switch\, tree movement\, branching and reopen are tested\. - \[ \] Reload claims match the actual host path\. - \[ \] Background work has cancellation and ownership\. - \[ \] Durable work retains target\, delivery ID\, body and retry state\. - \[ \] No cross\-process coordination is implied without a real backend\/lock\. ### UI and machine access - \[ \] Terminal\-only features use `mode === "tui"`\. - \[ \] Generic `hasUI` is not treated as complete method support\. - \[ \] Standard dialogs handle undefined\/false and optional ask\/chat results\. - \[ \] Timeout fallback is not treated as consent\. - \[ \] Tool content remains useful without custom rendering\. - \[ \] Custom components sanitize data and respect visible width\. - \[ \] Abort\/dispose restores focus and composer state\. - \[ \] RPC\/ACP degraded behavior is documented and tested\. - \[ \] Accessibility gaps are acknowledged\; semantic alternatives remain available\. ### Loading and packaging - \[ \] Entries export a valid default factory\. - \[ \] Manifest entries point to shipped files\. - \[ \] Adjacent text\/JSON assets are included\. - \[ \] Helpers are not placed where loose scanning imports them accidentally\. - \[ \] Runtime dependencies and compatible host versions are documented\. - \[ \] Optional features do not run through unconditional imports\. - \[ \] Name\, flag\, renderer and shortcut collisions are checked separately\. - \[ \] Configured paths are resolved against the intended cwd\. - \[ \] Installation scope is stated accurately\. - \[ \] Disable\/removal has been checked against every discovery route\. ### Verification and release - \[ \] Types were checked against the matching build\. - \[ \] Pure domain tests assert useful state changes\, not only fixture equality\. - \[ \] Real loader\/runner\/session scenarios pass\. - \[ \] Actual TUI composer behavior was tested where claimed\. - \[ \] Protocol cancellation and late replies were tested\. - \[ \] Real service tests are claimed only when actually run\. - \[ \] Failure recovery has an operator\-readable path\. - \[ \] The distributed archive contains no credentials\, private sessions or local machine paths\. - \[ \] A clean extraction can load the intended entries\. - \[ \] A release note states what was tested and what remains unverified\. The public workbook packages remain marked `private: true`\. If you turn a copy into a real distributed package\, choose your own package identity\, licensing\, versioning and publication route\. No registry publication or install success is claimed by this workbook\. ## Evidence and method This edition is grounded in the supplied **2026\-08\-29 source snapshot**\, complete public example files and a recorded completed verification report\. Repository citations throughout refer to that snapshot\. They are not links to an assumed upstream commit\. The installed custom host can differ from a published npm package or upstream source with a similar version string\. ### Recorded completed checks The supplied report records\: - **312 passing contract tests** - **22 test files** - **1\,039 assertions** - **0 failed tests** - Bun **1\.3\.14** - Host reported as **`omp/18.0.7`** - Strict typecheck of all supplied public example TypeScript files - **44 passing isolated example scenarios** - Two resolved review findings The two recorded corrections were\: 1. **Permission revocation\:** an in\-flight Review Desk dialog now gets aborted and generation\-invalidated\; a late positive RPC response cannot recreate the grant\. 2. **Binding lifetime\:** Field Notes is accurately described as factory\-local\. `newSession()` and `switchSession()` reuse its closures\; a new binding starts fresh\. ### Exact contract\-test command recorded The following is the completed command from the supplied report\. It is also a reproduction recipe for a matching installed source checkout—not a command available inside the example ZIP alone\. **Terminal shell—recorded repository\-root test command\:** ~~~sh bun test \ packages/coding-agent/test/extensions-runner.test.ts \ packages/coding-agent/test/extensions-discovery.test.ts \ packages/coding-agent/test/extension-delivery.test.ts \ packages/coding-agent/test/extension-delivery-lifecycle.test.ts \ packages/coding-agent/test/extension-provider-registration-rollback.test.ts \ packages/coding-agent/test/extension-prepared-rebind.test.ts \ packages/coding-agent/test/extension-flag-dispatch.test.ts \ packages/coding-agent/test/extension-flag-initial-message.test.ts \ packages/coding-agent/test/cli-explicit-extension-isolation.test.ts \ packages/coding-agent/test/plugin-extensions-discovery.test.ts \ packages/coding-agent/test/rpc-extension-ui.test.ts \ packages/coding-agent/test/sdk-file-write-fallback-extension.test.ts \ packages/coding-agent/test/sdk-extensions-per-session-binding.test.ts \ packages/coding-agent/test/sdk-preloaded-extensions-isolation.test.ts \ packages/coding-agent/test/sdk-restricted-extension-provider.test.ts \ packages/coding-agent/test/extension-context-project-trust.test.ts \ packages/coding-agent/test/extension-workspace-package-resolution.test.ts \ packages/coding-agent/test/issue-4919-extension-autocomplete-provider.test.ts \ packages/coding-agent/test/extensibility/ext-model-query.test.ts \ packages/coding-agent/test/discovery/disabled-extensions.test.ts \ packages/coding-agent/test/acp-agent.test.ts \ packages/coding-agent/test/status-text-sanitization.test.ts ~~~ The strict public\-example typecheck used `tsgo` through a separate validation workspace’s `bun check` command\. The downloadable Package Lab manifest does not declare a `check` script\. Do not assume running `bun check` in an arbitrary extracted directory reproduces that validation configuration\. ### What the observations establish The example scenarios used actual production components where named\: - discovery and module loading\; - factory binding and prepared rebinding\; - runner dispatch and tool adapters\; - real JSONL session storage\; - real SDK construction\; - real RPC request\/response streams\; - real TUI controller\, focus dispatch and a terminal emulator\; - real renderer width\/sanitization behavior\. Seed Desk’s confirmation responses were simulated at the UI seam\. Review Desk’s native check used a surrounding mode fixture\. Some existing lifecycle contract tests used mock models to test scheduling and consumption\. These distinctions matter\. A test can exercise a real coordinator while deliberately replacing the provider\. ### What is not claimed The supplied proof does not establish\: - live provider inference or OAuth against a real account\; - actual package installation\, registry publication or marketplace deployment\; - a real elevated file broker\; - physical\-terminal visual correctness across terminals\; - full Seed Desk autocomplete\/Enter smoke\; - arbitrary remote\-client accessibility\; - browser\/UI publication verification for this workbook\; - complete\-repository test coverage\; - cross\-process reservation or delivery coordination\. The newly authored exercises in this manuscript are source\-backed teaching code\, not additions to the supplied completed\-check totals\. No new execution is claimed during manuscript authoring\. ### Material prerequisites and missing context Some outcomes necessarily require evidence outside this bundle\: - A real provider needs its actual endpoint\, auth flow and transport behavior\. - A privileged file fallback needs a real host broker and filesystem policy\. - A remote UI needs a client that implements the negotiated dialogs and cancellation behavior\. - Declarative theme creation needs the matching host’s theme\-file schema\. - Standalone shell\/script\-tool protocols should be checked in their own loader implementation rather than inferred from discovery metadata\. - Exact hot\-reload behavior depends on the frontend path that performs reload\, not only on the module loader’s import support\. Where public types or older prose disagree with current code\, this workbook uses the narrower implementation\-backed behavior\: RPC can have semantic UI\, command handlers do not automatically inherit event timeouts\, `ctx.reload()` is not promised to rebind factories\, and metadata discovery is not execution\. ### Source families used The principal reference locations are\: - `packages/coding-agent/src/extensibility/extensions/types.ts` - `packages/coding-agent/src/extensibility/extensions/loader.ts` - `packages/coding-agent/src/extensibility/extensions/runner.ts` - `packages/coding-agent/src/extensibility/extensions/wrapper.ts` - `packages/coding-agent/src/extensibility/extensions/model-api.ts` - `packages/coding-agent/src/extensibility/extensions/managed-timers.ts` - `packages/coding-agent/src/session/agent-session.ts` - `packages/coding-agent/src/session/session-manager.ts` - `packages/coding-agent/src/session/extension-delivery.ts` - `packages/coding-agent/src/sdk.ts` - `packages/coding-agent/src/main.ts` - `packages/coding-agent/src/discovery/builtin.ts` - `packages/coding-agent/src/discovery/helpers.ts` - `packages/coding-agent/src/discovery/gemini.ts` - `packages/coding-agent/src/extensibility/plugins/loader.ts` - `packages/coding-agent/src/extensibility/plugins/manager.ts` - `packages/coding-agent/src/config/model-registry.ts` - `packages/coding-agent/src/modes/controllers/extension-ui-controller.ts` - `packages/coding-agent/src/modes/rpc/rpc-mode.ts` - `packages/coding-agent/src/modes/acp/acp-agent.ts` - `packages/coding-agent/src/tools/file-write-fallback.ts` - `packages/tui/src/components/composer/types.ts` The public examples are available through [the complete ZIP]() and the individual file links in their chapters\. Private runners\, private state\, credentials and local proof artifacts are not part of those downloads\. The process to carry forward is simple\: > Choose the smallest appropriate surface\. Give humans and models explicit contracts\. Make state lifetimes visible\. Test the real boundary that matters\. Distribute only what another reader can inspect\, operate and verify\. ## Extensions inside those boundaries\: next steps You now have both sides of the contract\: the operator’s need to identify and verify an effect\, and the builder’s responsibility to expose identity\, authority\, lifetime\, failure\, and retry behavior honestly\. The six connection chapters that follow are the synthesis of the book\. They compare state stores\, distinguish kinds of forks\, attach cancellation to the operation that owns it\, examine permission lifetimes\, separate results from disclosure\, and keep evidence at its actual verification layer\. Begin with [An empty context is not an empty history or memory store]()\. Return to the complete source chapters whenever an exact command\, example\, caveat\, or implementation reference matters\. The connections explain overlap\; they do not replace those contracts\. ## An empty context is not an empty history or memory store The Memory model and the Continuity ledger answer different questions\. Memory asks where useful knowledge can live\. Continuity asks which representation and identity a session operation changes\. Put them together before interpreting an old answer or choosing a reset\. ### Trace the representation\, not the word reset | Representation | What the source chapters establish | What that does not establish | | --- | --- | --- | | Rendered transcript | A viewer can collapse\, filter\, or hide content\. | Hidden content has been deleted\. | | Live\/model context | `/clear` drops live messages and appends a reset boundary used by later context rebuilding\. | Every journal entry\, memory\, skill\, or project instruction has disappeared\. | | Durable journal | Earlier and alternative entries can remain after a live\-context reset\. | Reopening them restores earlier workspace files\. | | Provider\-facing state | `/fresh` closes local cached handles\, rotates the provider\-facing identity\, and retains the conversation\. | Remote erasure\, authentication repair\, a cache miss\, or a new persistent journal\. | | Durable memory | Scoped retrieval can bring retained evidence into a later conversation\. | Retrieval is exhaustive\, current\, or guaranteed\. | | Managed skills | Procedural guidance exists in separately discovered files\. | A skill is a deterministic program or is erased by a conversation reset\. | | Extension state | Each example chooses a lifetime and reconstruction policy\. | Clearing model messages universally resets extension closures or stored domain entries\. | These are source\-backed distinctions\. The editorial consequence is straightforward\: **an unexpected answer is a provenance problem before it is a reset problem\.** ### Diagnose an old fact without wiping another layer In Cedar’s correction story\, the old retry limit might be present in a working memory row\, another bank\, a read\-only fact projection\, a cached injection\, or retained conversation material\. Seeing the old value does not identify which representation supplied it\. [Memory troubleshooting]() therefore begins with directory and bank scope\, then distinguishes stored rows from `/memory view`’s injected payload\. The correction story requires exact returned IDs and full content before a replacement edit\. A successful edit of one eligible row does not establish that transcripts\, skills\, exports\, backups\, or provider\-held copies changed\. Likewise\, [Decision Desk’s reset ledger]() does not describe `/clear` as an export scrubber\. A post\-clear context can be empty while a full\-history export still contains the earlier conversation\. Repeating clear cannot turn that retained representation into a deletion receipt\. ### Scope can change while conversation identity survives Continuity’s relocation paths can retain the persistent session identity while changing journal location or active cwd\. Memory’s recorded Mnemopi `per-project` bank derives from resolved cwd\, not Git root\. The combined operating implication is to recheck memory scope after a move or directory change rather than infer it from the retained session ID\. That is a scope check\, not a claim that relocation migrates a memory database\. The supplied chapters establish no universal migration contract between those systems\. Extensions add another reason to avoid broad reset assumptions\. Seed Desk reconstructs domain snapshots from `getBranch()`\. Field Notes keeps selection inside a factory binding that can survive `/new` and session switching\. The optional `ctx.memory` interface is neither automatically branch\-local nor a transactional domain store\. ### Keep two meanings of fresh separate Memory sometimes recommends a fresh startup after changing startup\-dependent configuration\. The named `/fresh` command has a narrower provider\-facing purpose\. Do not use the English phrase as evidence that the command reloads memory backends\, discovers new tools\, or rebinds extensions\. A useful paper check is to predict three independent outcomes\: which messages will be active\, which saved records will remain\, and which runtime configuration will be rebuilt\. If you cannot answer all three\, use the relevant source chapter instead of choosing a stronger\-sounding reset\. **Source trail\:** [Four places knowledge can live]()\, [The continuity ledger]()\, and [Models\, providers\, credentials and memory]()\. Their cited implementation anchors include `packages/coding-agent/src/mnemopi/config.ts` — `computeMnemopiBankScope`\; `mnemopi/state.ts` — `MnemopiSessionState`\; `session/agent-session.ts` — `freshSession`\, `resetSessionContext`\; and `session/session-context.ts` — `buildSessionContext`\. Related chapters\: - [The continuity ledger]() - [Return Desk missing\-directory decisions]() - [Decision Desk resetting deliberately]() - [Four places knowledge can live]() - [The configuration this workbook teaches]() - [Five fictional lab stories]() - [The command desk]() - [Troubleshooting]() - [Package Lab\: one file to an embedded host]() - [Models\, providers\, credentials and memory]() ## A conversation fork is not a worktree or a cloned runtime The word fork names a relationship between histories\. It does not\, by itself\, tell you which files\, processes\, settings\, tools\, or permissions became independent\. Continuity and Tan both preserve earlier conversation material\, but they do so for different operating purposes\. Extension branch state adds a third use of ancestry without creating another worker at all\. ### Compare the actual operations | Operation | Conversation effect | Workspace and runtime boundary | | --- | --- | --- | | Session\-tree navigation | Selects a path within the same journal\; target handling depends on entry type\. | It does not create a checkout or another worker\. Branch\-aware extensions must reconstruct their state\. | | Interactive `/fork` | Creates a new persistent identity from the current session\, retaining live conversation and ordinary queues on the fork path\. | The workspace remains shared\. Session artifacts are copied best\-effort\. | | Startup `--fork` | Creates a new identity from saved history and rebuilds context using the launch cwd\. | It does not clone an old process’s queues or copy workspace files\. | | Initial `/tan` | Creates a contextual child conversation and an initial background run from persisted Main history\. | Main and the child can run concurrently in the same directory\. Their live runtimes are not one cloned object\. | The full continuity fork carries all existing non\-header journal entries\, not only the visible leaf\. The tangent launch also starts from persisted history\, not a synchronized stream of Main’s unfinished text\, unsent draft\, or pending queues\. Both facts matter for privacy and for expectations about what the new conversation knows\. ### Task ownership is not isolation The Tan controller clears the clone’s inherited todo list and supplies a tangent\-specific responsibility boundary\. That helps keep the child from taking over Main’s unfinished work\. It does not make the filesystem read\-only\. Lantern Library’s ownership table is therefore more than prompt\-writing style\. It assigns one writer to each file\, identifies shared inputs\, and tells other workers what to leave alone\. When Main changes an input\, the relevant tan must reread it\; the file can be shared while the explanation of its change is not\. For review\, compare the current file and diff with the intended outcome\. An agent’s report is evidence to inspect\, not a substitute for inspecting the shared result\. If actual workspace isolation is required\, it needs a separately chosen and verified mechanism\. The source explicitly does not establish `task.isolation.*` as an automatic `/tan` control\. ### Do not inherit safeguards by assumption The initial tan receives model\, prompt\, settings\, and enabled\-tool information through specific construction paths\. Main’s live extension instances\, editor\, shell state\, and active provider request are not copied as a complete runtime\. Initial extension discovery is disabled\, but custom\-tool discovery and supplied MCP proxy tools are separate paths\. The recorded subagent helper defaults unattended approval to `yolo`\, with explicit per\-tool policies still inherited\. A narrow assignment is therefore not proof that Main’s interactive approval experience or extension\-based safeguards are reproduced unchanged\. Package Lab gives the corresponding builder rule\: prepared factories can be rebound\, but already\-bound extension instances close over their original runtime\. Sharing those instances with an independently constructed SDK session is not equivalent to constructing a fresh capability for the child\. ### Artifacts have their own fork behavior Continuity’s full fork attempts a recursive copy of the session artifact tree\; copy failure can leave a valid child journal with missing artifacts\. The initial Tan instead nests its transcript under the parent artifact tree and captures Main’s `local://` mapping without recursively copying that tree\. Its artifact allocation is not universally identical to Main’s\, and cold revival introduces further current\-host resource boundaries\. Use actual returned links and inspect required files\. Neither a fork acknowledgement nor an existing transcript is a verified backup\. **Source trail\:** [Decision Desk forking]()\, [Understand the fork]()\, [Start from Main]()\, and [Package Lab]()\. Their anchors include `packages/coding-agent/src/session/session-manager.ts` — `fork`\, `forkFrom`\, `copySessionArtifacts`\; `modes/controllers/tan-command-controller.ts` — `TanCommandController.start`\; and `extensibility/extensions/loader.ts` — `bindPreparedExtensions`\. Related chapters\: - [Decision Desk forking]() - [Decision Desk resetting deliberately]() - [1\. Understand the fork]() - [2\. Start from Main]() - [9\. Coordinate several tans]() - [10\. Protect context and recover]() - [Package Lab\: one file to an embedded host]() - [Session navigation and event\-driven behavior]() ## Changing focus\, stopping work\, and cancelling disclosure Cancellation is meaningful only when attached to an operation and a phase\. A keyboard gesture\, a rejected promise\, a cancelled job row\, and a hidden late result can describe very different outcomes\. The shared question is not “Did I press Escape\?” It is **which component owned that input\, what work had already started\, and which effect was actually stopped\?** ### Name the thing being stopped | Control or event | Intended boundary | Do not infer | | --- | --- | --- | | Ordinary Escape in focused Tan chat | Clears nonempty draft text\; otherwise returns the view to Main\. | The tan or its job was cancelled\. Higher\-priority panels or loop handling may own Escape instead\. | | Automatic return from Tan focus | Changes the recipient surface after parking\, abortion\, or removal\. | A draft still belongs to the tan\, or a submitted message needs replaying\. | | Turn interruption | Requests an end to the current attempt\. | Queue erasure\, durable agent termination\, or rollback of tool effects\. | | Cancellation of the initial background job | Marks and signals the identified running job\. | The explicit\-kill tombstone was written\, or every external process stopped\. | | Explicit Hub kill | Requests terminal agent release with a tombstone and retained transcript\. | The job must say cancelled\, or earlier edits were undone\. | | Main session reset or transition | Changes session state and may clear queues or cancel owned work according to that path\. | It is merely a view change\, or every failure phase is transactional\. | | Sharing\-loader Escape | Restores the editor and suppresses later result display\/opening\. | A started upload or custom\-handler effect was aborted or revoked\. | These distinctions explain why whole\-application controls are poor substitutes for leaving a focused tangent\. They also explain why a remembered job ID is unsafe for later cancellation\: job rows are short\-lived handles\, whereas the conversation transcript may remain\. ### Compare two asynchronous cancellations Review Desk explicitly retires pending authority\. Its `invalidateAuthority()` increments a generation\, clears the grant\, and aborts the pending presentation\. A late positive confirmation is accepted only if it still belongs to the current generation\. The recorded RPC scenario demonstrated that the old response could not recreate authority\. The sharing controller has a different contract\. Its loader receives cancellation\, but the inspected path does not pass that loader signal into default `shareSession` or the custom callback\. The recorded held operation completed after Escape while its late URL was suppressed\. That observation supports a warning about possible late completion\; it is not evidence of a real upload or a revocation service\. The lesson is not that one cancellation word is reliable and another is not\. It is that **signal propagation\, stale\-result rejection\, committed effects\, and UI restoration must each be designed and checked**\. ### Use a phase\-aware recovery record When an operation is uncertain\, record five things before retrying\: 1. **Surface\:** which chat\, overlay\, loader\, or mode owned the input\? 2. **Identity\:** which agent\, job\, session\, process\, or dialog was targeted\? 3. **Phase\:** had work only been requested\, had it started\, or had an effect already committed\? 4. **Observation\:** what receipt\, lifecycle state\, journal entry\, or file effect is actually available\? 5. **Remainder\:** what can still be running or retained outside that component\? For a tan\, inspect both agent and job state and any relevant external process\. For a session switch\, distinguish settings preflight\, hook veto\, guarded target\-load failure\, and post\-switch reconciliation\. For a share\, treat a cancelled or ambiguous result as possibly completed\; do not resend merely to obtain a visible URL\. This is a reading and recovery discipline\, not a request to manufacture a destructive or networked test\. The original failure cards and intercepted reports provide the comparison safely\. **Source trail\:** [Leave and switch safely]()\, [Interrupt\, cancel\, or kill]()\, [Decision Desk refusals and failures]()\, and [Sharing]()\. Relevant cited symbols include `SessionFocusController`\, `AgentLifecycleManager.release`\, `AsyncJobManager.cancel`\, and `CommandController.handleShareCommand`\; the supplied `examples/review-desk/index.ts` contains `invalidateAuthority()`\. Related chapters\: - [5\. Leave and switch safely]() - [7\. Continue a finished tan]() - [8\. Interrupt\, cancel\, or kill]() - [12\. State and control reference]() - [Decision Desk resetting deliberately]() - [Decision Desk refusals and failures]() - [Sharing is a separate disclosure decision]() - [Review Desk\: edit and decide locally]() - [Background work and owner\-addressed delivery]() ## Permission belongs to an operation\, a revision\, and a lifetime A tool can be enabled without its domain action being authorized\. A human can approve a local edit without approving publication\. A new session can reuse an extension closure without inheriting the same kind of persisted permission as another example\. The Extension part makes these distinctions concrete\. Continuity explains why they remain important when the active conversation moves\, and Tan explains why Main’s protections cannot simply be presumed to follow another runtime\. The Permissions part adds the operator’s resolution path\: which declaration\, effective policy key\, mode\, and UI capability govern this particular call\? The title’s operation\/revision\/lifetime discipline is a design principle\, not a claim that the generic tool\-approval dialog implements every domain revision check\. Its binary answer admits one call\; the domain must still validate its own object and authority\. ### Compare the examples without flattening their policies | Example | State and authority lifetime | Consequence | | --- | --- | --- | | Seed Desk reservations | Reservations and `agentEnabled` are persisted in branch snapshots\. Revision combines session identity and the latest relevant state\-entry ID\. | Ancestor grants can be inherited\. A headless reopen can retain an existing grant\; both human grant and revoke commands require UI in this supplied stage\. | | Review Desk | Draft state is reconstructed from branch entries\. The one\-action grant is in memory\, tied to session identity and numeric revision\. | A successful mutation consumes the grant\. Navigation\, revocation\, and shutdown invalidate authority and retire pending dialogs\. | | Field Notes | Selection is local to the factory binding and is not persisted in the journal\. | `/new` and session switching can keep the selection\; a fresh binding starts without it\. | | Memory and skills | Retained evidence and procedural guidance have their own storage and discovery scope\. | Retrieved prose does not grant a tool permission or establish that a procedure was executed\. | Even the persisted\-data validation policies differ\. Seed Desk refuses malformed matching snapshots rather than skipping them\. Review Desk’s small fixture skips entries that fail its state predicate\. Preserve that distinction when studying recovery\; the examples do not define one universal corruption policy\. ### Resolve host approval without inventing a domain grant [Approval Desk\: modes and policies]() establishes a precise order\. Tool deny and effective user deny are checked before automatic mode admission\. Explicit tool allow or prompt can outrank a non\-deny user policy\. An override\-only prompt is not an unbypassable policy in yolo\. Consequently\, neither “the user record always wins” nor “yolo disables every gate” is an accurate summary\. [Dispatch Desk]() adds policy identity\. A valid device policy replaces the invoking `write` fallback\; it is not an intersection with every policy in the record\. The outer transport borrows a tier\, while an applicable inner wrapper can still deny\. `xdevApproved` suppresses a particular unchanged\-input duplicate prompt\, not every nested check\. A supported input replacement can require reclassification\, and the source predicate is not a universal content\-revision guard\. The generic [one\-call boundary]() offers Approve and Deny only\. Dismissal is not approval\, and an approval does not persist an allow\-for\-session setting\. Two questions at outer and inner device gates can still precede only one execution\. None of those answers creates Seed Desk’s branch grant or Review Desk’s revision\-bound one\-action authority\. ### Authority and concurrency are separate checks Seed Desk re\-reads its revision after awaiting human confirmation\. Review Desk uses generation invalidation to prevent an old dialog answer from reviving authority\. Both respond to the same asynchronous hazard\: the context that made a decision meaningful may have changed while the UI was waiting\. A current revision does not supply permission\, and permission does not make an old revision current\. On a stale refusal\, inspect again and reconsider the action\; do not merely substitute a newer token into an unchanged request\. These revisions are domain\-specific\. Seed Desk’s token\, Review Desk’s counter\, a workbook page revision\, and a provider\-facing session ID are not interchangeable concurrency controls\. The generic wrapper’s supported pre\-approval input replacement and Review Desk’s pending\-dialog generation invalidation also remain different mechanisms\. ### UI\, launch\, and child construction are distinct boundaries [When the host can ask]() separates terminal presence from an installed UI adapter\. RPC can provide select requests through its transport\. ACP form support is capability\-dependent\, and a non\-no\-op adapter can still return an unavailable value for a particular operation\. Print\/no\-UI execution fails closed when this generic gate requires a prompt\. None of those statements proves physical keyboard behavior or every native component\. [Configuration and launch precedence]() explains why a displayed always\-ask setting can coexist with wrapper yolo\: the execute\-time autoApprove boolean can outrank the configured mode\. This does not remove an effective explicit deny or acknowledge pending provider safety checks\. [Subagents and inherited policies]() traces both Task construction and `TanCommandController.start()` to `createSubagentSettings()`\. The helper defaults child mode to yolo while retaining per\-tool policy values\, and explicit helper overrides are applied afterward\. Initial construction\, later live runtime inputs\, and conversation ancestry are not one inheritance contract\. No universal live synchronization or safeguard clone is established\. ### Reload is not a universal revocation boundary The source’s `AgentSession.reload()` reopens the current session through `switchSession()`\. It does not establish that every extension factory is imported and rebound\. Review Desk uses the switch path to invalidate its authority\. Field Notes deliberately retains its factory\-local selection\. Therefore neither “reload clears everything” nor “reload preserves everything” is a sound rule\. State the intended lifetime\, implement its transitions\, and test those transitions through the actual host\. Restarting the explicit launch is the source workbook’s reliable procedure for testing extension code edits\, not a claim that every hot\-reload route is equivalent\. ### Give the agent an interface\, not implied authority A model\-required capability needs a supported tool\, not a suggestion to invoke a human slash command\. Humans and tools should share mandatory domain rules when both can reach the same action\. A human command path is not cryptographic proof of a human keystroke\: SDK and RPC hosts can deliberately dispatch command text\. Host approval controls execution under the host’s policy\. Domain grants control the example’s operation\. Pending provider safety acknowledgement is another gate\. Operating\-system and broker policy control a different boundary\. The supplied `isProjectTrusted()` compatibility method and trusted\-file selection do not sandbox arbitrary extension JavaScript or its imports\. This matters especially for unattended tangents and permission\-denied file fallbacks\. Verify the actual subagent settings and installed safeguards rather than assuming Main’s experience follows it\. A fallback adapter must refuse the wrong session or destination and rely on a real broker\; returning success before the exact write has completed is not permission\-aware behavior\. That is a host\-design contract\, not a request to use a privileged broker for this workbook\. [Approval is not a sandbox]() preserves the distinction between application admission\, a denied primitive\, and a verified effect\. **Source trail\:** [Seed Desk reservations]()\, [Review Desk]()\, [Discovery\, installation and reload]()\, and [File fallbacks]()\. Supplied examples include `examples/seed-desk/03-reservations/desk.ts` — `reconstruct`\, `changeReservation`\; `examples/review-desk/index.ts` — `stateFor`\, `invalidateAuthority`\; and `examples/package-lab/multi/index.ts` — the factory\-local `selected` variable\. New permissions anchors include `packages/coding-agent/src/tools/approval.ts` — `resolveApproval`\; `extensibility/extensions/wrapper.ts` — `ExtensionToolWrapper.execute`\; `modes/rpc/rpc-mode.ts` — `runRpcMode`\; and `task/executor.ts` — `createSubagentSettings`\, with the latter abbreviated paths relative to `packages/coding-agent/src/`\. Their recorded checks remain scoped in [Permissions evidence]()\. Related chapters\: - [Prepare a reversible lab]() - [Seed Desk\: reservations on the active branch]() - [Review Desk\: edit and decide locally]() - [Package Lab\: one file to an embedded host]() - [Discovery\, installation and reload]() - [Tools\, interception and native delegation]() - [Permission\-denied file fallbacks]() - [Decision Desk refusals and failures]() - [2\. Start from Main]() - [Four places knowledge can live]() - [Approval Desk\: modes and policies]() - [Dispatch Desk\: device and path gates]() - [Boundary Desk\: one call at a time]() - [Boundary Desk\: when the host can ask]() - [Configuration and launch precedence]() - [Subagents and inherited policies]() - [Approval is not a sandbox]() - [Recovery without widening permission]() ## A result\, a receipt\, and permission to share are different facts The word done often hides a chain of independent claims\. Work may have returned text\, stored a body\, delivered it to an owner\, scheduled a turn\, satisfied an assignment\, received approval\, or disclosed data\. None of those facts automatically establishes the next\. ### Keep the claims separate | Fact | Useful evidence | Limit | | --- | --- | --- | | Returned output | The actual tool result\, assistant text\, transcript\, or returned artifact\. | A preview may be incomplete\; the initial Tan job returns its last assistant text\, which may be a later follow\-up rather than the earlier report\. | | Delivery | A receipt or an identified owner\-routed result\. | Delivery is not compliance\, a model reply\, or a completed project check\. | | Observation | A query\, inspection\, or recovered result at a particular time\. | Observation can change delivery bookkeeping\; it is not always repeatable retrieval of the same body\. | | Completion | A settled operation plus evidence for the requested outcome\. | A completed job can still have failed its assignment\. | | Approval | A scoped host decision or domain grant for the intended action\. | Approval to edit or accept locally is not permission to disclose the transcript\. | | Disclosure | Data leaves its prior trusted boundary or an access\-bearing copy is provided\. | Encryption\, redaction\, a hidden panel\, or UI cancellation does not alone make disclosure authorized or reversible\. | ### A delivered body and a scheduled wake are not the same result The extension delivery coordinator makes this explicit\. `captureSessionTarget()` records an owner anchor\. `deliverMessage()` reports whether a body was deferred\, committed\, or already committed\, and separately reports wake state\. A committed body with a pending wake is not missing content\. Retain the same target\, namespace\, delivery ID\, and body for a legitimate retry\. Creating a new identity to recover a missing reply can duplicate delivery\. A fork does not inherit the original owner’s delivery authority merely because it contains related conversation text\, and moving away from the anchor or across a reset boundary can make delivery inadmissible\. Tan’s job delivery is a different interface\, but it teaches the same distinction\. Hub `jobs` or `wait` can recover a settled result and suppress duplicate automatic delivery\. Later snapshots may omit the body because it was already delivered or recovered\. Read the earlier result\, the actual returned full\-output artifact\, or the transcript\; do not infer that no output existed or construct an ordinary\-task artifact URL for a tan\. ### Presentation is not content policy Extension result `content` is the model\-facing path\; `details` is not automatically replayed to the model\. Decision\-critical fields need an appropriate model\-visible representation\. Conversely\, `display: false` hides presentation without making custom\-message content invisible to the model\. The same distinction appears in Memory\: recalled material enters model context\. Local storage does not prove no egress\. It also appears in export\: filters\, collapsed sections\, and a blank viewer do not remove embedded bytes\. ### Choose the copied representation before considering a recipient A live dump uses current context and can include current system\/tool information and a temporary sidecar\. A file\-based HTML export uses saved history without reconstructing a running agent’s current prompt inventory\. Ordinary HTML can embed pre\-clear and nested history\. Default sharing builds a different snapshot and does not collect adjacent nested transcripts\; a custom TUI share handler receives ordinary HTML instead\. Those differences are not privacy rankings\. They are reasons to inspect the exact representation selected for the purpose\. The current HTML viewer also depends on external CDN scripts\: embedded data does not make it a self\-contained offline viewer\. Raw or decoded fictional data remains inspectable when scripts are blocked\. Redaction depends on the available obfuscator and its recognized fields and strings\. Images\, unknown values\, and some identifying metadata can remain\. Encryption protects access to the sealed representation\, while the complete fragment\-bearing link grants decryption access\. Size trimming removes evidence\, not necessarily sensitive content\. Sharing cancellation has the separate late\-completion boundary explained in [Changing focus\, stopping work\, and cancelling disclosure]()\. Review Desk’s `accepted` status is a useful final check on vocabulary\: it records a local decision and publishes nothing\. Do not promote that fact into approval to share a packet\. **Source trail\:** [Observe jobs and read results]()\, [Owner\-addressed delivery]()\, [Choosing a snapshot]()\, and [Sharing]()\. Cited anchors include `AsyncJobManager.consumeJobResults`\, `ExtensionDeliveryCoordinator`\, `buildSessionData`\, `collectSubSessions`\, `buildShareSnapshot`\, and `shareSession` in their source chapters\. Related chapters\: - [4\. Steer and queue work]() - [6\. Observe jobs and read results]() - [7\. Continue a finished tan]() - [Tools\, interception and native delegation]() - [Background work and owner\-addressed delivery]() - [Review Desk\: edit and decide locally]() - [Privacy and costs]() - [Review Packet choosing a snapshot]() - [Review Packet local HTML export]() - [Review Packet reading the whole packet]() - [Sharing is a separate disclosure decision]() ## Match each claim to the layer that was checked This book contains implementation explanations\, completed recorded checks\, fictional expected outcomes\, and browser\-readable lesson state\. The useful question is not whether something was tested in the abstract\, but whether the named check reaches the effect being claimed\. ### Preserve the original proof boundaries | Source | Recorded evidence retained here | Boundary that remains | | --- | --- | --- | | Memory | Sanitized configuration inspection and source\-grounded lifecycle and command explanations\. | No memory\-content audit\, database\-health check\, or actual provider resolution was established\. | | Tan | Nine isolated runtime scenarios and a report of 136 passing focused tests\. | Mock provider and recording UI\; no physical keyboard proof\, real task\-quality result\, or guaranteed restart rediscovery\. | | Extensions | 312 passing contract tests across 22 files\, 1\,039 assertions\, strict checking of supplied example TypeScript\, and 44 isolated example scenarios\. | No live provider\/OAuth\, real elevated broker\, full physical\-terminal audit\, or general cross\-process coordination proof\. | | Continuity | 38 passing checks across Return Desk\, Decision Desk\, and Review Packet\, plus a separate headless\-browser report\. | Read\-only RPC startup\, inert or synthetic seams where stated\, intercepted sharing\, and no physical TUI or real upload proof\. | These counts belong to different historical reports\. They are not one newly executed unified suite\. The original source and evidence chapters retain the narrower qualifications\, including tests added during their own publication review\. A successful domain transition does not prove loader wiring\. A loader scenario does not prove model tool choice\. An RPC roundtrip does not prove a physical terminal’s key decoding\. A controller test that intercepts an OS\-open request does not prove a desktop viewer opened\. The same discipline applies to a reader’s own observations\. ### The unified browser interface is a worked boundary\, not an OMP connection The reading\-site contract names `window.ompWorkbook`\, version 1\, with tutorial\-only scope\. Its [machine\-readable contract]() and live discovery describe the loaded interface\. They do not expose a session journal\, provider\, filesystem\, or command runner\. | Operation | Reading use | Limit | | --- | --- | --- | | `discover()` | Obtain schemas\, permissions\, page\/explorer scope\, exact registered controls\, and availability\. | Do not infer a control from its visible label or from a pattern in another page\. | | `inspect()` | Read the current document revision\, page\, explorer\, checklist\, clipboard\, navigation\, disclosures\, and controls\. | The result describes tutorial state only\. | | `query()` | Search authored chapter titles and text across the book\. | Results are excerpts\, not proof that another chapter is visible or that OMP contains matching data\. | | `act()` | Request a supported native click\, disclosure state\, or checkbox state using a fresh revision\. | A navigation result is a request\, not confirmed loading\; a checked lesson is self\-report\. | | `wait()` | Observe a newer matching revision in the current document within a bounded deadline\. | It cannot follow cross\-document navigation or establish real work completion\. | | `diagnose()` | Inspect tutorial runtime\, storage\, clipboard capability\, and control integrity\. | `connectedToOMP` is false and OMP health is not assessed\. | Query text is bounded to 240 characters\, with a result limit from 1 to 10\. The wait deadline is 0–5000 milliseconds\, defaulting to 1500\. Wait conditions can identify a page\, story\, or stage\; a stage requires its owning story\. Obtain actual IDs through discovery rather than inventing them\. Inspect immediately before an action and pass the opaque revision unchanged\. Focus\, scroll\, viewport\, disclosure\, clipboard\, and other native changes can invalidate it\. On a stale revision\, inspect and reassess\. Hidden\, disabled\, detached\, or closed\-disclosure targets are not permission to bypass the interface by modifying the DOM\. After a native navigation request\, inspect the destination document\. New or restored documents issue their own revisions\, and leaving the old document invalidates pending waits there\. An unchanged idempotent action need not create a newer revision\, so a timeout is not evidence that a requested transition happened\. ### Progress and copying remain local claims Unified checklist reads\, writes\, and reset use only `omp-workbook-checklist-v1`\. Storage can fail\; a failed reset may leave an earlier record\. Saved state is the last local observation\, without multi\-tab locking\. Visiting a chapter or selecting an example milestone does not verify or automatically complete its exercise\. Clipboard confirmation requires the write promise to resolve before the contract’s 2500\-millisecond deadline\. Manual selection is not confirmed copying\. Denial or timeout does not prove a late browser write is impossible\, and copying never executes the snippet\. The [Memory lab]() deliberately keeps its separate version\-1 `window.memoryTutorial` interface and `omp-memory-workbook:checklist:v1` storage\. Its stage selection is fictional\, not a successful retain or recall\. If a page interface is unavailable\, use the complete authored Markdown rather than inventing a network API\. **Source trail\:** the supplied unified browser reading contract\; the Memory lab HTML and [browser\-interface chapter]()\; [Extension verification levels]()\; and each part’s complete evidence chapter\. This editorial assembly adds no new browser\, OMP\, provider\, or filesystem execution result\. Related chapters\: - [Browser agent interface]() - [Your checkpoint]() - [Sources\, method and limitations]() - [Evidence and method]() - [Review Desk\: a native panel and portable dialogs]() - [Debugging and verification]() - [Evidence and method]() - [Start here]() - [Review Packet reading the whole packet]() - [Evidence and limitations]() ## Shared glossary These terms describe boundaries that recur throughout the book\. They are grouped by the confusion they resolve\, not by API name\. ### State\, identity\, and scope **Live context\, model context\, and journal\.** Live messages are held by the running agent\. Model context is prepared from that state through conversion and transformation boundaries\. The durable JSONL journal can retain older and alternative entries that are not in current model context\. None is automatically an exact captured provider request\. See [the continuity ledger]()\. **Persistent session identity and provider\-facing identity\.** `SessionManager.getSessionId()` identifies the saved conversation’s header identity\. In the described implementation\, `AgentSession.sessionId` is provider\-facing\. `/fresh` can change the latter while preserving the former\. A provider prompt\-cache key is another value\; sharing or inheriting one does not prove a cache hit or savings\. **Entry\, leaf\, and branch\.** An entry is a journal record with its own identity and parent relationship\. The leaf selects a current path through those records\. A branch is not every entry in the file\. Seed Desk reconstructs state from `getBranch()` so a sibling snapshot is not silently treated as current\. Tree navigation and a new\-file conversational fork are different operations\. **Reset boundary\.** A saved `reset_boundary` tells supported context rebuilds where cleared conversation context stops contributing\. It does not remove earlier journal entries\, erase a memory backend\, scrub exports\, or restore workspace files\. **Cwd and project scope\.** Cwd is the working directory associated with an operation or session\. Launch cwd\, recorded header cwd\, and active runtime cwd can differ during fallback or failure\. Memory’s recorded per\-project bank uses resolved cwd\, not Git root\. Extension\-module discovery and skill discovery also have different traversal rules\. **Durable memory\, bank\, store\, and injection\.** Durable memory is retained material available for later retrieval\. A bank identifies retrieval\/storage scope\; a row’s store affects what edits are supported\. Injection is the selected memory instructions and recalled text placed into current context\, not the entire database\. The recorded Mnemopi working\, episodic\, and extracted\-fact behaviors are not interchangeable\. See [the Memory command desk]()\. **Global override and resolved default\.** These describe where a configuration value came from\. A persisted global override is not proof of a global memory bank\, successful runtime initialization\, or healthy provider access\. The Memory table reports a snapshot\, not a current\-machine audit\. **Runtime override and effective wrapper policy\.** A `Settings.override()` value is not persisted like `Settings.set()`\. The approval wrapper also reads execute\-time `autoApprove` separately from settings\. A displayed approval mode can therefore differ from the mode the wrapper uses\. Configuration inspection is not a live audit of another call or process\. See [Configuration and launch precedence]()\. **Compaction and managed skill\.** Compaction makes room by summarizing active conversational context\. A managed skill is separately stored procedural guidance in a `SKILL.md` file\. Neither is a database wipe\, a guaranteed complete record\, or a deterministic script that automatically executes\. See [four places knowledge can live]()\. ### Workers\, views\, and lifetimes **Tan\.** An OMP tangent subagent\: a contextual\, tool\-capable child conversation that can run concurrently with Main\. It is not TanStack\, an ordinary task subagent under every task\-executor convention\, or an isolated checkout\. **Agent ID\, job ID\, and process name\.** The agent ID addresses a conversation\/registration\. The background job ID addresses a managed run\, notably the initial Tan run\. A process name addresses a separately supervised server\, watcher\, debugger\, or similar process\. Discover their actual association before acting\; a shared display label is not a mapping\. **Focus\.** The currently addressed chat view\. Selecting a Hub row is not yet successful focus\. Automatic return to Main can change the recipient of an unfinished draft\. Closing an overlay may reveal the prior chat rather than Main\. See [Leave and switch safely]()\. **Running\, idle\, parked\, aborted\, and absent\.** These are agent lifecycle states\, not background\-job outcomes\. Idle has an attached live session\; parked requires revival for new work\; aborted is terminal in the explicit\-kill case\; absent means no current registration\, not necessarily no transcript\. Check job state separately\. **Cold revival\.** Reconstructing an eligible parked agent from retained history and saved initialization information using available host resources\. It does not restore a complete old runtime\, restart the original job\, or guarantee identical tools\, settings\, model\, or resource mappings\. **Steering and follow\-up\.** Steering changes the direction of current work at supported agent\-loop boundaries\. A follow\-up waits until the current work would otherwise yield\. Focused Enter\, the follow\-up chord\, and peer messaging are distinct input paths\. Queued does not mean processed\, persisted as a durable ticket\, or completed\. **Turn and run\.** A run can contain several assistant turns\, tool results\, and maintenance continuations\. Memory’s periodic retention threshold counts new USER turns\, not assistant replies or tool calls\. Auto\-learn’s eligible tool\-call threshold is a separate loop\. Keep each source’s counting unit attached to its setting\. **Conversation fork and workspace isolation\.** A fork separates conversation identity or history paths\. It does not create a Git branch\, worktree\, repository snapshot\, or rollback mechanism\. Shared file effects are already present in the shared workspace\; there is no automatic Tan merge operation\. **Initial child settings and live inheritance\.** `createSubagentSettings()` snapshots base values\, defaults child approval mode to yolo\, and then applies explicit helper overrides\. Both Task construction and the supplied initial Tan controller use it\. Per\-tool policy values remain relevant\. Later live runtime inheritance\, shared callbacks\, and revival are separate paths\; conversation ancestry does not clone every safeguard or prove permanent synchronization\. Provider service\-tier inheritance is not read\/write\/exec tier inheritance\. **Module\-local\, factory\-local\, and branch\-local\.** Module state can be shared through cached imports\. Factory\-local state belongs to one binding\, which can survive transcript changes\. Branch\-local state is reconstructed from the selected journal ancestry\. The word session\-local is too imprecise unless the actual lifetime is stated\. See [Package Lab]()\. **Reload\, rebind\, and new session\.** Reload may reopen a journal\. Rebinding calls a prepared factory against a fresh runtime\. A new session changes conversation identity but can reuse extension closures\. None should be used as shorthand for all three effects\. ### Authority\, results\, and observation **Host approval\, domain grant\, and trust\.** Host approval gates a tool under host policy\. A domain grant authorizes a particular application action\, often with identity and revision limits\. Trust in an in\-process extension permits code execution\; it is not an operating\-system sandbox\. A grant cannot be inferred from draft text\, a recalled memory\, or an MCP notification\. **Tool availability and presentation\.** Availability concerns whether a capability is enabled and reachable in the actual session\. `loadMode` concerns presentation of an enabled tool\, not permission for every call\. An enabled mounted device can be absent from the top\-level schema\. An allow policy does not install a missing tool\. **Tool tier\.** The `read`\, `write`\, or `exec` declaration used by approval resolution\, possibly computed from arguments\. An omitted declaration defaults to exec\. A tier is not a sandbox\, syscall audit\, or proof of zero effects\: some declared read operations change agent\/job state\, and ordinary reads can use the network\. It is unrelated to a provider’s processing service tier\. **Approval mode\.** The default tier comparison\: `always-ask` admits read\; `write` admits read and write\; `yolo` admits all tiers\. Higher\-precedence applicable policies remain relevant\. The schema default in the permissions snapshot is yolo\, not a claim about the reader’s settings\. Always\-ask does not mean every call prompts\. **Approval policy and provenance\.** `allow`\, `prompt`\, and `deny` are resolver outcomes and supported explicit policies\. Tool deny and effective user deny precede automatic admission\. Explicit tool allow\/prompt can outrank non\-deny user policy\. A resolved `source` identifies tool\, user\, or mode where supplied\; it is not execution evidence\. See [Approval Desk]()\. **Policy key and invoking\-tool fallback\.** `policyKey` lets a declaration select another user\-policy identity\, such as a device reached through write\. A missing or invalid keyed policy falls back to the invoking tool’s policy\. A valid keyed policy replaces that fallback\, including a fallback deny\; the lookup is not an intersection of every entry\. Raw property presence can still matter to a later wrapper predicate even when normalization ignored its value\. **Override\-only prompt and explicit prompt\.** `override: true` without an explicit policy requests prompting in non\-yolo resolution but is ignored in yolo\. An explicit tool prompt survives the resolver’s yolo branch\. An override combined with explicit tool allow remains allow after deny checks\. Forwarded xdev prompting has an additional wrapper predicate\, so resolver policy and actual nested prompt count are not interchangeable\. **AutoApprove\.** The execute\-time boolean that makes the wrapper use yolo before resolution\. The supplied built\-in CLI sets it through `--auto-approve` or `--yolo`\, not a listed `-y` alias\. It can outrank a displayed explicit approval mode but does not remove effective explicit denies or acknowledge pending provider safety checks\. **One\-call approval and declined call\.** The generic wrapper offers Approve and Deny\. Only exact Approve is positive\; dismissal\/undefined is refused\, and a throwing selector stops the call\. The answer does not persist an allow\-for\-session policy\. A declined call is different from a configured deny and does not undo earlier effects\. **Forwarded xdev approval\.** `xdevApproved` is context used to suppress a particular unchanged\-input duplicate prompt after an outer write gate\. Explicit user policy\, surviving overrides\, provider checks\, and supported input replacement affect the inner decision\. The source tests object identity\, not a domain revision hash\. It is not an arbitrary nested\-tool grant\. See [Dispatch Desk]()\. **Pending provider safety checks\.** Computer\-provider metadata can require explicit acknowledgement independently of ordinary tier admission\. The wrapper sets `providerSafetyApproved` after the required positive selection\. Synthetic metadata tests prove that local transition\, not provider delivery\, physical computer behavior\, or the entirety of provider safety policy\. **Permission\-denied file fallback\.** A later seam for selected denied native byte writes or unlinks\, not the approval dialog and not an elevated writer by itself\. Write and delete registries are separate and process\-wide\; requests identify origin and resolved target according to the primitive\. A handler’s true result is a durability\/completion contract\, not a grant or independent proof\. Unsupported routes and host policy remain separate\. **Revision\.** A precondition token or counter whose meaning belongs to its issuer\. Seed Desk uses session and state\-entry identity\; Review Desk uses a numeric domain counter with separate authority invalidation\; the website uses opaque document revisions\. A content revision identifies authored material\, not the fresh page state required by `act()`\. The generic tool approval does not replace these domain preconditions\. **Returned content and structured details\.** Extension tool `content` is the normal model\-facing result\. `details` is host\/rendering metadata and is not automatically model\-visible\. A custom renderer or notification is presentation\, not a substitute for a complete queryable result\. **Owner anchor\, delivery ID\, receipt\, and wake\.** An owner anchor records where delayed work belongs\. A stable delivery ID supports deduplicated retry\. The receipt describes body admission or commitment\, while wake describes whether another agent turn is scheduled or pending\. A committed body is not proof that the model answered it\. See [owner\-addressed delivery]()\. **Read\-only observation\.** Read\-only names the intended mutation boundary\, not a universal promise of zero side effects or disclosure\. A Main request can require model use\; a Hub job inspection can consume delivery bookkeeping\; an extension’s show command can append a custom message\. Read the exact operation contract\. Do not silently equate this phrase with every operation declared read\-tier\. **Completion\.** Settlement of an operation and correctness of an assignment are different claims\. A completed job\, accepted message\, nonthrowing domain refusal\, or success banner must be interpreted through its actual result fields and postconditions\. Approval requested\/resolved events and prompt counts likewise do not replace an execution or effect count\. **TUI\, RPC\, and ACP\.** TUI is terminal presentation and input\. RPC and ACP provide host\/client protocol surfaces\, with adapter\-specific semantic UI\. `hasUI` does not mean every terminal component\, dialog option\, or composer method works\. Protocol proof is not physical terminal proof\. In the supplied approval runner\, `hasUI()` tests for a non\-no\-op adapter\; RPC can install a select\-capable adapter\, while ACP form support depends on negotiation\. ### Copies\, disclosure\, and evidence **Artifact and internal resource address\.** Artifacts are stored outputs or session\-adjacent resources\, not necessarily workspace files\. `memory://`\, `history://`\, `local://`\, `artifact://`\, and `agent://` are OMP resource schemes with different handlers\, not HTTP endpoints on this site\. Follow actual returned IDs and links\; a Tan transcript does not imply an ordinary\-task result artifact exists\. `xd://` is a tool\-dispatch address\, not an operator grant\. **Sidecar\.** An auxiliary file whose meaning depends on the operation\: a dump JSON file\, a memory database companion\, or an agent tombstone are not the same object\. Temporary or adjacent does not mean automatically deleted\, fully backed up\, or safe to disclose\. **Dump\, export\, and share\.** A dump represents current context and can create clipboard text plus a temporary sidecar\. HTML export copies session\-manager history\, with live versus file\-based metadata differences and possible nested transcripts\. Sharing uses a default snapshot or a custom executable route and is a separate disclosure decision\. See [choosing a snapshot]()\. **Embedded and offline\.** Embedded data can be recovered from a file even when its viewer fails\. The described HTML viewer still depends on CDN scripts\; the recorded blocked\-script case displayed controls but no transcript\. Base64 encoding is not encryption\. **Redaction\, encryption\, trimming\, cancellation\, and revocation\.** Redaction transforms selected outgoing data according to available recognition and field rules\. Encryption controls access to a sealed representation\. Trimming loses content to meet a size budget\. Cancellation may stop only a particular phase or UI\. Revocation would withdraw access or authority\; no generic share\-link revocation workflow is established here\. None substitutes for recipient and purpose approval\. **Recorded observation\, source\-backed expectation\, and exercise\.** A recorded observation belongs to the named historical check\. A source\-backed expectation follows the supplied source account\. An exercise is a result to reason about or independently test\. Browser lesson ticks are a fourth thing\: self\-report\. Combining the books does not upgrade any of these into new live verification\. The permissions cases’ expected fields remain authored data\; their separate executed report supplies observations for the named cases only\. ## Next steps The durable skill in this workbook is not command memorization\. It is the ability to say exactly what changed\, what stayed available\, who had authority\, and what evidence supports that account\. A useful conclusion may be a verified local result\. It may also be a refusal\, an unavailable dependency\, an ambiguous identity\, or an inspection gap\. Reporting that boundary accurately is better than manufacturing success by changing settings\, supplying credentials\, guessing a target\, or widening permissions\. ### A safe workflow for the next piece of work 1. **Choose the need before the mechanism\.** Returning to history\, recalling evidence\, asking a tangent\, understanding a tool decision\, and adding a capability are different needs\. Use a reading path and its source chapters before selecting a command or API\. 2. **Establish the target and scope\.** Record the persistent session identity and file when relevant\, the active cwd\, the exact agent\/job association\, the tool and any inner device operation\, or the domain object and revision\. Do not use a title\, row number\, or success toast as the sole identity check\. 3. **Choose an owned practice surface\.** Use the Memory simulator\, printed Tan fixtures\, inert permissions cases\, or a disposable copy of the supplied examples\. Keep personal journals\, memory rows\, settings\, credentials\, and real review packets out of the workbook route\. 4. **Predict the boundary\.** Write down the state expected to change and at least one state expected not to change\. Include authority\, pending work\, and copies outside the immediate view\. For a tool decision\, name the applicable policy key and effective mode rather than relying on the displayed tool label alone\. 5. **Use one supported action or inspection\.** Follow the original caption and prerequisites\. Printing a native command is not running it\; selecting a simulator stage is not a real memory operation\; reading an approval case is not answering a live dialog\. Stop at setup\, identity\, permission\, or compatibility failures rather than silently substituting another path\. 6. **Check the specific postcondition\.** Inspect the relevant complete state\, journal\, result body\, or owned file\. Use the original chapter’s falsifiable acceptance checks\. A receipt is evidence about its own operation\, not automatic proof of project correctness\. An approval is not proof of execution\, and execution is not proof that the intended effect succeeded\. 7. **Record the result at its real verification level\.** Separate what the source predicts\, what the historical report observed\, and what you personally observed\. Mark unexecuted or blocked checks as such\. Keep complete sensitive diagnostics private\. 8. **Finish without crossing another boundary accidentally\.** Returning to Main is not cancellation\. Cancellation is not undo\. A local accepted draft is not published\. No cleanup is needed for reading the permissions cases\. Any later disposal is limited to exclusively owned exercise material no longer needed\; destructive session or memory commands are not a cleanup shortcut\. ### Make the next check falsifiable The supplied stories provide concrete standards without requiring a new live service experiment\: | Learning target | Check to carry forward | Claim to avoid | | --- | --- | --- | | Continuity | The intended journal identity and active project scope agree with the selected fictional target\; today’s workspace still has today’s label\. | Reopening yesterday restored yesterday’s files\. | | Memory | The simulator reports fictional tutorial state\; the source correction workflow requires an exact ID and full row content before an edit\. | Selecting a stage saved or recalled a real memory\. | | Tan control | The intended agent\, any current backing job\, and the current input recipient are separately identified\; available output is read in its actual form\. | A job label\, delivery receipt\, or automatic return establishes successful work or terminal agent removal\. | | Permissions | Explain the exact policy source and key\, required prompt count\, and recorded execution count\; distinguish denial\, dismissal\, unavailable UI\, revised input\, and an OS error\. | No prompt proves safety\, Approve persists a blanket grant\, or yolo supplies OS authority\. | | Extension design | The original domain checks distinguish stale revision\, missing grant\, cancellation\, and a successful mutation\; the relevant host scenario reaches the layer being claimed\. | A resolved promise\, registered tool\, or visible widget proves the full workflow\. | | Packet review | The fictional parent\, pre\-clear material\, and nested records are inspected through an available raw\, decoded\, or explicitly permitted rendered route\. | A blank viewer\, hidden panel\, encrypted link\, or cancelled loader proves privacy\. | For an offline extension starting point\, the original [debugging chapter]() contains a complete Review Desk domain\-test exercise\. Use its existing code and stated limits rather than adding a provider call merely to make the exercise feel more complete\. For continuity\, begin with [the ledger’s fixture inspection]()\. For Memory\, begin in [the local fictional lab]()\. For Tan\, the [already\-running chapter]() is the immediate control reference\, while its fictional assignments can be studied without launching work\. For permissions\, compare `boundary-approval-does-not-persist` in [Boundary Desk’s data]() with `dispatch-explicit-prompt-twice` in [Dispatch Desk’s data]()\. Both recorded two prompts and one inert execution\, but for different reasons\: two separate calls in the first case\, outer and inner gates for one dispatch in the second\. If your explanation treats them as the same lifetime\, return to [One call at a time]()\. Use [Recovery without widening permission]() to finish with a precise blocked outcome rather than a broader policy\. ### Keep disclosure as a separate decision Nothing about finishing the book authorizes publishing a real transcript\, dump\, sidecar\, memory\, or complete access\-bearing share link\. The [safe disclosure checklist]() applies to the actual outgoing representation\, not merely its visible page\. If inspection is incomplete\, hold the packet\. Do not run a share to discover its policy or repeat an ambiguous share to recover a URL\. Likewise\, no additional authentication\, provider inference\, destructive session operation\, privileged\-broker exercise\, personal settings change\, or live upload is needed to complete this unified route\. Service adapters remain contracts until their real prerequisites and separately authorized verification exist\. A tool\-tier declaration is not a substitute for that authorization\. Carry the six connections into future work\: distinguish stores\, distinguish forks\, stop the owned operation\, bind authority to a lifetime\, separate delivery from disclosure\, and match evidence to its layer\. Those habits make both operation and extension design easier to explain\, recover\, and trust\.