dostuff 0.2.8__tar.gz → 0.2.10__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 (169) hide show
  1. {dostuff-0.2.8 → dostuff-0.2.10}/PKG-INFO +142 -2
  2. {dostuff-0.2.8 → dostuff-0.2.10}/README.md +141 -1
  3. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/loop.py +100 -31
  4. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/cli_tui.py +479 -22
  5. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/config.py +4 -0
  6. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/constants.py +4 -0
  7. dostuff-0.2.10/dostuff/helpers/agent/side_question.py +226 -0
  8. dostuff-0.2.10/dostuff/helpers/agent/steering.py +107 -0
  9. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/templates/config.example.yaml +3 -0
  10. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff.egg-info/PKG-INFO +142 -2
  11. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff.egg-info/SOURCES.txt +5 -0
  12. {dostuff-0.2.8 → dostuff-0.2.10}/pyproject.toml +1 -1
  13. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_config_memory_mcp.py +15 -0
  14. dostuff-0.2.10/tests/test_loop.py +1099 -0
  15. dostuff-0.2.10/tests/test_side_question.py +341 -0
  16. dostuff-0.2.10/tests/test_side_question_litellm.py +41 -0
  17. dostuff-0.2.10/tests/test_steering.py +121 -0
  18. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_subagents_types.py +2 -1
  19. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_tui.py +1814 -3
  20. dostuff-0.2.8/tests/test_loop.py +0 -443
  21. {dostuff-0.2.8 → dostuff-0.2.10}/LICENSE +0 -0
  22. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/__init__.py +0 -0
  23. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/__main__.py +0 -0
  24. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/call_agent.py +0 -0
  25. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/instructions.py +0 -0
  26. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/permissions.py +0 -0
  27. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/run_tool.py +0 -0
  28. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/subagents/__init__.py +0 -0
  29. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/subagents/adapter.py +0 -0
  30. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/subagents/definitions.py +0 -0
  31. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/subagents/fork.py +0 -0
  32. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/subagents/prompt.py +0 -0
  33. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/subagents/registry.py +0 -0
  34. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/agent/subagents/run.py +0 -0
  35. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/cli.py +0 -0
  36. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/headless.py +0 -0
  37. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/append_step.py +0 -0
  38. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/consume_stream.py +0 -0
  39. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/context_usage.py +0 -0
  40. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/environment_context.py +0 -0
  41. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/file_mentions.py +0 -0
  42. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  43. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/load_identity.py +0 -0
  44. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  45. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  46. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/loop_emit.py +0 -0
  47. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/manage_context.py +0 -0
  48. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/model_cost.py +0 -0
  49. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/notices.py +0 -0
  50. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/pastes.py +0 -0
  51. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/quick_memory.py +0 -0
  52. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  53. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/agent/tool_output.py +0 -0
  54. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/hooks/__init__.py +0 -0
  55. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/hooks/dispatch.py +0 -0
  56. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/hooks/events.py +0 -0
  57. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/hooks/load_hooks.py +0 -0
  58. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/hooks/run_hook.py +0 -0
  59. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/hooks/trust.py +0 -0
  60. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  61. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  62. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/mcp/server_config.py +0 -0
  63. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/mcp/token_store.py +0 -0
  64. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/memory/export_session.py +0 -0
  65. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  66. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/memory/shell_step.py +0 -0
  67. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/models/add_model_entry.py +0 -0
  68. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/models/list_models.py +0 -0
  69. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/models/opencode.py +0 -0
  70. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/skills/custom_commands.py +0 -0
  71. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/skills/discover_skills.py +0 -0
  72. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/skills/skill_command.py +0 -0
  73. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/tools/diff.py +0 -0
  74. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  75. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/tools/project_root.py +0 -0
  76. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  77. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/ui/__init__.py +0 -0
  78. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/ui/ask_answers.py +0 -0
  79. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/ui/doctor.py +0 -0
  80. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/ui/emit.py +0 -0
  81. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/ui/prompt_history.py +0 -0
  82. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/ui/terminal_signals.py +0 -0
  83. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/helpers/ui/tools_listing.py +0 -0
  84. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/checkpoints.py +0 -0
  85. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/exceptions.py +0 -0
  86. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/mcp/mcp_client.py +0 -0
  87. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  88. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  89. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/memory/chroma.py +0 -0
  90. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  91. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  92. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/memory/session_store.py +0 -0
  93. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/memory/stores.py +0 -0
  94. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/memory/types.py +0 -0
  95. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/model.py +0 -0
  96. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/tracing.py +0 -0
  97. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/lib/worktree.py +0 -0
  98. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/memory/__init__.py +0 -0
  99. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/setup_wizard.py +0 -0
  100. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/skills.py +0 -0
  101. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/templates/env.example +0 -0
  102. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/__init__.py +0 -0
  103. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/agent.py +0 -0
  104. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/ask_user.py +0 -0
  105. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/bash/bash_command.py +0 -0
  106. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/bash/bash_output.py +0 -0
  107. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/bash/jobs.py +0 -0
  108. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/bash/kill_shell.py +0 -0
  109. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/create_agent_type.py +0 -0
  110. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/definitions.py +0 -0
  111. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/files/delete_file.py +0 -0
  112. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/files/edit_file.py +0 -0
  113. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/files/list_files.py +0 -0
  114. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/files/read_file.py +0 -0
  115. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/files/write_file.py +0 -0
  116. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/get_current_datetime.py +0 -0
  117. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  118. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  119. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  120. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/memory/save_episode.py +0 -0
  121. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/memory/save_memory.py +0 -0
  122. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/names.py +0 -0
  123. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/search/glob.py +0 -0
  124. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/search/grep.py +0 -0
  125. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/search/walk.py +0 -0
  126. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/send_message.py +0 -0
  127. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/settings.py +0 -0
  128. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/stop_agent.py +0 -0
  129. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/todo_write.py +0 -0
  130. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/web_fetch.py +0 -0
  131. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff/tools/web_search.py +0 -0
  132. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff.egg-info/dependency_links.txt +0 -0
  133. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff.egg-info/entry_points.txt +0 -0
  134. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff.egg-info/requires.txt +0 -0
  135. {dostuff-0.2.8 → dostuff-0.2.10}/dostuff.egg-info/top_level.txt +0 -0
  136. {dostuff-0.2.8 → dostuff-0.2.10}/setup.cfg +0 -0
  137. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_ask_user.py +0 -0
  138. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_bash_command.py +0 -0
  139. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_checkpoints_todos_caching.py +0 -0
  140. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_cli_commands.py +0 -0
  141. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_create_agent_type.py +0 -0
  142. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_file_mentions.py +0 -0
  143. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_file_tools.py +0 -0
  144. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_hooks.py +0 -0
  145. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_jobs.py +0 -0
  146. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_mcp_e2e.py +0 -0
  147. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_mcp_oauth.py +0 -0
  148. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_opencode.py +0 -0
  149. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_optional_memory_and_instructions.py +0 -0
  150. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_pastes.py +0 -0
  151. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_permissions.py +0 -0
  152. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_roadmap_021.py +0 -0
  153. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_session_store.py +0 -0
  154. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_settings_tools.py +0 -0
  155. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_setup_wizard.py +0 -0
  156. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_skill_command.py +0 -0
  157. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_skills_discovery.py +0 -0
  158. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_slash_suggestion.py +0 -0
  159. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_subagent.py +0 -0
  160. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_subagents_background.py +0 -0
  161. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_subagents_fork.py +0 -0
  162. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_subagents_run.py +0 -0
  163. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_subagents_store.py +0 -0
  164. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_terminal_signals.py +0 -0
  165. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_tool_schemas.py +0 -0
  166. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_tools_listing.py +0 -0
  167. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_web_fetch.py +0 -0
  168. {dostuff-0.2.8 → dostuff-0.2.10}/tests/test_web_search.py +0 -0
  169. {dostuff-0.2.8 → dostuff-0.2.10}/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.10
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,8 @@ 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)
88
+ - **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
87
89
  - **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
90
  - **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
91
  - **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 +244,8 @@ In the TUI:
242
244
  | `/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
245
  | `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
244
246
  | `/copy` | Copy the model's last answer to the clipboard |
247
+ | `/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) |
248
+ | `/steer <message>` | Send a correction to the running turn: the model reads it at the next tool boundary and carries on, without the turn ending. See [Mid-turn steering](#mid-turn-steering-steer) |
245
249
  | `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
246
250
  | `/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
251
  | `/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 |
@@ -276,7 +280,8 @@ In the TUI:
276
280
  - **Status bar** — `cwd • model • permission mode • context usage %` by default; `help`, `session`, `tokens` and `cost` can be added. Choose and order the items with `ui.status_bar` in `config.yaml`; when the terminal is too narrow (or zoomed in), long items are shortened and the least important dropped (help, session, cwd, tokens, cost, model, context, mode) instead of being cut off
277
281
  - **Shells** — while background jobs run, a `⚙ 2 shells` item sits at the end of the status bar whatever `ui.status_bar` says. Click it (or press `↓` in an empty input) to list the session's jobs with when each started and how long it has run, and click it again to close the list; pick one (click or Enter) to see its last 8 lines of output and log path in the same small panel, refresh them, or stop it
278
282
  - **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
279
- - **Queued prompts** — prompts sent while a turn runs wait above the input, one row each, and run in order. Click the list (or `/queue`) to pick one and edit it (back into the input), run it next or remove it, or clear them all (`/queue clear`). `Esc` cancels the turn and moves the queued prompts back into the input instead of running them
283
+ - **Queued prompts** — prompts that have to wait for the turn sit above the input, one row each, and run in order: skill and custom commands in both modes, plain messages with `ui.mid_turn_messages: queue`. Click the list (or `/queue`) to pick one and edit it (back into the input), run it next or remove it, or clear them all (`/queue clear`). `Esc` cancels the turn and moves the queued prompts back into the input instead of running them
284
+ - **Steering messages** — `/steer <message>` (and every plain message by default; `ui.mid_turn_messages: queue` makes them wait instead) waits for the next tool boundary instead of the end of the turn: the bar leads with `→ N for the agent · read at the next tool boundary`, `/queue` lists them first with Edit / Remove (and *Send now* turns a queued prompt into one), and `Esc` puts a pending one back in the input ahead of the queue. See [Mid-turn steering](#mid-turn-steering-steer)
280
285
  - **Terminal title** — the tab / window title shows the run status: `⏳ dostuff · <folder>` while working, `✋` while an approval waits, `✓` when done; the old title comes back on exit. `ui.terminal_title: false` turns it off
281
286
  - **Notifications** (off by default) — `ui.notifications: bell` (terminal bell) or `osc9` (desktop notification in iTerm2, WezTerm, Ghostty, kitty …) when a turn finishes or an approval is waiting, if it took longer than `ui.notify_after_seconds` (30) or the terminal is in the background. `/notifications` switches it per session
282
287
 
@@ -464,6 +469,135 @@ is still listed but answers "No user is available in this run", and the model st
464
469
 
465
470
  ---
466
471
 
472
+ ## Side questions (`/btw`)
473
+
474
+ A turn can run for minutes, and halfway through you may want to know something *about* it: which file it just
475
+ edited, whether a test already exists, what you asked for. Typed into the input, that question would wait in the
476
+ queue until the turn ends; `Esc` would stop the work. `/btw <question>` answers it now, while the turn keeps running:
477
+
478
+ ```
479
+ ╭──────────────────────────────────────────────────────────────────────────────────╮
480
+ │ /btw — where does the retry happen? │
481
+ │ The retry loop is in call_agent, wrapped by classify_model_error; loop.py │
482
+ │ decides whether to compact or back off from its return value. │
483
+ │ Esc/Enter/Space close · f fork out · c copy · ↑18.4k (18.2k cached) ↓61 · │
484
+ │ $0.0021 │
485
+ ╰──────────────────────────────────────────────────────────────────────────────────╯
486
+ ```
487
+
488
+ The panel sits above the input and the conversation stays visible underneath. It shows `Asking…` until the answer
489
+ arrives; `↑`/`↓` scroll a long one.
490
+
491
+ - **No tools run.** The model sees the conversation up to the last completed step and answers from that alone, in
492
+ one response. If it asks for a tool or writes out a tool call instead, nothing runs and a note under the answer
493
+ says so.
494
+ - **Nothing is written.** The question and the answer never enter the transcript, the session history, `/export` or
495
+ the next compaction, and their cost is not added to the session: it is shown in the panel's footer instead, with
496
+ the prompt-cache hits: the side call sends the turn's own system prompt and tools, so a provider with prompt
497
+ caching can serve most of it from the cache. Hooks don't fire for it either.
498
+ - **No follow-up turns.** One question, one answer. Later `/btw`s in the same session see the earlier side questions
499
+ and answers (the last 20); `/clear`, `/resume` and `/fork` start a fresh side thread.
500
+
501
+ Keys while the panel has focus: `Esc`, `Enter` or `Space` close it (Esc closes the panel, it does **not** cancel the
502
+ turn), `c` copies the answer, and `f` forks it out. One side question at a time; a second `/btw` while one is still
503
+ asking is refused. If an approval prompt or an `ask_user` question opens while the panel is up, the prompt takes the
504
+ focus and the first `Esc`.
505
+
506
+ **Fork out (`f`).** When the conversation isn't enough to answer, `f` starts a background `fork` agent with the
507
+ question, the answer to check and the same view of the conversation the side question had. It runs with the main
508
+ agent's tools in its own slot (`/agents` shows it), costs what any background agent costs, and its report comes back
509
+ into the conversation like every background agent's. `Esc` on the main turn doesn't stop it. It is carried to the new
510
+ session by `/clear` and `/resume`; `/fork` leaves it with the original session and says so.
511
+
512
+ With no turn running, `/btw` works from the stored conversation and the last turn's system prompt. `dostuff -p` has
513
+ no `/btw` (only skills and custom commands run there), so `/btw` in a `-p` prompt is ordinary text for the model.
514
+
515
+ ---
516
+
517
+ ## Mid-turn steering (`/steer`)
518
+
519
+ A message typed while a turn runs normally waits its turn: it joins the queue and runs as its own prompt when the
520
+ current one ends. `/steer <message>` sends a **correction** instead — the model reads it at the next tool boundary and
521
+ carries on with it, without the turn ending and without anything being interrupted:
522
+
523
+ ```
524
+ > /steer actually target ./dostuff, not the repo root
525
+ ```
526
+
527
+ It lands in the transcript as a user message right after the tool output it was reacting to — where the model read it
528
+ — and the next model call sees it as the newest user message. A final answer that arrives while a correction is still
529
+ waiting does not end the turn: the model reads it and redoes or extends the answer. That check runs before the `Stop`
530
+ hooks, so they see the answer that really ends the turn.
531
+
532
+ What the model reads is framed, not bare: the stored user step is your text wrapped in two fixed lines —
533
+ `The user sent a new message while you were working:` above it, `Address the message above, then continue the task
534
+ you were working on.` below. The loop has no notion of "the task", only the history, so without that instruction a
535
+ standalone question tends to be answered with a final response and the turn ends with the interrupted work left
536
+ mid-flight; Claude Code wraps mid-turn messages the same way. Everything you *see* stays raw — the transcript line,
537
+ Esc-to-restore, and what a leftover re-runs — the frame reaches only the model, plus the stored transcript that
538
+ `/resume` replays.
539
+
540
+ ### Two modes
541
+
542
+ `ui.mid_turn_messages` in `config.yaml` decides what a **plain** message does while a turn runs (default `steer`):
543
+
544
+ | Submitted | `queue` | `steer` (default) |
545
+ |---|---|---|
546
+ | Plain message | waits in the queue, runs after the turn | steering: read at the next tool boundary |
547
+ | `/steer <message>` | steering | steering |
548
+ | `/<skill> args`, custom command | waits in the queue | waits in the queue |
549
+ | `/btw`, `/queue`, `/jobs`, … | run now | run now |
550
+ | `/clear`, `/resume`, `/model`, … | refused while a turn runs | refused while a turn runs |
551
+ | `!command` | refused while a turn runs | refused while a turn runs |
552
+ | `#note` (quick memory) | run now | run now |
553
+
554
+ `steer` is the default because it is Claude Code's behaviour: a correction is read now, at the next tool boundary,
555
+ instead of after the turn. `queue` stays one key away for anyone who prefers batching — three instructions typed in a
556
+ row run as three prompts while you are away, and a queued message is never read mid-task when you meant "next".
557
+ `/steer` works in both modes, and with no turn running it is
558
+ an ordinary prompt (it starts a turn), so the habit is never an error. Skills and custom commands stay in the queue in
559
+ both modes: a skill is a turn's prompt, not a correction.
560
+
561
+ ### What you see
562
+
563
+ - **On submit** the input clears and the bar above it leads with the steering group, `→ 1 for the agent · read at the next tool boundary`, above the usual `N queued · click or /queue …` rows; the loader counts them separately, `· 1 steering · 2 queued`.
564
+ - **`/queue`** lists the steering messages first, each marked `→`, with *Edit* and *Remove* (once the loop has read
565
+ one, the picker says "That message was already read."), and every queued prompt gained *Send now (at the next tool
566
+ boundary)*, which turns it into a correction.
567
+ - **Attachments are prepared in order**: `@mentions` are expanded and pastes resolved right after you send, in the
568
+ order you sent them, so a message holding a big file never jumps ahead of the one after it. The `Attached …` lines
569
+ show as they finish, as for a prompt.
570
+ - **Hooks and the sandbox still apply**: `UserPromptSubmit` runs for each correction at the boundary, so a hook can
571
+ block it — it is shown like a blocked prompt and never reaches the model — or add context for this turn, written as a
572
+ note right before the correction (the system prompt never changes mid-turn, so the prompt cache holds); a preparation
573
+ failure is reported instead of half-delivered.
574
+
575
+ ### Latency, and `Ctrl+B`
576
+
577
+ Delivery waits for the tool call in flight; nothing is interrupted to deliver sooner, so a two-minute `bash_command`
578
+ delays a correction two minutes. While a message waits behind a running command the bar says why —
579
+ `waiting for a running command · Ctrl+B to background it` — and `Ctrl+B` moves the command (or a foreground subagent)
580
+ to the background, which returns the call to the loop at once: the message is read at the next boundary while the
581
+ command keeps running. `Esc` remains the way to stop.
582
+
583
+ ### Leftovers
584
+
585
+ A correction can outlive its turn — sent after the final answer's last check, still being prepared, the turn hit the
586
+ iteration cap, the model call failed, or you pressed `Esc`. Nothing is lost:
587
+
588
+ - **Cancelled** (`Esc`) — the raw text goes back into the input **ahead of** the queued prompts: stopping the work
589
+ includes the corrections to it.
590
+ - **Otherwise** — it runs next: `1 message arrived after the turn ended; running it next`, then it is re-prepared from
591
+ what you typed and runs as a normal turn.
592
+
593
+ Either way the text you typed is written to the history exactly once — whether the model read it mid-turn or it ran as
594
+ the next turn.
595
+
596
+ `dostuff -p` has no `/steer` (only skills and custom commands run there), so a `/steer` line in a `-p` prompt is
597
+ ordinary text for the model.
598
+
599
+ ---
600
+
467
601
  ## Subagents
468
602
 
469
603
  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 +890,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
756
890
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
757
891
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
758
892
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
893
+ | `/btw` | `/btw` | not a tool: a side question fires no hook (no `UserPromptSubmit`, `PreToolUse` or `Stop`) |
759
894
 
760
895
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
761
896
  events.
@@ -805,6 +940,11 @@ permissions:
805
940
  mode: ask # ask | allowlist | auto | plan
806
941
  allow: []
807
942
 
943
+ ui:
944
+ mid_turn_messages: steer # steer (default): a plain message sent while a turn runs is read by the model at
945
+ # the next tool boundary, inside the running turn | queue: it waits and runs after
946
+ # the turn. /steer sends one either way (see Mid-turn steering)
947
+
808
948
  agents: # see Subagents
809
949
  max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
810
950
  max_concurrent: 4
@@ -36,6 +36,8 @@ 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)
40
+ - **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
39
41
  - **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
42
  - **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
43
  - **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 +196,8 @@ In the TUI:
194
196
  | `/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
197
  | `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
196
198
  | `/copy` | Copy the model's last answer to the clipboard |
199
+ | `/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) |
200
+ | `/steer <message>` | Send a correction to the running turn: the model reads it at the next tool boundary and carries on, without the turn ending. See [Mid-turn steering](#mid-turn-steering-steer) |
197
201
  | `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
198
202
  | `/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
203
  | `/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 |
@@ -228,7 +232,8 @@ In the TUI:
228
232
  - **Status bar** — `cwd • model • permission mode • context usage %` by default; `help`, `session`, `tokens` and `cost` can be added. Choose and order the items with `ui.status_bar` in `config.yaml`; when the terminal is too narrow (or zoomed in), long items are shortened and the least important dropped (help, session, cwd, tokens, cost, model, context, mode) instead of being cut off
229
233
  - **Shells** — while background jobs run, a `⚙ 2 shells` item sits at the end of the status bar whatever `ui.status_bar` says. Click it (or press `↓` in an empty input) to list the session's jobs with when each started and how long it has run, and click it again to close the list; pick one (click or Enter) to see its last 8 lines of output and log path in the same small panel, refresh them, or stop it
230
234
  - **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
231
- - **Queued prompts** — prompts sent while a turn runs wait above the input, one row each, and run in order. Click the list (or `/queue`) to pick one and edit it (back into the input), run it next or remove it, or clear them all (`/queue clear`). `Esc` cancels the turn and moves the queued prompts back into the input instead of running them
235
+ - **Queued prompts** — prompts that have to wait for the turn sit above the input, one row each, and run in order: skill and custom commands in both modes, plain messages with `ui.mid_turn_messages: queue`. Click the list (or `/queue`) to pick one and edit it (back into the input), run it next or remove it, or clear them all (`/queue clear`). `Esc` cancels the turn and moves the queued prompts back into the input instead of running them
236
+ - **Steering messages** — `/steer <message>` (and every plain message by default; `ui.mid_turn_messages: queue` makes them wait instead) waits for the next tool boundary instead of the end of the turn: the bar leads with `→ N for the agent · read at the next tool boundary`, `/queue` lists them first with Edit / Remove (and *Send now* turns a queued prompt into one), and `Esc` puts a pending one back in the input ahead of the queue. See [Mid-turn steering](#mid-turn-steering-steer)
232
237
  - **Terminal title** — the tab / window title shows the run status: `⏳ dostuff · <folder>` while working, `✋` while an approval waits, `✓` when done; the old title comes back on exit. `ui.terminal_title: false` turns it off
233
238
  - **Notifications** (off by default) — `ui.notifications: bell` (terminal bell) or `osc9` (desktop notification in iTerm2, WezTerm, Ghostty, kitty …) when a turn finishes or an approval is waiting, if it took longer than `ui.notify_after_seconds` (30) or the terminal is in the background. `/notifications` switches it per session
234
239
 
@@ -416,6 +421,135 @@ is still listed but answers "No user is available in this run", and the model st
416
421
 
417
422
  ---
418
423
 
424
+ ## Side questions (`/btw`)
425
+
426
+ A turn can run for minutes, and halfway through you may want to know something *about* it: which file it just
427
+ edited, whether a test already exists, what you asked for. Typed into the input, that question would wait in the
428
+ queue until the turn ends; `Esc` would stop the work. `/btw <question>` answers it now, while the turn keeps running:
429
+
430
+ ```
431
+ ╭──────────────────────────────────────────────────────────────────────────────────╮
432
+ │ /btw — where does the retry happen? │
433
+ │ The retry loop is in call_agent, wrapped by classify_model_error; loop.py │
434
+ │ decides whether to compact or back off from its return value. │
435
+ │ Esc/Enter/Space close · f fork out · c copy · ↑18.4k (18.2k cached) ↓61 · │
436
+ │ $0.0021 │
437
+ ╰──────────────────────────────────────────────────────────────────────────────────╯
438
+ ```
439
+
440
+ The panel sits above the input and the conversation stays visible underneath. It shows `Asking…` until the answer
441
+ arrives; `↑`/`↓` scroll a long one.
442
+
443
+ - **No tools run.** The model sees the conversation up to the last completed step and answers from that alone, in
444
+ one response. If it asks for a tool or writes out a tool call instead, nothing runs and a note under the answer
445
+ says so.
446
+ - **Nothing is written.** The question and the answer never enter the transcript, the session history, `/export` or
447
+ the next compaction, and their cost is not added to the session: it is shown in the panel's footer instead, with
448
+ the prompt-cache hits: the side call sends the turn's own system prompt and tools, so a provider with prompt
449
+ caching can serve most of it from the cache. Hooks don't fire for it either.
450
+ - **No follow-up turns.** One question, one answer. Later `/btw`s in the same session see the earlier side questions
451
+ and answers (the last 20); `/clear`, `/resume` and `/fork` start a fresh side thread.
452
+
453
+ Keys while the panel has focus: `Esc`, `Enter` or `Space` close it (Esc closes the panel, it does **not** cancel the
454
+ turn), `c` copies the answer, and `f` forks it out. One side question at a time; a second `/btw` while one is still
455
+ asking is refused. If an approval prompt or an `ask_user` question opens while the panel is up, the prompt takes the
456
+ focus and the first `Esc`.
457
+
458
+ **Fork out (`f`).** When the conversation isn't enough to answer, `f` starts a background `fork` agent with the
459
+ question, the answer to check and the same view of the conversation the side question had. It runs with the main
460
+ agent's tools in its own slot (`/agents` shows it), costs what any background agent costs, and its report comes back
461
+ into the conversation like every background agent's. `Esc` on the main turn doesn't stop it. It is carried to the new
462
+ session by `/clear` and `/resume`; `/fork` leaves it with the original session and says so.
463
+
464
+ With no turn running, `/btw` works from the stored conversation and the last turn's system prompt. `dostuff -p` has
465
+ no `/btw` (only skills and custom commands run there), so `/btw` in a `-p` prompt is ordinary text for the model.
466
+
467
+ ---
468
+
469
+ ## Mid-turn steering (`/steer`)
470
+
471
+ A message typed while a turn runs normally waits its turn: it joins the queue and runs as its own prompt when the
472
+ current one ends. `/steer <message>` sends a **correction** instead — the model reads it at the next tool boundary and
473
+ carries on with it, without the turn ending and without anything being interrupted:
474
+
475
+ ```
476
+ > /steer actually target ./dostuff, not the repo root
477
+ ```
478
+
479
+ It lands in the transcript as a user message right after the tool output it was reacting to — where the model read it
480
+ — and the next model call sees it as the newest user message. A final answer that arrives while a correction is still
481
+ waiting does not end the turn: the model reads it and redoes or extends the answer. That check runs before the `Stop`
482
+ hooks, so they see the answer that really ends the turn.
483
+
484
+ What the model reads is framed, not bare: the stored user step is your text wrapped in two fixed lines —
485
+ `The user sent a new message while you were working:` above it, `Address the message above, then continue the task
486
+ you were working on.` below. The loop has no notion of "the task", only the history, so without that instruction a
487
+ standalone question tends to be answered with a final response and the turn ends with the interrupted work left
488
+ mid-flight; Claude Code wraps mid-turn messages the same way. Everything you *see* stays raw — the transcript line,
489
+ Esc-to-restore, and what a leftover re-runs — the frame reaches only the model, plus the stored transcript that
490
+ `/resume` replays.
491
+
492
+ ### Two modes
493
+
494
+ `ui.mid_turn_messages` in `config.yaml` decides what a **plain** message does while a turn runs (default `steer`):
495
+
496
+ | Submitted | `queue` | `steer` (default) |
497
+ |---|---|---|
498
+ | Plain message | waits in the queue, runs after the turn | steering: read at the next tool boundary |
499
+ | `/steer <message>` | steering | steering |
500
+ | `/<skill> args`, custom command | waits in the queue | waits in the queue |
501
+ | `/btw`, `/queue`, `/jobs`, … | run now | run now |
502
+ | `/clear`, `/resume`, `/model`, … | refused while a turn runs | refused while a turn runs |
503
+ | `!command` | refused while a turn runs | refused while a turn runs |
504
+ | `#note` (quick memory) | run now | run now |
505
+
506
+ `steer` is the default because it is Claude Code's behaviour: a correction is read now, at the next tool boundary,
507
+ instead of after the turn. `queue` stays one key away for anyone who prefers batching — three instructions typed in a
508
+ row run as three prompts while you are away, and a queued message is never read mid-task when you meant "next".
509
+ `/steer` works in both modes, and with no turn running it is
510
+ an ordinary prompt (it starts a turn), so the habit is never an error. Skills and custom commands stay in the queue in
511
+ both modes: a skill is a turn's prompt, not a correction.
512
+
513
+ ### What you see
514
+
515
+ - **On submit** the input clears and the bar above it leads with the steering group, `→ 1 for the agent · read at the next tool boundary`, above the usual `N queued · click or /queue …` rows; the loader counts them separately, `· 1 steering · 2 queued`.
516
+ - **`/queue`** lists the steering messages first, each marked `→`, with *Edit* and *Remove* (once the loop has read
517
+ one, the picker says "That message was already read."), and every queued prompt gained *Send now (at the next tool
518
+ boundary)*, which turns it into a correction.
519
+ - **Attachments are prepared in order**: `@mentions` are expanded and pastes resolved right after you send, in the
520
+ order you sent them, so a message holding a big file never jumps ahead of the one after it. The `Attached …` lines
521
+ show as they finish, as for a prompt.
522
+ - **Hooks and the sandbox still apply**: `UserPromptSubmit` runs for each correction at the boundary, so a hook can
523
+ block it — it is shown like a blocked prompt and never reaches the model — or add context for this turn, written as a
524
+ note right before the correction (the system prompt never changes mid-turn, so the prompt cache holds); a preparation
525
+ failure is reported instead of half-delivered.
526
+
527
+ ### Latency, and `Ctrl+B`
528
+
529
+ Delivery waits for the tool call in flight; nothing is interrupted to deliver sooner, so a two-minute `bash_command`
530
+ delays a correction two minutes. While a message waits behind a running command the bar says why —
531
+ `waiting for a running command · Ctrl+B to background it` — and `Ctrl+B` moves the command (or a foreground subagent)
532
+ to the background, which returns the call to the loop at once: the message is read at the next boundary while the
533
+ command keeps running. `Esc` remains the way to stop.
534
+
535
+ ### Leftovers
536
+
537
+ A correction can outlive its turn — sent after the final answer's last check, still being prepared, the turn hit the
538
+ iteration cap, the model call failed, or you pressed `Esc`. Nothing is lost:
539
+
540
+ - **Cancelled** (`Esc`) — the raw text goes back into the input **ahead of** the queued prompts: stopping the work
541
+ includes the corrections to it.
542
+ - **Otherwise** — it runs next: `1 message arrived after the turn ended; running it next`, then it is re-prepared from
543
+ what you typed and runs as a normal turn.
544
+
545
+ Either way the text you typed is written to the history exactly once — whether the model read it mid-turn or it ran as
546
+ the next turn.
547
+
548
+ `dostuff -p` has no `/steer` (only skills and custom commands run there), so a `/steer` line in a `-p` prompt is
549
+ ordinary text for the model.
550
+
551
+ ---
552
+
419
553
  ## Subagents
420
554
 
421
555
  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 +842,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
708
842
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
709
843
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
710
844
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
845
+ | `/btw` | `/btw` | not a tool: a side question fires no hook (no `UserPromptSubmit`, `PreToolUse` or `Stop`) |
711
846
 
712
847
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
713
848
  events.
@@ -757,6 +892,11 @@ permissions:
757
892
  mode: ask # ask | allowlist | auto | plan
758
893
  allow: []
759
894
 
895
+ ui:
896
+ mid_turn_messages: steer # steer (default): a plain message sent while a turn runs is read by the model at
897
+ # the next tool boundary, inside the running turn | queue: it waits and runs after
898
+ # the turn. /steer sends one either way (see Mid-turn steering)
899
+
760
900
  agents: # see Subagents
761
901
  max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
762
902
  max_concurrent: 4
@@ -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,24 @@ 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
22
  from dostuff.helpers.hooks.events import (
24
- STOP_LIMIT_MESSAGE, STOP_NOTE, session_context_suffix, session_start, stop_event_for,
23
+ STOP_LIMIT_MESSAGE, STOP_NOTE, session_start, stop_event_for, user_prompt_submit,
25
24
  )
26
25
  from dostuff.helpers.hooks.run_hook import payload_for
27
26
  from dostuff.config import AUTO_COMPACT_THRESHOLD, get_config
28
27
  from dostuff.tools.definitions import TOOL_MAP, default_tool_names
29
28
  from dostuff.agent.subagents.fork import ForkContext
30
29
  from dostuff.helpers.agent.notices import format_notices, get_notice_queue
30
+ from dostuff.helpers.agent.steering import SteerMessage, SteeringQueue, frame_steered
31
+ from dostuff.helpers.agent.side_question import (
32
+ compose_system_instruction, plan_mode_on, publish_snapshot, published_snapshot, usage_dict as build_usage_dict,
33
+ )
31
34
  from dostuff.tools.bash.jobs import Job, JobEvent, get_registry
32
35
  from typing import Any, Iterator, Literal
33
36
  import contextlib
@@ -188,7 +191,7 @@ def _job_events(owner: str, adapter: Any) -> Iterator[None]:
188
191
  registry.remove_listener(on_job)
189
192
 
190
193
 
191
- async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_instruction: str, mcp_client: MCPClient, working_history: list, turn_type: Literal['interactive_loop', 'subagent_loop'], current_session_history=None, steps_history=None, store=None, adapter=None, compaction_notes: str = "", session_prompt_tokens: int = 0, session_completion_tokens: int = 0, session_total_tokens: int = 0, last_input_tokens: int = 0, stream: bool = True, max_iterations: int = MAX_ITERATIONS, tool_names: list[str] | None = None, permissions: SessionPermissions | None = None, session_hook_context: dict[str, str] | None = None, owner: str | None = None, inbox: list[str] | None = None) -> str:
194
+ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_instruction: str, mcp_client: MCPClient, working_history: list, turn_type: Literal['interactive_loop', 'subagent_loop'], current_session_history=None, steps_history=None, store=None, adapter=None, compaction_notes: str = "", session_prompt_tokens: int = 0, session_completion_tokens: int = 0, session_total_tokens: int = 0, last_input_tokens: int = 0, stream: bool = True, max_iterations: int = MAX_ITERATIONS, tool_names: list[str] | None = None, permissions: SessionPermissions | None = None, session_hook_context: dict[str, str] | None = None, owner: str | None = None, inbox: list[str] | None = None, steering: SteeringQueue | None = None) -> str:
192
195
  """Run one agent turn. `working_history` is mutated in place (appends and compaction).
193
196
 
194
197
  `session_hook_context` is the caller's per-session SessionStart context (hooks spec REQ-2.4): added to
@@ -198,9 +201,14 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
198
201
 
199
202
  `inbox` is a subagent's `send_message` queue (subagents spec D10): each message becomes a user step before
200
203
  the next model call, and a final answer with messages waiting doesn't end the run.
204
+
205
+ `steering` is the TUI's mid-turn messages (steering spec D1): read at the next tool boundary, inside this
206
+ turn. Main session only — a `subagent_loop` never delivers one (CON-008), and `run_agent_loop` doesn't pass it.
201
207
  """
202
208
  current_session_id.set(session_id)
203
209
  owner = owner or session_id
210
+ # Main session only (CON-008): a subagent's route is send_message, never the steering queue
211
+ steer = steering if turn_type == "interactive_loop" else None
204
212
  iteration = 0
205
213
  token_limit = get_model_token_limit()
206
214
  config = get_config()
@@ -234,6 +242,7 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
234
242
  except Exception as e:
235
243
  await loop_emit("error", f"Could not save compaction: {e}", adapter=adapter)
236
244
  await loop_emit("system", f"{reason} Context compacted. Notes: {compaction_notes}", adapter=adapter)
245
+ publish_snapshot(session_id, fork_context()) # /btw must not read the history that just overflowed
237
246
  if session_hook_context is not None and turn_type == "interactive_loop": # a fork carries the main's
238
247
  # Earlier SessionStart context may be stale now; refresh it under its own key (REQ-2.4)
239
248
  await session_start("compact", session_hook_context, session_id=session_id, turn_id=turn_id,
@@ -241,9 +250,52 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
241
250
  return True
242
251
 
243
252
  async def append_note(text: str) -> None:
244
- """A harness-authored user step: a Stop-hook continuation, background notices or a send_message."""
253
+ """A harness-authored user step: a Stop-hook continuation, background notices, a send_message or a
254
+ framed steering message."""
245
255
  await append_step({"role": "user", "content": text}, steps_history, working_history, current_session_history, session_id, store, turn_type)
246
256
 
257
+ async def deliver_steer(messages: list[SteerMessage]) -> int:
258
+ """D6's drain body, shared by the top-of-iteration drain and D7's final-answer path: a failed
259
+ or blocked message is reported and appended nowhere, the rest is written framed and once
260
+ (CON-004) after UserPromptSubmit (CON-007). Hook context, if any, rides ahead of the frame as
261
+ its own note — never a system-instruction fold, which mid-turn would invalidate the provider's
262
+ cached prompt prefix (the system prompt is stable within a turn). Returns how many reached the
263
+ history — D7 re-prompts the model only when that is above zero, never with an unchanged history."""
264
+ delivered = 0
265
+ for steer_msg in messages:
266
+ if steer_msg.failed is not None:
267
+ await loop_emit("steer_failed", {"id": steer_msg.id, "error": steer_msg.failed},
268
+ adapter=adapter)
269
+ continue
270
+ if steer_msg.content is None:
271
+ continue # unreachable: take_ready only returns ready or failed entries
272
+ blocked, context = await user_prompt_submit(
273
+ steer_msg.content, session_id=session_id, turn_id=turn_id, turn_type=turn_type,
274
+ adapter=adapter)
275
+ if blocked is not None:
276
+ await loop_emit("steer_blocked", {"id": steer_msg.id, "reason": blocked},
277
+ adapter=adapter)
278
+ continue
279
+ if context:
280
+ # In-band note, not a system fold: a mid-turn system change would invalidate the
281
+ # provider's whole cached prefix — the system prompt stays byte-stable in a turn.
282
+ await append_note(f"[Context from UserPromptSubmit hooks]\n{context}")
283
+ await append_note(frame_steered(steer_msg.content)) # the steer message's only write (CON-004), framed (D6)
284
+ await loop_emit("steered", {"id": steer_msg.id, "index": len(steps_history) - 1},
285
+ adapter=adapter)
286
+ delivered += 1
287
+ return delivered
288
+
289
+ async def drain_facts() -> None:
290
+ """Background-job notices and inbox messages, oldest first (D1/D7): both the top of an
291
+ iteration and D7's final-answer path drain them before a correction is delivered, so a
292
+ correction lands after the facts it may be reacting to."""
293
+ notices = get_notice_queue().drain(owner)
294
+ if notices:
295
+ await append_note(format_notices(notices, max_tool_output_chars))
296
+ while inbox: # send_message to this running subagent, oldest first (D10)
297
+ await append_note(inbox.pop(0))
298
+
247
299
  def fork_context() -> ForkContext | None:
248
300
  """What a fork started now inherits (subagents spec D11): the history as it is before this response's
249
301
  assistant step is appended, and the system prompt parts as this model call got them. Main agent only."""
@@ -265,7 +317,8 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
265
317
  if context_token_threshold is not None and last_input_tokens > context_token_threshold:
266
318
  await compact("Token threshold exceeded.", keep_recent_token_budget)
267
319
 
268
- with tracer.start_as_current_span("turn") as turn_span, _job_events(owner, adapter):
320
+ with tracer.start_as_current_span("turn") as turn_span, _job_events(owner, adapter), \
321
+ published_snapshot(session_id, enabled=turn_type == "interactive_loop"):
269
322
  turn_span.set_attribute("session_id", session_id)
270
323
  turn_span.set_attribute("turn_type", turn_type)
271
324
  turn_span.set_attribute("turn_id", turn_id)
@@ -283,11 +336,14 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
283
336
  return CANCELLED_TURN
284
337
 
285
338
  # Background jobs and agents of this run that ended since the last model call (spec D7)
286
- notices = get_notice_queue().drain(owner)
287
- if notices:
288
- await append_note(format_notices(notices, max_tool_output_chars))
289
- while inbox: # send_message to this running subagent, oldest first (D10)
290
- await append_note(inbox.pop(0))
339
+ await drain_facts()
340
+ if steer is not None:
341
+ # The user's mid-turn messages, in submit order (D6): after the notices and the inbox so a
342
+ # correction is read after the facts it may be reacting to, before publish_snapshot so a
343
+ # /btw asked afterwards sees it.
344
+ await deliver_steer(steer.take_ready())
345
+ # What a /btw side question reads while this turn runs (btw spec D3); main agent only
346
+ publish_snapshot(session_id, fork_context())
291
347
 
292
348
  # Model call with classified retries and exponential backoff
293
349
  interaction = None
@@ -299,13 +355,11 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
299
355
  progress = StreamProgress()
300
356
  try:
301
357
  # 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"
358
+ plan_mode = plan_mode_on(permissions, config)
303
359
  interaction, model_span = await call_agent(
304
360
  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),
361
+ system_instruction=compose_system_instruction(
362
+ dynamic_system_instruction, plan_mode, compaction_notes, session_hook_context),
309
363
  tool_names=tool_names,
310
364
  stream=stream,
311
365
  )
@@ -342,24 +396,12 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
342
396
  if interaction is None:
343
397
  return CANCELLED_TURN
344
398
 
345
- usage_dict = None
346
- usage = getattr(interaction, "usage", None)
399
+ usage_dict = build_usage_dict(interaction) # None when the response has no usage
347
400
  choices = getattr(interaction, "choices", None)
348
401
  message = choices[0].message if choices else None
349
402
  tool_calls = getattr(message, "tool_calls", None) if message else None
350
403
  content = getattr(message, "content", None) if message else None
351
404
 
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
405
  # close model_span exactly once, here, before any continue/return below
364
406
  if model_span is not None and model_span.is_recording():
365
407
  if usage_dict:
@@ -397,9 +439,36 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
397
439
  "content": content,
398
440
  }
399
441
  await append_step(model_step, steps_history, working_history, current_session_history, session_id, store, turn_type)
400
- if inbox: # a send_message arrived during this call: read it instead of ending
442
+ if inbox:
443
+ # A send_message arrived during this call: read it instead of ending (D10) — inbox
444
+ # items always append at the drain, so the model always gets something new. Before
445
+ # the Stop hooks, so a Stop hook sees the answer that really ends the turn.
401
446
  iter_span.set_status(Status(StatusCode.OK))
402
447
  continue
448
+ if steer is not None and steer.has_ready_or_preparing():
449
+ # D7: a steering message arrived during this call — read it instead of ending, but
450
+ # never re-prompt with unchanged history: a failed or blocked message is reported
451
+ # without appending and a still-preparing one appends nothing. Wait for each pending
452
+ # message to settle, deliver what passes, and fall through to the Stop hooks once
453
+ # nothing more will be delivered.
454
+ steer_delivered = 0
455
+ while steer.has_ready_or_preparing() and not steer_delivered:
456
+ if await check_cancelled():
457
+ return CANCELLED_TURN
458
+ steer_taken = steer.take_ready()
459
+ if steer_taken:
460
+ await drain_facts() # D1 order: facts that arrived during the call
461
+ # land before the correction reacting to them (review round 2)
462
+ steer_delivered += await deliver_steer(steer_taken)
463
+ else:
464
+ # preparation in flight: wait for it instead of calling the model again
465
+ # with no new user content (the message arrives at this boundary anyway)
466
+ await asyncio.sleep(0.05)
467
+ if steer_delivered:
468
+ iter_span.set_status(Status(StatusCode.OK))
469
+ continue
470
+ # every pending message failed or was blocked (both already reported above): this
471
+ # answer really ends the turn — fall through to the Stop hooks below.
403
472
 
404
473
  # Stop / SubagentStop: only here, on a final answer, never on cancel, errors or the
405
474
  # iteration cap. A block keeps the turn going, at most stop_block_limit times (REQ-2.3)