pi-btw 0.5.0 → 0.6.0

package/README.md

@@ -11,7 +11,9 @@ A small [pi](https://github.com/earendil-works/pi-mono) extension that adds a `/
 - 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
+- accepts `/side` as an alias for the `/btw` entry command
 - supports `/btw:tangent` for a contextless side thread that does not inherit the current main-session conversation
+- supports `/btw:ask` for a read-only side thread that inherits main-session context but exposes only `read` / `grep` / `find` / `ls`
 - 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+/`, `Super+/`, or `Ctrl+Alt+W` (all remappable)
 - keeps BTW thread entries out of the main agent's future context
@@ -51,10 +53,13 @@ pi install /absolute/path/to/pi-btw
 
 ```text
 /btw what file defines this route?
+/side what file defines this route?
 /btw how would you refactor this parser?
 /btw --save summarize the last error in one sentence
 /btw:new let's start a fresh thread about auth
 /btw:tangent brainstorm from first principles without using the current chat context
+/btw:ask what does this module do?
+/btw:ask --save explain the latest test failure
 /btw:model openai gpt-5-mini openai-responses
 /btw:thinking low
 /btw:inject implement the plan we just discussed
@@ -77,6 +82,12 @@ pi install /absolute/path/to/pi-btw
 - persists the BTW exchange as hidden thread state
 - with `--save`, also saves that single exchange as a visible session note
 
+### `/side [--save] <question>`
+
+- alias for `/btw`, matching the equivalent command in Codex
+- shares the same thread, overlay, persistence, model, and thinking settings as `/btw`
+- `/btw` stays canonical; lifecycle commands remain under the `/btw:*` namespace, so there is no `/side:new` or `/side:clear`
+
 ## Overlay controls
 
 - `Alt+w` toggles the overlay between the framed window layout (inset from the terminal edges) and a full-width layout
@@ -107,6 +118,17 @@ pi install /absolute/path/to/pi-btw
 - opens or refreshes the same focused BTW modal shell
 - with `--save`, also saves that single exchange as a visible session note
 
+### `/btw:ask [--save] <question>`
+
+- starts or continues an enforced read-only side thread
+- inherits the current main-session conversation, exactly like `/btw`
+- exposes only pi's built-in read-only tools (`read`, `grep`, `find`, `ls`); `bash`, `edit`, and `write` are never available to it
+- follows up read-only for the lifetime of the thread
+- identifies the thread as read-only in the overlay title
+- if you switch between `/btw`, `/btw:tangent`, and `/btw:ask`, the previous side thread is cleared and the child session is recreated so the capability boundary stays unambiguous
+- 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 modal/widget
@@ -148,6 +170,7 @@ BTW is implemented as an actual pi sub-session with its own in-memory session st
 
 - 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
+- `/btw:ask` seeds the same main-session context as `/btw` but restricts the child session's tool surface to pi's read-only tools, so the boundary is structural rather than prompt-based
 - BTW can inherit the main thread model/thinking settings or use BTW-only overrides via `/btw:model` and `/btw:thinking`
 - `/btw:summarize` uses the current effective BTW model but keeps thinking off
 - 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
@@ -157,7 +180,7 @@ BTW is implemented as an actual pi sub-session with its own in-memory session st
 
 Inside the BTW modal composer, slash handling is split at the BTW/session boundary:
 
-- `/btw:new`, `/btw:tangent`, `/btw:clear`, `/btw:model`, `/btw:thinking`, `/btw:inject`, and `/btw:summarize` stay owned by BTW because they control BTW lifecycle, configuration, or handoff behavior
+- `/btw:new`, `/btw:tangent`, `/btw:ask`, `/btw:clear`, `/btw:model`, `/btw:thinking`, `/btw:inject`, and `/btw:summarize` stay owned by BTW because they control BTW lifecycle, configuration, 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
@@ -172,7 +195,7 @@ BTW exchanges are persisted in the session as hidden custom entries so they:
 
 - survive reloads and restarts
 - 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`
+- preserve whether the current side thread is a normal `/btw` thread, a contextless `/btw:tangent`, or a read-only `/btw:ask` thread
 - preserve the current BTW-only model and thinking overrides for that session history
 - stay out of the main agent's LLM context
 
@@ -210,6 +233,27 @@ To use it without installing:
 pi -e /path/to/pi-btw
 ```
 
+## DeepSeek Harness
+
+pi-btw also runs unmodified on [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) through the [pi2dsh](https://github.com/weijiafu14/pi2dsh) compatibility bridge.
+
+For DSH Web, install the **dsh-work-x** suite, which includes pi-btw, pi2dsh, a browser side-chat window, and other extensions:
+
+```bash
+dsh plugin --profile web add dsh-work-x
+```
+
+To install just the bridge and this extension instead:
+
+```bash
+dsh plugin --profile web add pi2dsh
+dsh plugin --profile web add pi-btw
+```
+
+Restart DSH after installation, then use `/btw <question>` to start a side conversation. The suite presents it in a browser side-chat window backed by a native DSH child session. DSH uses hyphens for the command family: for example, `/btw:inject` becomes `/btw-inject`.
+
+See the [DSH side-conversation guide](https://github.com/weijiafu14/pi2dsh/tree/main/examples/side-conversation) for CLI-only installation, usage, and screenshots, and the [versioned validation results](https://github.com/weijiafu14/pi2dsh/tree/main/community/release-0.25.1) for the tested releases. Report DSH integration problems to [pi2dsh](https://github.com/weijiafu14/pi2dsh/issues).
+
 ## License
 
 MIT

package/extensions/btw.ts

@@ -176,7 +176,7 @@ const BTW_CONTINUE_THREAD_USER_TEXT = "[The following is a separate side convers
 const BTW_CONTINUE_THREAD_ASSISTANT_TEXT = "Understood, continuing our side conversation.";
 
 type SessionThinkingLevel = "off" | AiThinkingLevel;
-type BtwThreadMode = "contextual" | "tangent";
+type BtwThreadMode = "contextual" | "tangent" | "readonly";
 type SessionModel = NonNullable<ExtensionCommandContext["model"]>;
 /**
  * Loose model reference parsed from `/btw:model <provider> <id> <api>` and persisted to
@@ -443,6 +443,17 @@ function formatModelRef(model: Pick<SessionModel, "provider" | "id" | "api">): s
   return `${model.provider}/${model.id} (${model.api})`;
 }
 
+/**
+ * Tool surfaces keyed by BTW mode. Read-only mode exposes only pi's built-in
+ * read-only tools so the child session cannot mutate the workspace; every other
+ * mode matches pi's default coding-agent toolset (read/bash/edit/write).
+ */
+const BTW_TOOLS_BY_MODE: Record<BtwThreadMode, readonly string[]> = {
+  contextual: ["read", "bash", "edit", "write"],
+  tangent: ["read", "bash", "edit", "write"],
+  readonly: ["read", "grep", "find", "ls"],
+};
+
 function buildBtwSeedState(
   ctx: ExtensionCommandContext,
   thread: BtwDetails[],
@@ -451,7 +462,7 @@ function buildBtwSeedState(
 ): { messages: Message[]; sideThreadStartIndex: number } {
   const messages: Message[] = [];
 
-  if (mode === "contextual") {
+  if (mode === "contextual" || mode === "readonly") {
     try {
       messages.push(
         ...(buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages as Message[]).filter(
@@ -1217,7 +1228,7 @@ function canRenderBtwOverlay(ctx: ExtensionContext | ExtensionCommandContext): b
 
 function notifyInlineQuestionRequired(
   ctx: ExtensionCommandContext,
-  command: "/btw" | "/btw:tangent" | "/btw:new",
+  command: "/btw" | "/btw:tangent" | "/btw:new" | "/btw:ask",
 ): void {
   notify(ctx, `${command} cannot open its composer outside Pi's TUI. Pass the question inline instead.`, "warning");
 }
@@ -1234,7 +1245,13 @@ const BTW_OVERLAY_CHROME_LINES = 9;
 const BTW_BLOCK_INDENT = "    ";
 
 function getOverlayTitle(mode: BtwThreadMode): string {
-  return mode === "tangent" ? "BTW tangent" : "BTW";
+  if (mode === "tangent") {
+    return "BTW tangent";
+  }
+  if (mode === "readonly") {
+    return "BTW ask · read-only";
+  }
+  return "BTW";
 }
 
 function buildTranscriptBadge(
@@ -1964,8 +1981,8 @@ export default function (pi: ExtensionAPI) {
       model: settings.model,
       ...modelRuntimeOptions,
       thinkingLevel: settings.thinkingLevel,
-      // Match pi's default coding-agent toolset (read/bash/edit/write).
-      tools: ["read", "bash", "edit", "write"],
+      // Read-only mode narrows this to pi's built-in read-only toolset.
+      tools: [...BTW_TOOLS_BY_MODE[mode]],
       resourceLoader: createBtwResourceLoader(ctx),
     };
     const { session } = await createAgentSession(sessionOptions);
@@ -2138,6 +2155,29 @@ export default function (pi: ExtensionAPI) {
       return true;
     }
 
+    if (name === "btw:ask") {
+      const { question, save } = parseBtwArgs(trimmedArgs);
+      if (!question && !canRenderBtwOverlay(ctx)) {
+        notifyInlineQuestionRequired(ctx, "/btw:ask");
+        return true;
+      }
+
+      // Read-only mode is a distinct capability boundary, so switching into it
+      // resets the thread and lets ensureBtwSession recreate the child session.
+      if (pendingMode !== "readonly") {
+        await resetThread(ctx, true, "readonly");
+      }
+
+      if (!question) {
+        await ensureBtwSession(ctx, "readonly");
+        await ensureOverlay(ctx);
+        return true;
+      }
+
+      await runBtw(ctx, question, save, "readonly");
+      return true;
+    }
+
     if (name === "btw:new") {
       const { question, save } = parseBtwArgs(trimmedArgs);
       if (!question && !canRenderBtwOverlay(ctx)) {
@@ -2274,7 +2314,7 @@ export default function (pi: ExtensionAPI) {
 
   function parseOverlayBtwCommand(value: string): { name: string; args: string } | null {
     const trimmed = value.trim();
-    const match = trimmed.match(/^\/(btw:(?:new|tangent|clear|inject|summarize|model|thinking))(?:\s+(.*))?$/);
+    const match = trimmed.match(/^\/(btw:(?:new|ask|tangent|clear|inject|summarize|model|thinking))(?:\s+(.*))?$/);
     if (!match) {
       return null;
     }
@@ -2755,6 +2795,13 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("side", {
+    description: "Alias for /btw: continue a side conversation in a focused BTW modal.",
+    handler: async (args, ctx) => {
+      await dispatchBtwCommand("btw", args, ctx);
+    },
+  });
+
   pi.registerCommand("btw:tangent", {
     description: "Start or continue a contextless BTW tangent in the focused BTW modal.",
     handler: async (args, ctx) => {
@@ -2762,6 +2809,13 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("btw:ask", {
+    description: "Ask a read-only side question: inherits main-session context but exposes only read/grep/find/ls tools.",
+    handler: async (args, ctx) => {
+      await dispatchBtwCommand("btw:ask", args, ctx);
+    },
+  });
+
   pi.registerCommand("btw:new", {
     description: "Start a fresh BTW thread with main-session context. Optionally ask the first question immediately.",
     handler: async (args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-btw",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A pi extension for parallel side conversations with /btw",
   "type": "module",
   "license": "MIT",

package/skills/btw/SKILL.md

@@ -22,10 +22,13 @@ Use these commands in your guidance to the user:
 
 ```text
 /btw <question>
+/side <question>
 /btw --save <question>
 /btw:new [question]
 /btw:tangent <question>
 /btw:tangent --save <question>
+/btw:ask <question>
+/btw:ask --save <question>
 /btw:clear
 /btw:model [<provider> <model> <api> | clear]
 /btw:thinking [<level> | clear]
@@ -33,6 +36,8 @@ Use these commands in your guidance to the user:
 /btw:summarize [instructions]
 ```
 
+`/side` is an alias for `/btw` and shares the same thread, overlay, and settings. `/btw` is canonical; the lifecycle commands stay in the `/btw:*` namespace.
+
 ## How to guide the user
 
 ### For a quick side question
@@ -45,6 +50,8 @@ Recommend:
 
 Use this when the user wants an immediate aside and does not need a visible saved note.
 
+Users coming from Codex may reach for `/side` instead; it is an alias for `/btw` and can be used anywhere `/btw` is used.
+
 ### For a saved one-off note
 
 Recommend:
@@ -87,6 +94,22 @@ or
 
 Use this when the user wants a side conversation that does not include the current main-session context.
 
+### For an enforced read-only side question
+
+Recommend:
+
+```text
+/btw:ask <question>
+```
+
+or
+
+```text
+/btw:ask --save <question>
+```
+
+Use this when the user wants a side question that inherits the current main-session context but must not be able to change anything. The read-only thread only has `read`, `grep`, `find`, and `ls`; it never has `bash`, `edit`, or `write`.
+
 ### To hand the full thread back to the main agent
 
 Recommend:
@@ -122,6 +145,7 @@ Use these when the main thread should keep its current model or thinking level,
 
 - Prefer `/btw` over normal chat when the user explicitly wants a side conversation.
 - Prefer `/btw:tangent` when the user wants that side conversation to be contextless.
+- Prefer `/btw:ask` when the user wants a side conversation that cannot modify the workspace.
 - Prefer `/btw:summarize` over `/btw:inject` for long exploratory threads.
 - Prefer `/btw:inject` when precise wording, detailed tradeoffs, or a full plan matters.
 - Suggest `/btw:new` before starting a totally unrelated side topic when main-session context is still useful.
@@ -156,6 +180,12 @@ When helping the user use BTW:
 /btw:tangent think through this from first principles without using the current chat context
 ```
 
+### Example: ask a read-only side question
+
+```text
+/btw:ask what does the token refresh path do without changing anything?
+```
+
 ### Example: send the result back
 
 ```text