dostuff 0.2.7__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 (168) hide show
  1. {dostuff-0.2.7 → dostuff-0.2.9}/PKG-INFO +118 -1
  2. {dostuff-0.2.7 → dostuff-0.2.9}/README.md +117 -0
  3. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/loop.py +35 -32
  4. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/permissions.py +2 -1
  5. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/subagents/__init__.py +2 -0
  6. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/subagents/definitions.py +9 -3
  7. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/cli_tui.py +930 -53
  8. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/headless.py +40 -0
  9. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/constants.py +12 -0
  10. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/loop_check_cancelled.py +5 -0
  11. dostuff-0.2.9/dostuff/helpers/agent/side_question.py +226 -0
  12. dostuff-0.2.9/dostuff/helpers/agent/tool_output.py +83 -0
  13. dostuff-0.2.9/dostuff/helpers/ui/ask_answers.py +90 -0
  14. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/ui/tools_listing.py +1 -0
  15. dostuff-0.2.9/dostuff/tools/ask_user.py +184 -0
  16. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/definitions.py +4 -0
  17. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/names.py +1 -0
  18. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff.egg-info/PKG-INFO +118 -1
  19. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff.egg-info/SOURCES.txt +6 -0
  20. {dostuff-0.2.7 → dostuff-0.2.9}/pyproject.toml +1 -1
  21. dostuff-0.2.9/tests/test_ask_user.py +586 -0
  22. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_cli_commands.py +187 -0
  23. dostuff-0.2.9/tests/test_loop.py +688 -0
  24. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_permissions.py +21 -0
  25. dostuff-0.2.9/tests/test_side_question.py +341 -0
  26. dostuff-0.2.9/tests/test_side_question_litellm.py +41 -0
  27. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_subagents_types.py +24 -1
  28. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_tool_schemas.py +16 -0
  29. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_tools_listing.py +10 -0
  30. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_tui.py +2367 -0
  31. dostuff-0.2.7/dostuff/helpers/agent/tool_output.py +0 -44
  32. dostuff-0.2.7/tests/test_loop.py +0 -261
  33. {dostuff-0.2.7 → dostuff-0.2.9}/LICENSE +0 -0
  34. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/__init__.py +0 -0
  35. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/__main__.py +0 -0
  36. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/call_agent.py +0 -0
  37. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/instructions.py +0 -0
  38. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/run_tool.py +0 -0
  39. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/subagents/adapter.py +0 -0
  40. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/subagents/fork.py +0 -0
  41. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/subagents/prompt.py +0 -0
  42. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/subagents/registry.py +0 -0
  43. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/agent/subagents/run.py +0 -0
  44. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/cli.py +0 -0
  45. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/config.py +0 -0
  46. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/append_step.py +0 -0
  47. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/consume_stream.py +0 -0
  48. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/context_usage.py +0 -0
  49. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/environment_context.py +0 -0
  50. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/file_mentions.py +0 -0
  51. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  52. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/load_identity.py +0 -0
  53. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  54. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/loop_emit.py +0 -0
  55. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/manage_context.py +0 -0
  56. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/model_cost.py +0 -0
  57. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/notices.py +0 -0
  58. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/pastes.py +0 -0
  59. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/quick_memory.py +0 -0
  60. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  61. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/hooks/__init__.py +0 -0
  62. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/hooks/dispatch.py +0 -0
  63. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/hooks/events.py +0 -0
  64. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/hooks/load_hooks.py +0 -0
  65. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/hooks/run_hook.py +0 -0
  66. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/hooks/trust.py +0 -0
  67. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  68. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  69. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/mcp/server_config.py +0 -0
  70. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/mcp/token_store.py +0 -0
  71. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/memory/export_session.py +0 -0
  72. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  73. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/memory/shell_step.py +0 -0
  74. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/models/add_model_entry.py +0 -0
  75. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/models/list_models.py +0 -0
  76. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/models/opencode.py +0 -0
  77. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/skills/custom_commands.py +0 -0
  78. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/skills/discover_skills.py +0 -0
  79. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/skills/skill_command.py +0 -0
  80. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/tools/diff.py +0 -0
  81. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  82. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/tools/project_root.py +0 -0
  83. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  84. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/ui/__init__.py +0 -0
  85. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/ui/doctor.py +0 -0
  86. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/ui/emit.py +0 -0
  87. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/ui/prompt_history.py +0 -0
  88. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/helpers/ui/terminal_signals.py +0 -0
  89. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/checkpoints.py +0 -0
  90. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/exceptions.py +0 -0
  91. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/mcp/mcp_client.py +0 -0
  92. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  93. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  94. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/memory/chroma.py +0 -0
  95. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  96. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  97. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/memory/session_store.py +0 -0
  98. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/memory/stores.py +0 -0
  99. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/memory/types.py +0 -0
  100. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/model.py +0 -0
  101. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/tracing.py +0 -0
  102. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/lib/worktree.py +0 -0
  103. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/memory/__init__.py +0 -0
  104. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/setup_wizard.py +0 -0
  105. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/skills.py +0 -0
  106. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/templates/config.example.yaml +0 -0
  107. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/templates/env.example +0 -0
  108. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/__init__.py +0 -0
  109. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/agent.py +0 -0
  110. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/bash/bash_command.py +0 -0
  111. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/bash/bash_output.py +0 -0
  112. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/bash/jobs.py +0 -0
  113. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/bash/kill_shell.py +0 -0
  114. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/create_agent_type.py +0 -0
  115. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/files/delete_file.py +0 -0
  116. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/files/edit_file.py +0 -0
  117. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/files/list_files.py +0 -0
  118. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/files/read_file.py +0 -0
  119. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/files/write_file.py +0 -0
  120. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/get_current_datetime.py +0 -0
  121. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  122. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  123. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  124. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/memory/save_episode.py +0 -0
  125. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/memory/save_memory.py +0 -0
  126. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/search/glob.py +0 -0
  127. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/search/grep.py +0 -0
  128. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/search/walk.py +0 -0
  129. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/send_message.py +0 -0
  130. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/settings.py +0 -0
  131. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/stop_agent.py +0 -0
  132. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/todo_write.py +0 -0
  133. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/web_fetch.py +0 -0
  134. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff/tools/web_search.py +0 -0
  135. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff.egg-info/dependency_links.txt +0 -0
  136. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff.egg-info/entry_points.txt +0 -0
  137. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff.egg-info/requires.txt +0 -0
  138. {dostuff-0.2.7 → dostuff-0.2.9}/dostuff.egg-info/top_level.txt +0 -0
  139. {dostuff-0.2.7 → dostuff-0.2.9}/setup.cfg +0 -0
  140. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_bash_command.py +0 -0
  141. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_checkpoints_todos_caching.py +0 -0
  142. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_config_memory_mcp.py +0 -0
  143. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_create_agent_type.py +0 -0
  144. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_file_mentions.py +0 -0
  145. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_file_tools.py +0 -0
  146. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_hooks.py +0 -0
  147. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_jobs.py +0 -0
  148. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_mcp_e2e.py +0 -0
  149. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_mcp_oauth.py +0 -0
  150. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_opencode.py +0 -0
  151. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_optional_memory_and_instructions.py +0 -0
  152. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_pastes.py +0 -0
  153. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_roadmap_021.py +0 -0
  154. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_session_store.py +0 -0
  155. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_settings_tools.py +0 -0
  156. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_setup_wizard.py +0 -0
  157. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_skill_command.py +0 -0
  158. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_skills_discovery.py +0 -0
  159. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_slash_suggestion.py +0 -0
  160. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_subagent.py +0 -0
  161. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_subagents_background.py +0 -0
  162. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_subagents_fork.py +0 -0
  163. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_subagents_run.py +0 -0
  164. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_subagents_store.py +0 -0
  165. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_terminal_signals.py +0 -0
  166. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_web_fetch.py +0 -0
  167. {dostuff-0.2.7 → dostuff-0.2.9}/tests/test_web_search.py +0 -0
  168. {dostuff-0.2.7 → 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.7
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
@@ -83,6 +83,8 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
83
83
  - **`@file` mentions** — type `@` in the prompt to pick a file or folder; its content (or listing) is sent with the message
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
+ - **`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)
86
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
87
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)
88
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)
@@ -241,6 +243,7 @@ In the TUI:
241
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) |
242
244
  | `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
243
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) |
244
247
  | `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
245
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 |
246
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 |
@@ -295,6 +298,7 @@ In the TUI:
295
298
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
296
299
  | `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url` |
297
300
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
301
+ | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
298
302
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
299
303
  | `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
300
304
 
@@ -396,6 +400,117 @@ paths). Directories older than 7 days are removed at startup.
396
400
 
397
401
  ---
398
402
 
403
+ ## Asking the user
404
+
405
+ `ask_user` lets the agent stop and ask instead of guessing: a library to use, a product decision, a name. It is
406
+ the one tool that talks to you, it never needs approval, and subagents never get it (they report back instead).
407
+
408
+ The questions arrive as a panel in place of the input:
409
+
410
+ ```
411
+ ✓ DB · ▌ Auth · Name
412
+ Which auth methods should the API support?
413
+ ❯ 1. JWT stateless, no extra service
414
+ 2. OAuth a provider to configure
415
+ 3. Other (type your own)
416
+ ────────────────────────────────────────────────────────
417
+ Submit answers (answer every question first)
418
+ ↑/↓ select · Enter confirm · ←/→ change question · Esc cancel
419
+ ```
420
+
421
+ The top line is the tab strip: `▌` marks the question you are on (bold and orange), `✓` marks one you have
422
+ answered, and both sit in the same slot so the tabs never shift as you answer. The submit row is dim until
423
+ every question has an answer, then it brightens and the parenthetical hint goes away.
424
+
425
+ - **Nothing submits on one key.** A pick records the answer and moves to the next question; `Submit answers` is
426
+ the only thing that sends, and it stays inert (`answer every question first`) until every question has one.
427
+ `←`/`Shift+Tab` goes back, so an earlier answer can be changed before submitting.
428
+ - **`2-4` options, one line each**, with the trade-off where it matters. A multi-select question toggles with
429
+ `space` or its number, and the joined answer comes back in option order.
430
+ - **`Other`** is always the last row, numbered after the options: pick it and the input takes a typed answer (a
431
+ pasted block is collapsed to one line). A question with no options shows as just that row, so it still appears
432
+ in the tab strip; **Enter** (or `o`) on it takes the input, and `←`/`Tab` still move between questions — so
433
+ landing on a free-text question never traps you in the input. A call where *every* question is free text skips
434
+ the panel entirely and the input takes each answer in turn, with the last Enter as the submission.
435
+ - **Esc** cancels the questions and ends the turn, like Esc on an approval prompt. **Ctrl+Q** / `/exit` with a
436
+ question open cancel it first and then quit.
437
+ - Up to 4 questions per call. The prompt tells the model when to ask: when the answer changes what it builds and
438
+ the repo can't tell it; never to confirm a plan, to ask permission, or for anything `grep` / `read_file` answers.
439
+
440
+ The answers reach the model as one tool result, and the transcript shows the same pairs as one block — live and
441
+ after `/resume`:
442
+
443
+ ```
444
+ ⎿ Which database should I use? → Postgres
445
+ Which auth methods should the API support? → JWT, OAuth
446
+ ```
447
+
448
+ Nothing is truncated and Ctrl+O has nothing to expand, unlike an ordinary tool result: reading back what you
449
+ answered is the point. What the model actually receives is `format_answers`' output:
450
+
451
+ ```text
452
+ Asked the user 2 questions; they answered:
453
+ 1. Which database should I use?
454
+ → Postgres
455
+ 2. Which auth methods should the API support?
456
+ → JWT, OAuth
457
+ ```
458
+
459
+ A cancelled, refused or unavailable call renders as an ordinary tool result, with the model told what to do
460
+ (state the assumption and continue). `/export` writes the result text verbatim.
461
+
462
+ **`dostuff -p`** asks on the terminal when both stdin and stderr are a TTY: each question and its numbered options
463
+ go to stderr, and it reads one line per question (`2`, `1,3`, or free text; an empty line is `(no answer)`). There
464
+ is no submit row, because a line reader has no way back. With piped stdin (or stderr redirected to a file) the tool
465
+ is still listed but answers "No user is available in this run", and the model states an assumption and carries on.
466
+
467
+ ---
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
+
399
514
  ## Subagents
400
515
 
401
516
  A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
@@ -686,7 +801,9 @@ nesting are the same. Tool names and some argument names differ, so rename the m
686
801
  | `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
687
802
  | `Read` | `read_file` | `file_path` → `path` |
688
803
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
804
+ | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
689
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`) |
690
807
 
691
808
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
692
809
  events.
@@ -35,6 +35,8 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
35
35
  - **`@file` mentions** — type `@` in the prompt to pick a file or folder; its content (or listing) is sent with the message
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
+ - **`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)
38
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
39
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)
40
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)
@@ -193,6 +195,7 @@ In the TUI:
193
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) |
194
196
  | `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
195
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) |
196
199
  | `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
197
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 |
198
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 |
@@ -247,6 +250,7 @@ In the TUI:
247
250
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
248
251
  | `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url` |
249
252
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
253
+ | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
250
254
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
251
255
  | `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
252
256
 
@@ -348,6 +352,117 @@ paths). Directories older than 7 days are removed at startup.
348
352
 
349
353
  ---
350
354
 
355
+ ## Asking the user
356
+
357
+ `ask_user` lets the agent stop and ask instead of guessing: a library to use, a product decision, a name. It is
358
+ the one tool that talks to you, it never needs approval, and subagents never get it (they report back instead).
359
+
360
+ The questions arrive as a panel in place of the input:
361
+
362
+ ```
363
+ ✓ DB · ▌ Auth · Name
364
+ Which auth methods should the API support?
365
+ ❯ 1. JWT stateless, no extra service
366
+ 2. OAuth a provider to configure
367
+ 3. Other (type your own)
368
+ ────────────────────────────────────────────────────────
369
+ Submit answers (answer every question first)
370
+ ↑/↓ select · Enter confirm · ←/→ change question · Esc cancel
371
+ ```
372
+
373
+ The top line is the tab strip: `▌` marks the question you are on (bold and orange), `✓` marks one you have
374
+ answered, and both sit in the same slot so the tabs never shift as you answer. The submit row is dim until
375
+ every question has an answer, then it brightens and the parenthetical hint goes away.
376
+
377
+ - **Nothing submits on one key.** A pick records the answer and moves to the next question; `Submit answers` is
378
+ the only thing that sends, and it stays inert (`answer every question first`) until every question has one.
379
+ `←`/`Shift+Tab` goes back, so an earlier answer can be changed before submitting.
380
+ - **`2-4` options, one line each**, with the trade-off where it matters. A multi-select question toggles with
381
+ `space` or its number, and the joined answer comes back in option order.
382
+ - **`Other`** is always the last row, numbered after the options: pick it and the input takes a typed answer (a
383
+ pasted block is collapsed to one line). A question with no options shows as just that row, so it still appears
384
+ in the tab strip; **Enter** (or `o`) on it takes the input, and `←`/`Tab` still move between questions — so
385
+ landing on a free-text question never traps you in the input. A call where *every* question is free text skips
386
+ the panel entirely and the input takes each answer in turn, with the last Enter as the submission.
387
+ - **Esc** cancels the questions and ends the turn, like Esc on an approval prompt. **Ctrl+Q** / `/exit` with a
388
+ question open cancel it first and then quit.
389
+ - Up to 4 questions per call. The prompt tells the model when to ask: when the answer changes what it builds and
390
+ the repo can't tell it; never to confirm a plan, to ask permission, or for anything `grep` / `read_file` answers.
391
+
392
+ The answers reach the model as one tool result, and the transcript shows the same pairs as one block — live and
393
+ after `/resume`:
394
+
395
+ ```
396
+ ⎿ Which database should I use? → Postgres
397
+ Which auth methods should the API support? → JWT, OAuth
398
+ ```
399
+
400
+ Nothing is truncated and Ctrl+O has nothing to expand, unlike an ordinary tool result: reading back what you
401
+ answered is the point. What the model actually receives is `format_answers`' output:
402
+
403
+ ```text
404
+ Asked the user 2 questions; they answered:
405
+ 1. Which database should I use?
406
+ → Postgres
407
+ 2. Which auth methods should the API support?
408
+ → JWT, OAuth
409
+ ```
410
+
411
+ A cancelled, refused or unavailable call renders as an ordinary tool result, with the model told what to do
412
+ (state the assumption and continue). `/export` writes the result text verbatim.
413
+
414
+ **`dostuff -p`** asks on the terminal when both stdin and stderr are a TTY: each question and its numbered options
415
+ go to stderr, and it reads one line per question (`2`, `1,3`, or free text; an empty line is `(no answer)`). There
416
+ is no submit row, because a line reader has no way back. With piped stdin (or stderr redirected to a file) the tool
417
+ is still listed but answers "No user is available in this run", and the model states an assumption and carries on.
418
+
419
+ ---
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
+
351
466
  ## Subagents
352
467
 
353
468
  A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
@@ -638,7 +753,9 @@ nesting are the same. Tool names and some argument names differ, so rename the m
638
753
  | `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
639
754
  | `Read` | `read_file` | `file_path` → `path` |
640
755
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
756
+ | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
641
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`) |
642
759
 
643
760
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
644
761
  events.
@@ -1,7 +1,6 @@
1
- from dostuff.helpers.agent.loop_check_cancelled import is_cancelled, loop_check_cancelled
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
@@ -39,11 +39,15 @@ from dostuff.helpers.agent.tool_output import EMPTY_RESPONSE_NUDGE, format_call_
39
39
  TOOL_TIMEOUT_S = 120.0
40
40
  RETRY_BASE_DELAY_S = 1.0
41
41
  CANCELLED_RUNNING_RESULT = "Cancelled by user (may still be running)"
42
- CANCELLED_TURN = "Cancelled by user." # what loop() returns when the user cancelled
42
+ # CANCELLED_TURN (what loop() returns when the user cancelled) is imported from loop_check_cancelled
43
43
  MODEL_ERROR_PREFIX = "Model call failed: " # what loop() returns, + the error, when the model call failed
44
44
  # Tools exempt from TOOL_TIMEOUT_S: a subagent is bounded by its iteration cap, each of its own
45
- # tool calls has the normal timeout, and its approval prompts must not count against a deadline
46
- _UNTIMED_TOOLS = frozenset({"agent"})
45
+ # tool calls has the normal timeout, and its approval prompts must not count against a deadline;
46
+ # ask_user waits on a human who may think for minutes (ask-user spec D8)
47
+ _UNTIMED_TOOLS = frozenset({"agent", "ask_user"})
48
+ # Never dispatched side by side, whatever its kind (ask-user spec D8): a question opens a panel, and
49
+ # the transcript must not interleave a dialog with other results streaming in.
50
+ _NEVER_PARALLEL = frozenset({"ask_user"})
47
51
  _FORK_TOOLS = frozenset({"agent", "send_message"}) # get the fork_context harness param (subagents spec D11)
48
52
 
49
53
  _RETRYABLE_ERRORS: tuple[type[BaseException], ...] = (
@@ -134,6 +138,9 @@ def _call_label(call: _ToolCall) -> str:
134
138
 
135
139
 
136
140
  def _runs_in_parallel(name: str) -> bool:
141
+ """Read-only calls go in the parallel batch — except the ones that talk to the user (D8)."""
142
+ if name in _NEVER_PARALLEL:
143
+ return False
137
144
  spec = TOOL_MAP.get(name)
138
145
  return spec is not None and spec.kind == "read"
139
146
 
@@ -227,6 +234,7 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
227
234
  except Exception as e:
228
235
  await loop_emit("error", f"Could not save compaction: {e}", adapter=adapter)
229
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
230
238
  if session_hook_context is not None and turn_type == "interactive_loop": # a fork carries the main's
231
239
  # Earlier SessionStart context may be stale now; refresh it under its own key (REQ-2.4)
232
240
  await session_start("compact", session_hook_context, session_id=session_id, turn_id=turn_id,
@@ -258,7 +266,8 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
258
266
  if context_token_threshold is not None and last_input_tokens > context_token_threshold:
259
267
  await compact("Token threshold exceeded.", keep_recent_token_budget)
260
268
 
261
- 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"):
262
271
  turn_span.set_attribute("session_id", session_id)
263
272
  turn_span.set_attribute("turn_type", turn_type)
264
273
  turn_span.set_attribute("turn_id", turn_id)
@@ -281,6 +290,8 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
281
290
  await append_note(format_notices(notices, max_tool_output_chars))
282
291
  while inbox: # send_message to this running subagent, oldest first (D10)
283
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())
284
295
 
285
296
  # Model call with classified retries and exponential backoff
286
297
  interaction = None
@@ -292,13 +303,11 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
292
303
  progress = StreamProgress()
293
304
  try:
294
305
  # Read per call: the mode can change mid-turn (Shift+Tab)
295
- plan_mode = ((permissions.mode if permissions else None) or getattr(config, "permission_mode", "ask")) == "plan"
306
+ plan_mode = plan_mode_on(permissions, config)
296
307
  interaction, model_span = await call_agent(
297
308
  steps_history=working_history,
298
- system_instruction=dynamic_system_instruction
299
- + (f"\n\n{PLAN_MODE_INSTRUCTION}" if plan_mode else "")
300
- + (f"\n\n[Summary of earlier conversation]: {compaction_notes}" if compaction_notes else "")
301
- + session_context_suffix(session_hook_context),
309
+ system_instruction=compose_system_instruction(
310
+ dynamic_system_instruction, plan_mode, compaction_notes, session_hook_context),
302
311
  tool_names=tool_names,
303
312
  stream=stream,
304
313
  )
@@ -335,24 +344,12 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
335
344
  if interaction is None:
336
345
  return CANCELLED_TURN
337
346
 
338
- usage_dict = None
339
- usage = getattr(interaction, "usage", None)
347
+ usage_dict = build_usage_dict(interaction) # None when the response has no usage
340
348
  choices = getattr(interaction, "choices", None)
341
349
  message = choices[0].message if choices else None
342
350
  tool_calls = getattr(message, "tool_calls", None) if message else None
343
351
  content = getattr(message, "content", None) if message else None
344
352
 
345
- if usage:
346
- usage_dict = {
347
- "prompt_tokens": getattr(usage, "prompt_tokens", 0) or 0,
348
- "completion_tokens": getattr(usage, "completion_tokens", 0) or 0,
349
- "total_tokens": getattr(usage, "total_tokens", 0) or 0,
350
- # Prompt tokens read from the provider's prompt cache (0 if none / unsupported)
351
- "cached_tokens": getattr(getattr(usage, "prompt_tokens_details", None), "cached_tokens", 0) or 0,
352
- }
353
- # USD from litellm's price table; None if unknown (the TUI then hides the cost)
354
- usage_dict["cost"] = call_cost(get_litellm_model(), usage_dict)
355
-
356
353
  # close model_span exactly once, here, before any continue/return below
357
354
  if model_span is not None and model_span.is_recording():
358
355
  if usage_dict:
@@ -498,9 +495,12 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
498
495
  call.result = f"Error: {exc}"
499
496
  else:
500
497
  call.result = str(task.result())
501
- if not was_cancelled:
498
+ if not task.cancelled():
502
499
  # PostToolUse runs here, after the dispatch task and outside TOOL_TIMEOUT_S, so the
503
- # parallel read-only batch stays intact and its context reaches the tool step (D5)
500
+ # parallel read-only batch stays intact and its context reaches the tool step (D5).
501
+ # A call that returned on its own still fires it in a cancelled batch: Esc on an
502
+ # `ask_user` resolves the question, so the tool returns the cancel text rather
503
+ # than being cancelled (ask-user D7 — the hook sees that text).
504
504
  call.result, _ = await post_tool_use(call.name, call.args, call.result, tool_use_id=call.id, **hook_ids)
505
505
  await loop_emit("tool_result", f"{call.name}: {call.result}", adapter=adapter)
506
506
  return was_cancelled
@@ -512,7 +512,10 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
512
512
  if parallel:
513
513
  cancelled = await run_batch(parallel)
514
514
  for call in (c for c in runnable if not _runs_in_parallel(c.name)):
515
- if cancelled:
515
+ # The cancel flag can be set by the batch just finished (Esc on an ask_user):
516
+ # don't schedule a call that would only be cancelled before it starts
517
+ if cancelled or is_cancelled(adapter):
518
+ cancelled = True
516
519
  break
517
520
  cancelled = await run_batch([call])
518
521
 
@@ -40,7 +40,8 @@ MODE_CYCLE: tuple[str, ...] = ("ask", "auto", "plan", "allowlist")
40
40
  PLAN_MODE_INSTRUCTION = (
41
41
  "## Plan mode\nPlan mode is on: you can read files, search and run read-only commands, but file "
42
42
  "changes, other shell commands and settings changes are denied. Investigate, then reply with a "
43
- "concrete step-by-step plan. Don't make the changes until the user leaves plan mode (Shift+Tab or /permissions)."
43
+ "concrete step-by-step plan. In plan mode, ask what you need *before* writing the plan, with "
44
+ "`ask_user` — not after. Don't make the changes until the user leaves plan mode (Shift+Tab or /permissions)."
44
45
  )
45
46
 
46
47
 
@@ -24,6 +24,8 @@ RESTRICTED_SUBAGENT_TOOLS = frozenset({
24
24
  "save_episode",
25
25
  # The todo list belongs to the parent; a subagent would overwrite it
26
26
  "todo_write",
27
+ # The question channel is the main agent's: it holds the conversation with the user (ask-user D11)
28
+ "ask_user",
27
29
  # Settings are the user's to change, from the main conversation
28
30
  "read_settings",
29
31
  "edit_config",
@@ -74,6 +74,8 @@ CLAUDE_TOOL_NAMES: dict[str, tuple[str, ...]] = {
74
74
  "Bash": ("bash_command",),
75
75
  "WebFetch": ("web_fetch",),
76
76
  "WebSearch": ("web_search",),
77
+ # Known so an agent file that lists it gets the restricted-tool warning, not "unknown" (ask-user D10)
78
+ "AskUserQuestion": ("ask_user",),
77
79
  }
78
80
  MCP_TOOLS = ("search_mcp_tools", "get_mcp_tool_details", "call_mcp_tool")
79
81
 
@@ -117,11 +119,15 @@ def map_tools(raw: Any, source: str) -> tuple[tuple[str, ...], list[str]]:
117
119
  targets: tuple[str, ...] = MCP_TOOLS
118
120
  elif name in CLAUDE_TOOL_NAMES:
119
121
  targets = CLAUDE_TOOL_NAMES[name]
120
- elif name in BUILTIN_TOOL_NAMES and name not in RESTRICTED_SUBAGENT_TOOLS:
122
+ elif name in BUILTIN_TOOL_NAMES:
121
123
  targets = (name,)
122
124
  else:
123
- why = "not available to subagents" if name in RESTRICTED_SUBAGENT_TOOLS else "unknown tool"
124
- warnings.append(f"{source}: tool '{name}' dropped ({why})")
125
+ warnings.append(f"{source}: tool '{name}' dropped (unknown tool)")
126
+ continue
127
+ # Checked after the alias lookup as well as before it: AskUserQuestion → ask_user must not slip
128
+ # past the restriction by arriving under Claude Code's name (ask-user D10/D11)
129
+ if any(t in RESTRICTED_SUBAGENT_TOOLS for t in targets):
130
+ warnings.append(f"{source}: tool '{name}' dropped (not available to subagents)")
125
131
  continue
126
132
  mapped.extend(t for t in targets if t not in mapped)
127
133
  return tuple(mapped), warnings