pi-btw 0.1.1 → 0.2.1

package/README.md

@@ -2,16 +2,18 @@
 
 A small [pi](https://github.com/badlogic/pi-mono) extension that adds a `/btw` side conversation channel.
 
-`/btw` runs immediately, even while the main agent is still busy.
+`/btw` opens a real pi sub-session with coding-tool access, and it runs immediately even while the main agent is still busy.
 
 ![BTW overlay example](docs/btw-overlay.png)
 
 ## What it does
 
 - opens a parallel side conversation without interrupting the main run
+- runs that side conversation as a real pi sub-session with `read` / `bash` / `edit` / `write` tool access
 - keeps a continuous BTW thread by default
 - supports `/btw:tangent` for a contextless side thread that does not inherit the current main-session conversation
-- streams answers into a widget above the editor
+- opens a focused BTW modal shell with its own composer and transcript
+- keeps the BTW overlay open while you switch focus back to the main editor with `Alt+/`
 - keeps BTW thread entries out of the main agent's future context
 - lets you inject the full thread, or a summary of it, back into the main agent
 - optionally saves an individual BTW exchange as a visible session note with `--save`
@@ -61,28 +63,38 @@ pi install /absolute/path/to/pi-btw
 
 - runs right away
 - works while pi is busy
+- creates or reuses a real BTW sub-session instead of a one-off completion call
 - continues the current BTW thread
-- streams into a widget above the editor
+- opens or refreshes the focused BTW modal shell
+- streams into the BTW modal transcript/status surface
 - persists the BTW exchange as hidden thread state
 - with `--save`, also saves that single exchange as a visible session note
 
+## Overlay controls
+
+- `Alt+/` toggles focus between BTW and the main editor without closing the overlay
+- `Ctrl+Alt+W` is a fallback focus toggle for terminals that do not deliver `Alt+/` as a usable shortcut
+- `Esc` still dismisses BTW immediately while the overlay is focused
+- BTW now opens top-centered so the main session remains visible underneath it
+
 ### `/btw:new [question]`
 
 - clears the current BTW thread
 - starts a fresh thread that still inherits the current main-session context
 - optionally asks the first question in the new thread immediately
+- if no question is provided, opens a fresh BTW modal ready for the next prompt
 
 ### `/btw:tangent [--save] <question>`
 
 - starts or continues a contextless tangent thread
 - does not inherit the current main-session conversation
 - if you switch from `/btw` to `/btw:tangent` (or back), the previous side thread is cleared so the modes do not mix
-- streams into the same above-editor widget
+- opens or refreshes the same focused BTW modal shell
 - with `--save`, also saves that single exchange as a visible session note
 
 ### `/btw:clear`
 
-- dismisses the BTW widget
+- dismisses the BTW modal/widget
 - clears the current BTW thread
 
 ### `/btw:inject [instructions]`
@@ -100,12 +112,34 @@ pi install /absolute/path/to/pi-btw
 
 ## Behavior
 
+### Real sub-session model
+
+BTW is implemented as an actual pi sub-session with its own in-memory session state, transcript events, and tool surface.
+
+- contextual `/btw` threads seed that sub-session from the current main-session branch while filtering out BTW-visible notes from the parent context
+- `/btw:tangent` starts the same BTW UI in a contextless mode with no inherited main-session conversation
+- the overlay transcript/status line is driven from sub-session events, so tool activity, streaming deltas, failures, and recovery are all visible without scraping rendered output
+- handoff commands (`/btw:inject` and `/btw:summarize`) read from the BTW sub-session thread rather than maintaining a separate manual transcript model
+
+### In-modal slash behavior
+
+Inside the BTW modal composer, slash handling is split at the BTW/session boundary:
+
+- `/btw:new`, `/btw:tangent`, `/btw:clear`, `/btw:inject`, and `/btw:summarize` stay owned by BTW because they control BTW lifecycle or handoff behavior
+- any other slash-prefixed input is routed through the BTW sub-session's normal `prompt()` path
+- this means ordinary pi slash commands like `/help` are handled by the sub-session instead of being rejected by a modal-only fallback
+- if the sub-session cannot handle a slash command, BTW surfaces the real sub-session failure through the transcript/status state instead of inventing an "unsupported slash input" warning
+
+This keeps BTW-owned lifecycle commands explicit while giving the side conversation the same slash-command surface as the underlying sub-session.
+
+## Behavior
+
 ### Hidden BTW thread state
 
 BTW exchanges are persisted in the session as hidden custom entries so they:
 
 - survive reloads and restarts
-- rehydrate the BTW widget for the current branch
+- rehydrate the BTW modal shell for the current branch
 - preserve whether the current side thread is a normal `/btw` thread or a contextless `/btw:tangent`
 - stay out of the main agent's LLM context