dostuff 0.2.8__tar.gz → 0.2.9__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. {dostuff-0.2.8 → dostuff-0.2.9}/PKG-INFO +49 -1
  2. {dostuff-0.2.8 → dostuff-0.2.9}/README.md +48 -0
  3. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/loop.py +15 -25
  4. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/cli_tui.py +279 -3
  5. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/constants.py +2 -0
  6. dostuff-0.2.9/dostuff/helpers/agent/side_question.py +226 -0
  7. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff.egg-info/PKG-INFO +49 -1
  8. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff.egg-info/SOURCES.txt +3 -0
  9. {dostuff-0.2.8 → dostuff-0.2.9}/pyproject.toml +1 -1
  10. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_loop.py +245 -0
  11. dostuff-0.2.9/tests/test_side_question.py +341 -0
  12. dostuff-0.2.9/tests/test_side_question_litellm.py +41 -0
  13. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_subagents_types.py +2 -1
  14. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_tui.py +967 -0
  15. {dostuff-0.2.8 → dostuff-0.2.9}/LICENSE +0 -0
  16. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/__init__.py +0 -0
  17. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/__main__.py +0 -0
  18. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/call_agent.py +0 -0
  19. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/instructions.py +0 -0
  20. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/permissions.py +0 -0
  21. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/run_tool.py +0 -0
  22. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/subagents/__init__.py +0 -0
  23. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/subagents/adapter.py +0 -0
  24. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/subagents/definitions.py +0 -0
  25. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/subagents/fork.py +0 -0
  26. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/subagents/prompt.py +0 -0
  27. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/subagents/registry.py +0 -0
  28. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/agent/subagents/run.py +0 -0
  29. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/cli.py +0 -0
  30. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/config.py +0 -0
  31. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/headless.py +0 -0
  32. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/append_step.py +0 -0
  33. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/consume_stream.py +0 -0
  34. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/context_usage.py +0 -0
  35. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/environment_context.py +0 -0
  36. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/file_mentions.py +0 -0
  37. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  38. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/load_identity.py +0 -0
  39. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  40. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  41. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/loop_emit.py +0 -0
  42. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/manage_context.py +0 -0
  43. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/model_cost.py +0 -0
  44. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/notices.py +0 -0
  45. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/pastes.py +0 -0
  46. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/quick_memory.py +0 -0
  47. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  48. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/agent/tool_output.py +0 -0
  49. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/hooks/__init__.py +0 -0
  50. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/hooks/dispatch.py +0 -0
  51. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/hooks/events.py +0 -0
  52. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/hooks/load_hooks.py +0 -0
  53. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/hooks/run_hook.py +0 -0
  54. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/hooks/trust.py +0 -0
  55. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  56. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  57. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/mcp/server_config.py +0 -0
  58. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/mcp/token_store.py +0 -0
  59. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/memory/export_session.py +0 -0
  60. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  61. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/memory/shell_step.py +0 -0
  62. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/models/add_model_entry.py +0 -0
  63. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/models/list_models.py +0 -0
  64. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/models/opencode.py +0 -0
  65. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/skills/custom_commands.py +0 -0
  66. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/skills/discover_skills.py +0 -0
  67. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/skills/skill_command.py +0 -0
  68. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/tools/diff.py +0 -0
  69. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  70. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/tools/project_root.py +0 -0
  71. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  72. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/ui/__init__.py +0 -0
  73. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/ui/ask_answers.py +0 -0
  74. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/ui/doctor.py +0 -0
  75. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/ui/emit.py +0 -0
  76. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/ui/prompt_history.py +0 -0
  77. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/ui/terminal_signals.py +0 -0
  78. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/helpers/ui/tools_listing.py +0 -0
  79. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/checkpoints.py +0 -0
  80. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/exceptions.py +0 -0
  81. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/mcp/mcp_client.py +0 -0
  82. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  83. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  84. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/memory/chroma.py +0 -0
  85. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  86. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  87. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/memory/session_store.py +0 -0
  88. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/memory/stores.py +0 -0
  89. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/memory/types.py +0 -0
  90. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/model.py +0 -0
  91. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/tracing.py +0 -0
  92. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/lib/worktree.py +0 -0
  93. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/memory/__init__.py +0 -0
  94. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/setup_wizard.py +0 -0
  95. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/skills.py +0 -0
  96. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/templates/config.example.yaml +0 -0
  97. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/templates/env.example +0 -0
  98. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/__init__.py +0 -0
  99. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/agent.py +0 -0
  100. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/ask_user.py +0 -0
  101. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/bash/bash_command.py +0 -0
  102. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/bash/bash_output.py +0 -0
  103. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/bash/jobs.py +0 -0
  104. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/bash/kill_shell.py +0 -0
  105. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/create_agent_type.py +0 -0
  106. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/definitions.py +0 -0
  107. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/files/delete_file.py +0 -0
  108. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/files/edit_file.py +0 -0
  109. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/files/list_files.py +0 -0
  110. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/files/read_file.py +0 -0
  111. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/files/write_file.py +0 -0
  112. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/get_current_datetime.py +0 -0
  113. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  114. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  115. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  116. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/memory/save_episode.py +0 -0
  117. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/memory/save_memory.py +0 -0
  118. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/names.py +0 -0
  119. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/search/glob.py +0 -0
  120. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/search/grep.py +0 -0
  121. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/search/walk.py +0 -0
  122. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/send_message.py +0 -0
  123. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/settings.py +0 -0
  124. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/stop_agent.py +0 -0
  125. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/todo_write.py +0 -0
  126. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/web_fetch.py +0 -0
  127. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff/tools/web_search.py +0 -0
  128. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff.egg-info/dependency_links.txt +0 -0
  129. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff.egg-info/entry_points.txt +0 -0
  130. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff.egg-info/requires.txt +0 -0
  131. {dostuff-0.2.8 → dostuff-0.2.9}/dostuff.egg-info/top_level.txt +0 -0
  132. {dostuff-0.2.8 → dostuff-0.2.9}/setup.cfg +0 -0
  133. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_ask_user.py +0 -0
  134. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_bash_command.py +0 -0
  135. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_checkpoints_todos_caching.py +0 -0
  136. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_cli_commands.py +0 -0
  137. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_config_memory_mcp.py +0 -0
  138. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_create_agent_type.py +0 -0
  139. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_file_mentions.py +0 -0
  140. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_file_tools.py +0 -0
  141. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_hooks.py +0 -0
  142. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_jobs.py +0 -0
  143. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_mcp_e2e.py +0 -0
  144. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_mcp_oauth.py +0 -0
  145. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_opencode.py +0 -0
  146. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_optional_memory_and_instructions.py +0 -0
  147. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_pastes.py +0 -0
  148. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_permissions.py +0 -0
  149. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_roadmap_021.py +0 -0
  150. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_session_store.py +0 -0
  151. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_settings_tools.py +0 -0
  152. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_setup_wizard.py +0 -0
  153. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_skill_command.py +0 -0
  154. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_skills_discovery.py +0 -0
  155. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_slash_suggestion.py +0 -0
  156. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_subagent.py +0 -0
  157. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_subagents_background.py +0 -0
  158. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_subagents_fork.py +0 -0
  159. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_subagents_run.py +0 -0
  160. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_subagents_store.py +0 -0
  161. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_terminal_signals.py +0 -0
  162. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_tool_schemas.py +0 -0
  163. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_tools_listing.py +0 -0
  164. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_web_fetch.py +0 -0
  165. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_web_search.py +0 -0
  166. {dostuff-0.2.8 → dostuff-0.2.9}/tests/test_worktree.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dostuff
3
- Version: 0.2.8
3
+ Version: 0.2.9
4
4
  Summary: DoStuff - a terminal coding agent for any LLM: TUI and headless mode, permissions, MCP, skills, web tools, sessions and git worktrees
5
5
  Author-email: Varun Kumawat <varunkumawatleap2@gmail.com>
6
6
  License-Expression: MIT
@@ -84,6 +84,7 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
84
84
  - **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
85
85
  - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
86
86
  - **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
87
+ - **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
87
88
  - **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
88
89
  - **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
89
90
  - **Background jobs** — `bash_command(run_in_background=true)` starts dev servers, watchers and long test runs as jobs the agent reads with `bash_output` (`wait_for` a ready line) and stops with `kill_shell`; it hears when one ends. `Ctrl+B` moves a running command to the background, `/jobs` lists them, and none outlives the session. See [Background jobs](#background-jobs)
@@ -242,6 +243,7 @@ In the TUI:
242
243
  | `/worktree [name]` / `/worktree exit` | Move the session into a new git worktree on branch `dostuff/<name>` / leave it (removed if unchanged, otherwise keep or remove) |
243
244
  | `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
244
245
  | `/copy` | Copy the model's last answer to the clipboard |
246
+ | `/btw <question>` | Ask a side question about the conversation, even while a turn runs: answered in a panel above the input, without tools, never added to the history. See [Side questions](#side-questions-btw) |
245
247
  | `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
246
248
  | `/model [<provider/model>] [--active]` | Pick a model: your saved ones (`models:` in config.yaml) first, then "More <provider> models…" for each provider's list (type to filter; Enter on no match uses what you typed). A model that isn't saved yet is added to `~/.dostuff/config.yaml`. A plain `/model` switch lasts only for this session; add `--active` (e.g. `/model --active`, or `/model anthropic/claude-sonnet-5-5 --active`) to make it the default that new sessions start with |
247
249
  | `/config [mcp] [project]` | Edit a settings file right in the TUI: pick `config.yaml` or the MCP servers, user (`~/.dostuff`) or project (`./.dostuff`), or name one (`/config mcp project`). `Ctrl+S` checks the file, saves it and applies it without a restart (an invalid file stays open with the error); `Esc` closes, twice if there are unsaved changes. A new file starts with every option commented out. `.env` files aren't offered |
@@ -464,6 +466,51 @@ is still listed but answers "No user is available in this run", and the model st
464
466
 
465
467
  ---
466
468
 
469
+ ## Side questions (`/btw`)
470
+
471
+ A turn can run for minutes, and halfway through you may want to know something *about* it: which file it just
472
+ edited, whether a test already exists, what you asked for. Typed into the input, that question would wait in the
473
+ queue until the turn ends; `Esc` would stop the work. `/btw <question>` answers it now, while the turn keeps running:
474
+
475
+ ```
476
+ ╭──────────────────────────────────────────────────────────────────────────────────╮
477
+ │ /btw — where does the retry happen? │
478
+ │ The retry loop is in call_agent, wrapped by classify_model_error; loop.py │
479
+ │ decides whether to compact or back off from its return value. │
480
+ │ Esc/Enter/Space close · f fork out · c copy · ↑18.4k (18.2k cached) ↓61 · │
481
+ │ $0.0021 │
482
+ ╰──────────────────────────────────────────────────────────────────────────────────╯
483
+ ```
484
+
485
+ The panel sits above the input and the conversation stays visible underneath. It shows `Asking…` until the answer
486
+ arrives; `↑`/`↓` scroll a long one.
487
+
488
+ - **No tools run.** The model sees the conversation up to the last completed step and answers from that alone, in
489
+ one response. If it asks for a tool or writes out a tool call instead, nothing runs and a note under the answer
490
+ says so.
491
+ - **Nothing is written.** The question and the answer never enter the transcript, the session history, `/export` or
492
+ the next compaction, and their cost is not added to the session: it is shown in the panel's footer instead, with
493
+ the prompt-cache hits: the side call sends the turn's own system prompt and tools, so a provider with prompt
494
+ caching can serve most of it from the cache. Hooks don't fire for it either.
495
+ - **No follow-up turns.** One question, one answer. Later `/btw`s in the same session see the earlier side questions
496
+ and answers (the last 20); `/clear`, `/resume` and `/fork` start a fresh side thread.
497
+
498
+ Keys while the panel has focus: `Esc`, `Enter` or `Space` close it (Esc closes the panel, it does **not** cancel the
499
+ turn), `c` copies the answer, and `f` forks it out. One side question at a time; a second `/btw` while one is still
500
+ asking is refused. If an approval prompt or an `ask_user` question opens while the panel is up, the prompt takes the
501
+ focus and the first `Esc`.
502
+
503
+ **Fork out (`f`).** When the conversation isn't enough to answer, `f` starts a background `fork` agent with the
504
+ question, the answer to check and the same view of the conversation the side question had. It runs with the main
505
+ agent's tools in its own slot (`/agents` shows it), costs what any background agent costs, and its report comes back
506
+ into the conversation like every background agent's. `Esc` on the main turn doesn't stop it. It is carried to the new
507
+ session by `/clear` and `/resume`; `/fork` leaves it with the original session and says so.
508
+
509
+ With no turn running, `/btw` works from the stored conversation and the last turn's system prompt. `dostuff -p` has
510
+ no `/btw` (only skills and custom commands run there), so `/btw` in a `-p` prompt is ordinary text for the model.
511
+
512
+ ---
513
+
467
514
  ## Subagents
468
515
 
469
516
  A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
@@ -756,6 +803,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
756
803
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
757
804
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
758
805
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
806
+ | `/btw` | `/btw` | not a tool: a side question fires no hook (no `UserPromptSubmit`, `PreToolUse` or `Stop`) |
759
807
 
760
808
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
761
809
  events.
@@ -36,6 +36,7 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
36
36
  - **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
37
37
  - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
38
38
  - **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
39
+ - **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
39
40
  - **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
40
41
  - **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
41
42
  - **Background jobs** — `bash_command(run_in_background=true)` starts dev servers, watchers and long test runs as jobs the agent reads with `bash_output` (`wait_for` a ready line) and stops with `kill_shell`; it hears when one ends. `Ctrl+B` moves a running command to the background, `/jobs` lists them, and none outlives the session. See [Background jobs](#background-jobs)
@@ -194,6 +195,7 @@ In the TUI:
194
195
  | `/worktree [name]` / `/worktree exit` | Move the session into a new git worktree on branch `dostuff/<name>` / leave it (removed if unchanged, otherwise keep or remove) |
195
196
  | `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
196
197
  | `/copy` | Copy the model's last answer to the clipboard |
198
+ | `/btw <question>` | Ask a side question about the conversation, even while a turn runs: answered in a panel above the input, without tools, never added to the history. See [Side questions](#side-questions-btw) |
197
199
  | `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
198
200
  | `/model [<provider/model>] [--active]` | Pick a model: your saved ones (`models:` in config.yaml) first, then "More <provider> models…" for each provider's list (type to filter; Enter on no match uses what you typed). A model that isn't saved yet is added to `~/.dostuff/config.yaml`. A plain `/model` switch lasts only for this session; add `--active` (e.g. `/model --active`, or `/model anthropic/claude-sonnet-5-5 --active`) to make it the default that new sessions start with |
199
201
  | `/config [mcp] [project]` | Edit a settings file right in the TUI: pick `config.yaml` or the MCP servers, user (`~/.dostuff`) or project (`./.dostuff`), or name one (`/config mcp project`). `Ctrl+S` checks the file, saves it and applies it without a restart (an invalid file stays open with the error); `Esc` closes, twice if there are unsaved changes. A new file starts with every option commented out. `.env` files aren't offered |
@@ -416,6 +418,51 @@ is still listed but answers "No user is available in this run", and the model st
416
418
 
417
419
  ---
418
420
 
421
+ ## Side questions (`/btw`)
422
+
423
+ A turn can run for minutes, and halfway through you may want to know something *about* it: which file it just
424
+ edited, whether a test already exists, what you asked for. Typed into the input, that question would wait in the
425
+ queue until the turn ends; `Esc` would stop the work. `/btw <question>` answers it now, while the turn keeps running:
426
+
427
+ ```
428
+ ╭──────────────────────────────────────────────────────────────────────────────────╮
429
+ │ /btw — where does the retry happen? │
430
+ │ The retry loop is in call_agent, wrapped by classify_model_error; loop.py │
431
+ │ decides whether to compact or back off from its return value. │
432
+ │ Esc/Enter/Space close · f fork out · c copy · ↑18.4k (18.2k cached) ↓61 · │
433
+ │ $0.0021 │
434
+ ╰──────────────────────────────────────────────────────────────────────────────────╯
435
+ ```
436
+
437
+ The panel sits above the input and the conversation stays visible underneath. It shows `Asking…` until the answer
438
+ arrives; `↑`/`↓` scroll a long one.
439
+
440
+ - **No tools run.** The model sees the conversation up to the last completed step and answers from that alone, in
441
+ one response. If it asks for a tool or writes out a tool call instead, nothing runs and a note under the answer
442
+ says so.
443
+ - **Nothing is written.** The question and the answer never enter the transcript, the session history, `/export` or
444
+ the next compaction, and their cost is not added to the session: it is shown in the panel's footer instead, with
445
+ the prompt-cache hits: the side call sends the turn's own system prompt and tools, so a provider with prompt
446
+ caching can serve most of it from the cache. Hooks don't fire for it either.
447
+ - **No follow-up turns.** One question, one answer. Later `/btw`s in the same session see the earlier side questions
448
+ and answers (the last 20); `/clear`, `/resume` and `/fork` start a fresh side thread.
449
+
450
+ Keys while the panel has focus: `Esc`, `Enter` or `Space` close it (Esc closes the panel, it does **not** cancel the
451
+ turn), `c` copies the answer, and `f` forks it out. One side question at a time; a second `/btw` while one is still
452
+ asking is refused. If an approval prompt or an `ask_user` question opens while the panel is up, the prompt takes the
453
+ focus and the first `Esc`.
454
+
455
+ **Fork out (`f`).** When the conversation isn't enough to answer, `f` starts a background `fork` agent with the
456
+ question, the answer to check and the same view of the conversation the side question had. It runs with the main
457
+ agent's tools in its own slot (`/agents` shows it), costs what any background agent costs, and its report comes back
458
+ into the conversation like every background agent's. `Esc` on the main turn doesn't stop it. It is carried to the new
459
+ session by `/clear` and `/resume`; `/fork` leaves it with the original session and says so.
460
+
461
+ With no turn running, `/btw` works from the stored conversation and the last turn's system prompt. `dostuff -p` has
462
+ no `/btw` (only skills and custom commands run there), so `/btw` in a `-p` prompt is ordinary text for the model.
463
+
464
+ ---
465
+
419
466
  ## Subagents
420
467
 
421
468
  A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
@@ -708,6 +755,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
708
755
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
709
756
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
710
757
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
758
+ | `/btw` | `/btw` | not a tool: a side question fires no hook (no `UserPromptSubmit`, `PreToolUse` or `Stop`) |
711
759
 
712
760
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
713
761
  events.
@@ -1,7 +1,6 @@
1
1
  from dostuff.helpers.agent.loop_check_cancelled import CANCELLED_TURN, is_cancelled, loop_check_cancelled
2
2
  from dostuff.helpers.agent.get_model_token_limit import get_model_token_limit
3
- from dostuff.helpers.agent.model_cost import call_cost
4
- from dostuff.lib.model import current_session_id, get_litellm_model
3
+ from dostuff.lib.model import current_session_id
5
4
  from dostuff.helpers.agent.loop_emit import loop_emit
6
5
  from dostuff.lib.mcp.mcp_client import MCPClient
7
6
  from dostuff.lib.tracing import content_attr, tracer
@@ -14,20 +13,21 @@ import asyncio
14
13
  import inspect
15
14
  import random
16
15
  from dataclasses import dataclass
17
- from dostuff.agent.permissions import PLAN_MODE_INSTRUCTION, SessionPermissions
16
+ from dostuff.agent.permissions import SessionPermissions
18
17
  from dostuff.agent.run_tool import (
19
18
  CANCELLED_RESULT, authorize_batch, authorize_tool, dispatch_tool, post_tool_use, pre_tool_use,
20
19
  )
21
20
  from dostuff.helpers.hooks import HookOutcome, run_hooks
22
21
  from dostuff.helpers.hooks.dispatch import report_outcome
23
- from dostuff.helpers.hooks.events import (
24
- STOP_LIMIT_MESSAGE, STOP_NOTE, session_context_suffix, session_start, stop_event_for,
25
- )
22
+ from dostuff.helpers.hooks.events import STOP_LIMIT_MESSAGE, STOP_NOTE, session_start, stop_event_for
26
23
  from dostuff.helpers.hooks.run_hook import payload_for
27
24
  from dostuff.config import AUTO_COMPACT_THRESHOLD, get_config
28
25
  from dostuff.tools.definitions import TOOL_MAP, default_tool_names
29
26
  from dostuff.agent.subagents.fork import ForkContext
30
27
  from dostuff.helpers.agent.notices import format_notices, get_notice_queue
28
+ from dostuff.helpers.agent.side_question import (
29
+ compose_system_instruction, plan_mode_on, publish_snapshot, published_snapshot, usage_dict as build_usage_dict,
30
+ )
31
31
  from dostuff.tools.bash.jobs import Job, JobEvent, get_registry
32
32
  from typing import Any, Iterator, Literal
33
33
  import contextlib
@@ -234,6 +234,7 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
234
234
  except Exception as e:
235
235
  await loop_emit("error", f"Could not save compaction: {e}", adapter=adapter)
236
236
  await loop_emit("system", f"{reason} Context compacted. Notes: {compaction_notes}", adapter=adapter)
237
+ publish_snapshot(session_id, fork_context()) # /btw must not read the history that just overflowed
237
238
  if session_hook_context is not None and turn_type == "interactive_loop": # a fork carries the main's
238
239
  # Earlier SessionStart context may be stale now; refresh it under its own key (REQ-2.4)
239
240
  await session_start("compact", session_hook_context, session_id=session_id, turn_id=turn_id,
@@ -265,7 +266,8 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
265
266
  if context_token_threshold is not None and last_input_tokens > context_token_threshold:
266
267
  await compact("Token threshold exceeded.", keep_recent_token_budget)
267
268
 
268
- with tracer.start_as_current_span("turn") as turn_span, _job_events(owner, adapter):
269
+ with tracer.start_as_current_span("turn") as turn_span, _job_events(owner, adapter), \
270
+ published_snapshot(session_id, enabled=turn_type == "interactive_loop"):
269
271
  turn_span.set_attribute("session_id", session_id)
270
272
  turn_span.set_attribute("turn_type", turn_type)
271
273
  turn_span.set_attribute("turn_id", turn_id)
@@ -288,6 +290,8 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
288
290
  await append_note(format_notices(notices, max_tool_output_chars))
289
291
  while inbox: # send_message to this running subagent, oldest first (D10)
290
292
  await append_note(inbox.pop(0))
293
+ # What a /btw side question reads while this turn runs (btw spec D3); main agent only
294
+ publish_snapshot(session_id, fork_context())
291
295
 
292
296
  # Model call with classified retries and exponential backoff
293
297
  interaction = None
@@ -299,13 +303,11 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
299
303
  progress = StreamProgress()
300
304
  try:
301
305
  # Read per call: the mode can change mid-turn (Shift+Tab)
302
- plan_mode = ((permissions.mode if permissions else None) or getattr(config, "permission_mode", "ask")) == "plan"
306
+ plan_mode = plan_mode_on(permissions, config)
303
307
  interaction, model_span = await call_agent(
304
308
  steps_history=working_history,
305
- system_instruction=dynamic_system_instruction
306
- + (f"\n\n{PLAN_MODE_INSTRUCTION}" if plan_mode else "")
307
- + (f"\n\n[Summary of earlier conversation]: {compaction_notes}" if compaction_notes else "")
308
- + session_context_suffix(session_hook_context),
309
+ system_instruction=compose_system_instruction(
310
+ dynamic_system_instruction, plan_mode, compaction_notes, session_hook_context),
309
311
  tool_names=tool_names,
310
312
  stream=stream,
311
313
  )
@@ -342,24 +344,12 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
342
344
  if interaction is None:
343
345
  return CANCELLED_TURN
344
346
 
345
- usage_dict = None
346
- usage = getattr(interaction, "usage", None)
347
+ usage_dict = build_usage_dict(interaction) # None when the response has no usage
347
348
  choices = getattr(interaction, "choices", None)
348
349
  message = choices[0].message if choices else None
349
350
  tool_calls = getattr(message, "tool_calls", None) if message else None
350
351
  content = getattr(message, "content", None) if message else None
351
352
 
352
- if usage:
353
- usage_dict = {
354
- "prompt_tokens": getattr(usage, "prompt_tokens", 0) or 0,
355
- "completion_tokens": getattr(usage, "completion_tokens", 0) or 0,
356
- "total_tokens": getattr(usage, "total_tokens", 0) or 0,
357
- # Prompt tokens read from the provider's prompt cache (0 if none / unsupported)
358
- "cached_tokens": getattr(getattr(usage, "prompt_tokens_details", None), "cached_tokens", 0) or 0,
359
- }
360
- # USD from litellm's price table; None if unknown (the TUI then hides the cost)
361
- usage_dict["cost"] = call_cost(get_litellm_model(), usage_dict)
362
-
363
353
  # close model_span exactly once, here, before any continue/return below
364
354
  if model_span is not None and model_span.is_recording():
365
355
  if usage_dict:
@@ -26,6 +26,7 @@ from textual.containers import Horizontal, Vertical, VerticalScroll
26
26
  from textual.actions import SkipAction
27
27
  from textual.binding import Binding
28
28
  from textual.worker import Worker, WorkerState
29
+ from rich.console import Group
29
30
  from rich.style import Style
30
31
  from rich.text import Text
31
32
  from rich.markdown import Markdown as RichMarkdown
@@ -55,6 +56,11 @@ from dostuff.helpers.agent.file_mentions import (PARTIAL_MENTION_RE, attached_pa
55
56
  from dostuff.helpers.agent.model_cost import format_cost
56
57
  from dostuff.helpers.agent.notices import WAKE_LIMIT, agent_notice_line, fmt_agent_runtime, format_notices, get_notice_queue, parse_notices
57
58
  from dostuff.helpers.agent.pastes import PasteStore, sweep_old_pastes
59
+ from dostuff.helpers.agent.side_question import (
60
+ BTW_FORK_DESCRIPTION, BTW_FORK_PROMPT, add_exchange, answer_side_question, discard_snapshot, kept_prompt,
61
+ plan_mode_on, snapshot as live_side_snapshot,
62
+ )
63
+ from dostuff.agent.subagents.fork import ForkContext
58
64
  from dostuff.helpers.agent.quick_memory import append_memory, memory_file, quick_memory_text
59
65
  from dostuff.helpers.agent.context_usage import context_parts, count_tokens, render_context
60
66
  from dostuff.helpers.ui.doctor import doctor_checks, hooks_listing
@@ -958,6 +964,105 @@ class AskUserPanel(Static, can_focus=True):
958
964
  event.prevent_default()
959
965
 
960
966
 
967
+ class BtwPanel(Vertical, can_focus=True):
968
+ """The `/btw` side answer (btw spec D6): a title row, a scrollable body and a footer of keys.
969
+
970
+ Read-only, and outside `#msg-container`, so nothing in it can reach the transcript or `/export`. One instance is
971
+ composed hidden and reused, never mounted per question (the `DuplicateIds` lesson of `#picker` and
972
+ `#ask-panel`). It sits above the input and leaves the conversation visible: the turn keeps running underneath.
973
+
974
+ The panel owns its keys while focused (Enter/Space close, `f` fork out, `c` copy, ↑/↓ scroll); Esc is the app's
975
+ priority binding, which closes the panel unless an approval or a question is waiting (`action_cancel`).
976
+ """
977
+
978
+ BINDINGS = [
979
+ Binding("enter", "close", "Close", show=False),
980
+ Binding("space", "close", "Close", show=False),
981
+ Binding("f", "fork_out", "Fork out", show=False),
982
+ Binding("c", "copy", "Copy", show=False),
983
+ Binding("up", "scroll_body(-1)", show=False),
984
+ Binding("down", "scroll_body(1)", show=False),
985
+ Binding("pageup", "scroll_body(-10)", show=False),
986
+ Binding("pagedown", "scroll_body(10)", show=False),
987
+ ]
988
+
989
+ class Close(Message):
990
+ """Enter or Space."""
991
+
992
+ class ForkOut(Message):
993
+ """`f` on an answer: hand the question to a background fork (D8)."""
994
+
995
+ class Copy(Message):
996
+ """`c` on an answer."""
997
+
998
+ def __init__(self, **kwargs: Any) -> None:
999
+ super().__init__(**kwargs)
1000
+ self.question = ""
1001
+ self.snapshot: Any = None # the ForkContext the side call used; a fork-out gets this same object (D8)
1002
+ self.answer: Any = None # the SideAnswer once it arrived
1003
+ self.error = ""
1004
+ self.body_text = "" # what the body shows, as plain text
1005
+
1006
+ def compose(self) -> ComposeResult:
1007
+ yield Static(id="btw-title", markup=False)
1008
+ with VerticalScroll(id="btw-scroll", can_focus=False):
1009
+ yield Static(id="btw-body", markup=False)
1010
+ yield Static(id="btw-footer", markup=False)
1011
+
1012
+ def configure(self, question: str) -> None:
1013
+ """A new side question: forget the last answer, show `Asking…`."""
1014
+ self.question, self.snapshot, self.answer, self.error = question, None, None, ""
1015
+ self.body_text = "Asking…"
1016
+ self.query_one("#btw-title", Static).update(Text(f"/btw — {_one_line(question, 500)}"))
1017
+ self.query_one("#btw-body", Static).update(Text("Asking…", style="#8a8a8a"))
1018
+ self.query_one("#btw-footer", Static).update(BTW_ASKING_FOOTER)
1019
+ self.query_one("#btw-scroll", VerticalScroll).scroll_home(animate=False)
1020
+
1021
+ def show_answer(self, answer: Any, usage_text: str) -> None:
1022
+ self.answer = answer
1023
+ self.body_text = answer.text
1024
+ self.query_one("#btw-body", Static).update(RichMarkdown(answer.text))
1025
+ self.query_one("#btw-footer", Static).update(
1026
+ BTW_ANSWER_FOOTER + (f" · {usage_text}" if usage_text else ""))
1027
+
1028
+ def show_fork_error(self, message: str) -> None:
1029
+ """A fork-out that could not start: said under the answer, which stays (REQ-4.1)."""
1030
+ self.error = message
1031
+ self.body_text = f"{self.answer.text}\n\n{message}" if self.answer is not None else message
1032
+ self.query_one("#btw-body", Static).update(
1033
+ Group(RichMarkdown(self.answer.text), Text(""), Text(message, style="#e06c75"))
1034
+ if self.answer is not None else Text(message, style="#e06c75"))
1035
+
1036
+ def show_error(self, message: str) -> None:
1037
+ """A failed call or fork-out: said here, never as a turn error in the transcript (D6)."""
1038
+ self.error = self.body_text = message
1039
+ self.query_one("#btw-body", Static).update(Text(message, style="#e06c75"))
1040
+ self.query_one("#btw-footer", Static).update(BTW_ANSWER_FOOTER if self.answer is not None else BTW_CLOSE_FOOTER)
1041
+
1042
+ def action_close(self) -> None:
1043
+ self.post_message(self.Close())
1044
+
1045
+ def action_fork_out(self) -> None:
1046
+ if self.answer is not None: # inert while asking: the fork is given the answer to check (§7.3)
1047
+ self.post_message(self.ForkOut())
1048
+
1049
+ def action_copy(self) -> None:
1050
+ if self.answer is not None:
1051
+ self.post_message(self.Copy())
1052
+
1053
+ def action_scroll_body(self, rows: int) -> None:
1054
+ self.query_one("#btw-scroll", VerticalScroll).scroll_relative(y=rows, animate=False)
1055
+
1056
+
1057
+ BTW_ASKING_FOOTER = "Esc close"
1058
+ BTW_CLOSE_FOOTER = "Esc/Enter/Space close"
1059
+ BTW_ANSWER_FOOTER = "Esc/Enter/Space close · f fork out · c copy"
1060
+ BTW_BUSY = "a side question is already running"
1061
+ BTW_USAGE = "Usage: /btw <question>"
1062
+ BTW_HANDED_OFF = "handed to a background agent · /agents to watch it"
1063
+ BTW_FORK_STRANDED = "⚙ a side-question agent is still running; its answer stays with '{old}'"
1064
+
1065
+
961
1066
  # Shift+Enter needs a terminal that reports it (kitty keyboard protocol, e.g. kitty, WezTerm,
962
1067
  # Ghostty); elsewhere it arrives as plain Enter, so the others stay as fallbacks.
963
1068
  NEWLINE_KEYS = {"shift+enter", "ctrl+enter", "alt+enter", "ctrl+j"}
@@ -1623,6 +1728,16 @@ class DostuffTUI(App):
1623
1728
  #agent-view-scroll { height: 1fr; border: round #4a4a4a; }
1624
1729
  #agent-view-msgs { height: auto; }
1625
1730
  #agent-view-status { height: auto; padding: 0 1; color: #8a8a8a; }
1731
+ /* /btw: #agent-view's look (title colour, round border), but auto height so the conversation stays visible */
1732
+ #btw-panel {
1733
+ height: auto; max-height: 50vh; margin-top: 1; padding: 0 1; background: transparent;
1734
+ border: round #4a4a4a;
1735
+ }
1736
+ #btw-panel:focus { border: round #7a7a7a; }
1737
+ #btw-title { height: 1; color: #8ab4f8; text-style: bold; text-wrap: nowrap; text-overflow: ellipsis; }
1738
+ #btw-scroll { height: auto; max-height: 40vh; scrollbar-size-vertical: 1; }
1739
+ #btw-body { height: auto; }
1740
+ #btw-footer { height: auto; color: #8a8a8a; }
1626
1741
  #settings-panel { height: 1fr; }
1627
1742
  #settings-title { height: auto; padding: 0 1; color: #8ab4f8; }
1628
1743
  #settings-editor { height: 1fr; background: transparent; border: round #8ab4f8; }
@@ -1726,6 +1841,10 @@ class DostuffTUI(App):
1726
1841
  self._last_escape = 0.0 # time.monotonic() of an Esc with nothing to cancel (Esc Esc edits the last prompt)
1727
1842
  # (session id, steps_history index) → the prompt as typed, before @mentions / skills expanded it
1728
1843
  self._sent_prompts: dict[tuple[str, int], str] = {}
1844
+ # /btw (btw spec D5): this session's side thread as sent (question step, answer), and the call in flight
1845
+ self._side_exchanges: list[tuple[str, str]] = []
1846
+ self._btw_worker: Worker | None = None
1847
+ self._btw_forking = False # an `f` is starting its fork; a second press does nothing (D8)
1729
1848
 
1730
1849
  # ── Compose UI ─────────────────────────────────────────────────────────────
1731
1850
 
@@ -1737,6 +1856,9 @@ class DostuffTUI(App):
1737
1856
  yield JumpToBottom("↓ Jump to bottom", id="jump-bottom")
1738
1857
  yield CommandMenu(id="command-menu")
1739
1858
  yield QueueBar(id="queue-bar")
1859
+ btw = BtwPanel(id="btw-panel")
1860
+ btw.display = False # a /btw side answer, above the input (btw spec D6)
1861
+ yield btw
1740
1862
  picker = PermissionPrompt("", [], id="picker")
1741
1863
  picker.display = False # shown in place of the input by _show_picker
1742
1864
  yield picker
@@ -1766,15 +1888,17 @@ class DostuffTUI(App):
1766
1888
 
1767
1889
  def _keep_input_focus(self, focused: Widget | None) -> None:
1768
1890
  """Focus always goes back to the input (or the selector shown in its place)."""
1769
- if not isinstance(focused, (EnterSubmits, PermissionPrompt, AskUserPanel, SettingsEditor)):
1891
+ if not isinstance(focused, (EnterSubmits, PermissionPrompt, AskUserPanel, BtwPanel, SettingsEditor)):
1770
1892
  # call_later, not call_after_refresh: waiting on a repaint is slow on Windows
1771
1893
  self.call_later(self._refocus_input)
1772
1894
 
1773
1895
  def _refocus_input(self) -> None:
1774
- if isinstance(self.screen.focused, (EnterSubmits, PermissionPrompt, AskUserPanel, SettingsEditor)):
1896
+ if isinstance(self.screen.focused, (EnterSubmits, PermissionPrompt, AskUserPanel, BtwPanel, SettingsEditor)):
1775
1897
  return
1776
1898
  try:
1777
- for widget in (*self.query(PermissionPrompt), *self.query(AskUserPanel), *self.query(SettingsEditor)):
1899
+ # A prompt wins over the side answer: it is what the turn waits on (btw spec D6)
1900
+ for widget in (*self.query(PermissionPrompt), *self.query(AskUserPanel), *self.query(BtwPanel),
1901
+ *self.query(SettingsEditor)):
1778
1902
  if widget.display: # the #picker stays mounted while hidden
1779
1903
  self.screen.set_focus(widget)
1780
1904
  return
@@ -2027,6 +2151,7 @@ class DostuffTUI(App):
2027
2151
  A stored session gets this cwd and a fresh last_used; a new one gets its DB row with its
2028
2152
  first step, so launches that never send anything don't leave empty sessions behind.
2029
2153
  """
2154
+ self._clear_side_thread(self.session_id) # /resume and /fork; a no-op at startup (btw spec D10)
2030
2155
  self.session_id = session_id
2031
2156
  session_id_var.set(session_id)
2032
2157
  self.steps_history = await self.store.load(session_id)
@@ -2162,6 +2287,7 @@ class DostuffTUI(App):
2162
2287
  """
2163
2288
  old_session_id = self.session_id
2164
2289
  new_session_id = uuid.uuid4().hex[:16]
2290
+ self._clear_side_thread(old_session_id)
2165
2291
  self.session_id = new_session_id
2166
2292
  carried = self._carry_background(old_session_id)
2167
2293
  self.steps_history = []
@@ -2283,6 +2409,9 @@ class DostuffTUI(App):
2283
2409
  return
2284
2410
  old_session_id = self.session_id
2285
2411
  new_session_id = uuid.uuid4().hex[:16]
2412
+ # A fork-out is not carried into the fork: its run keeps the original as owner (btw spec D10, OUT-008)
2413
+ stranded = any(r.agent_type == "fork" and r.description == BTW_FORK_DESCRIPTION and r.ended is None
2414
+ for r in _agent_registry().runs(old_session_id))
2286
2415
  try:
2287
2416
  await self.store.fork_session(old_session_id, new_session_id, title or None)
2288
2417
  await self._load_session(new_session_id)
@@ -2296,6 +2425,8 @@ class DostuffTUI(App):
2296
2425
  f"/resume {old_session_id} goes back to the original.",
2297
2426
  msg_type="system",
2298
2427
  )
2428
+ if stranded:
2429
+ self._append(BTW_FORK_STRANDED.format(old=old_session_id), msg_type="system")
2299
2430
  if in_worktree:
2300
2431
  await self._enter_worktree(f"fork-{new_session_id[:8]}")
2301
2432
 
@@ -3232,6 +3363,9 @@ class DostuffTUI(App):
3232
3363
  self._remember_prompt(text)
3233
3364
  cmd = text.strip().lower()
3234
3365
 
3366
+ if cmd.split(maxsplit=1)[:1] == ["/btw"]: # works mid-turn: never queued (btw spec D1, CON-006)
3367
+ self._btw_command(self._pastes.inline(text.strip()[len("/btw"):]).strip())
3368
+ return
3235
3369
  if text.lstrip().startswith("!"):
3236
3370
  command = self._pastes.inline(text.lstrip()[1:]).strip()
3237
3371
  if not command:
@@ -3585,6 +3719,145 @@ class DostuffTUI(App):
3585
3719
  inp.display = True
3586
3720
  inp.focus()
3587
3721
 
3722
+ # ── /btw: a side question in an overlay (plan/2026-11-03-btw/spec.md) ──────────
3723
+
3724
+ def _btw_panel(self) -> BtwPanel:
3725
+ return self.query_one("#btw-panel", BtwPanel)
3726
+
3727
+ def _btw_open(self) -> bool:
3728
+ panels = self.query("#btw-panel")
3729
+ return bool(panels) and panels.first().display
3730
+
3731
+ def _btw_in_flight(self) -> bool:
3732
+ return self._btw_worker is not None and not self._btw_worker.is_finished
3733
+
3734
+ def _btw_command(self, question: str) -> None:
3735
+ if not question:
3736
+ self._append(BTW_USAGE, msg_type="error")
3737
+ return
3738
+ if self._btw_in_flight():
3739
+ self._flash_input_hint(BTW_BUSY)
3740
+ return
3741
+ self._show_btw(question)
3742
+ self._btw_worker = self._start_worker(self._ask_side_question(question), name="btw")
3743
+
3744
+ def _show_btw(self, question: str) -> None:
3745
+ """Shown at once with `Asking…`, filled when the answer arrives (D6). Takes focus for its keys."""
3746
+ panel = self._btw_panel()
3747
+ panel.configure(question)
3748
+ panel.display = True
3749
+ # Not while a prompt is up: the prompt keeps the focus and the first Esc (D6)
3750
+ if not self.adapter.has_pending_prompt():
3751
+ self.call_after_refresh(panel.focus)
3752
+
3753
+ def _close_btw(self) -> None:
3754
+ """Hide the side answer (an unanswered call is cancelled) and give the focus back."""
3755
+ if self._btw_in_flight() and self._btw_worker is not None:
3756
+ self._btw_worker.cancel()
3757
+ panels = self.query("#btw-panel")
3758
+ if not panels or not panels.first().display:
3759
+ return
3760
+ panel = panels.first()
3761
+ panel.display = False
3762
+ if self.screen.focused is panel:
3763
+ self.screen.set_focus(None)
3764
+ self._refocus_input()
3765
+
3766
+ async def _side_snapshot(self, question: str) -> ForkContext:
3767
+ """What a side question sees (D3): the running turn's snapshot; idle, the last turn's prompt parts with the
3768
+ stored history and notes (an idle /compact may have changed them, tasks.md open point 2); with neither, a
3769
+ system prompt built now, which is cache-cold once."""
3770
+ live = live_side_snapshot(self.session_id)
3771
+ if live is not None:
3772
+ return live
3773
+ meta = await self.store.get_session_meta(self.session_id) or {}
3774
+ history = await self.store.load_working_history(self.session_id)
3775
+ notes = meta.get("compaction_notes") or ""
3776
+ kept = kept_prompt(self.session_id)
3777
+ if kept is not None:
3778
+ return ForkContext(system_instruction=kept.system_instruction, compaction_notes=notes, history=history,
3779
+ tool_names=list(kept.tool_names), session_hook_context=kept.session_hook_context)
3780
+ from dostuff.tools.definitions import default_tool_names # pulls in the tools: after the first frame
3781
+ return ForkContext(system_instruction=await self._build_instructions(question), compaction_notes=notes,
3782
+ history=history, tool_names=default_tool_names(),
3783
+ session_hook_context=dict(self.session_hook_context))
3784
+
3785
+ async def _ask_side_question(self, question: str) -> None:
3786
+ """One no-tools call over the conversation; the answer goes to the panel and the side thread, nowhere
3787
+ else (CON-004). A failure is shown in the panel, never as a turn error."""
3788
+ panel = self._btw_panel()
3789
+ session_id = self.session_id
3790
+ try:
3791
+ await self._backend_ready.wait()
3792
+ if self._backend_error:
3793
+ raise RuntimeError(f"startup failed ({self._backend_error})")
3794
+ snap = await self._side_snapshot(question)
3795
+ panel.snapshot = snap
3796
+ answer = await answer_side_question(snap, list(self._side_exchanges), question,
3797
+ plan_mode_on(self.permissions, self.config))
3798
+ except asyncio.CancelledError:
3799
+ raise # the panel was closed while asking
3800
+ except Exception as e:
3801
+ panel.show_error(f"Side question failed: {e}")
3802
+ return
3803
+ if self.session_id != session_id:
3804
+ return # the session changed while asking: this answer belongs to the old thread
3805
+ add_exchange(self._side_exchanges, answer.sent_question, answer.answer)
3806
+ panel.show_answer(answer, self._format_side_usage(answer.usage))
3807
+
3808
+ def _format_side_usage(self, usage: dict | None) -> str:
3809
+ """`↑1.2k (1.1k cached) ↓340 · $0.0020`, shown on the panel and stored nowhere (D9)."""
3810
+ if not usage:
3811
+ return ""
3812
+ text = f"↑{self._fmt_tokens(usage.get('prompt_tokens', 0))}"
3813
+ if usage.get("cached_tokens"):
3814
+ text += f" ({self._fmt_tokens(usage['cached_tokens'])} cached)"
3815
+ text += f" ↓{self._fmt_tokens(usage.get('completion_tokens', 0))}"
3816
+ if usage.get("cost"):
3817
+ text += f" · {format_cost(usage['cost'])}"
3818
+ return text
3819
+
3820
+ def _clear_side_thread(self, old_session_id: str) -> None:
3821
+ """A session switch: the side thread and the panel belong to the old session, and so do its kept prompt
3822
+ parts (D10). A fork-out still running is a background run like any other (carried, or stranded by /fork)."""
3823
+ self._side_exchanges.clear()
3824
+ self._close_btw()
3825
+ discard_snapshot(old_session_id)
3826
+
3827
+ def on_btw_panel_close(self, event: BtwPanel.Close) -> None:
3828
+ self._close_btw()
3829
+
3830
+ def on_btw_panel_fork_out(self, event: BtwPanel.ForkOut) -> None:
3831
+ panel = self._btw_panel()
3832
+ if self._btw_forking or panel.answer is None:
3833
+ return
3834
+ self._btw_forking = True
3835
+ self._start_worker(self._btw_fork_out(panel.question, panel.answer.text, panel.snapshot), name="btw_fork")
3836
+
3837
+ async def _btw_fork_out(self, question: str, answer: str, snap: ForkContext | None) -> None:
3838
+ """`f`: the same question, the answer to check and the *same* snapshot to a background `fork` agent. Its
3839
+ report comes back by the ordinary notice path, as a user step in the transcript (D8)."""
3840
+ panel = self._btw_panel()
3841
+ try:
3842
+ await _agent_registry().start(
3843
+ owner=self.session_id, agent_type="fork", background=True, description=BTW_FORK_DESCRIPTION,
3844
+ prompt=BTW_FORK_PROMPT.format(question=question, answer=answer), fork=snap,
3845
+ mcp_client=self.mcp_client, adapter=self.adapter, permissions=self.permissions,
3846
+ )
3847
+ except Exception as e: # ValueError for a missing snapshot, anything else from start: the panel stays
3848
+ panel.show_fork_error(f"Could not hand it to a background agent: {e}")
3849
+ return
3850
+ finally:
3851
+ self._btw_forking = False
3852
+ self._close_btw()
3853
+ self._append(BTW_HANDED_OFF, msg_type="system")
3854
+
3855
+ def on_btw_panel_copy(self, event: BtwPanel.Copy) -> None:
3856
+ answer = self._btw_panel().answer
3857
+ if answer is not None:
3858
+ _copy_to_clipboard(self, answer.text)
3859
+ self._flash_input_hint(f"copied side answer ({len(answer.text)} characters)")
3860
+
3588
3861
  def _begin_turn(self, text: str) -> None:
3589
3862
  self._turn_in_progress = True
3590
3863
  self._wake_turns = 0
@@ -4059,6 +4332,9 @@ class DostuffTUI(App):
4059
4332
  if menu.display:
4060
4333
  menu.display = False
4061
4334
  return
4335
+ if self._btw_open() and not self.adapter.has_pending_prompt():
4336
+ self._close_btw() # closes the side answer; the turn keeps running (btw spec D6)
4337
+ return
4062
4338
  if self._picker_open():
4063
4339
  self._close_picker()
4064
4340
  return