dostuff 0.2.6__tar.gz → 0.2.8__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 (164) hide show
  1. {dostuff-0.2.6 → dostuff-0.2.8}/PKG-INFO +70 -1
  2. {dostuff-0.2.6 → dostuff-0.2.8}/README.md +69 -0
  3. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/loop.py +20 -7
  4. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/permissions.py +10 -4
  5. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/subagents/__init__.py +2 -0
  6. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/subagents/definitions.py +9 -3
  7. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/cli_tui.py +702 -59
  8. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/headless.py +40 -0
  9. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/constants.py +10 -0
  10. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/loop_check_cancelled.py +5 -0
  11. dostuff-0.2.8/dostuff/helpers/agent/tool_output.py +83 -0
  12. dostuff-0.2.8/dostuff/helpers/ui/ask_answers.py +90 -0
  13. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/ui/tools_listing.py +1 -0
  14. dostuff-0.2.8/dostuff/tools/ask_user.py +184 -0
  15. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/definitions.py +4 -0
  16. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/names.py +1 -0
  17. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff.egg-info/PKG-INFO +70 -1
  18. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff.egg-info/SOURCES.txt +3 -0
  19. {dostuff-0.2.6 → dostuff-0.2.8}/pyproject.toml +1 -1
  20. dostuff-0.2.8/tests/test_ask_user.py +586 -0
  21. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_cli_commands.py +187 -0
  22. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_loop.py +182 -0
  23. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_permissions.py +44 -0
  24. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_subagents_types.py +22 -0
  25. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_tool_schemas.py +16 -0
  26. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_tools_listing.py +10 -0
  27. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_tui.py +1493 -2
  28. dostuff-0.2.6/dostuff/helpers/agent/tool_output.py +0 -44
  29. {dostuff-0.2.6 → dostuff-0.2.8}/LICENSE +0 -0
  30. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/__init__.py +0 -0
  31. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/__main__.py +0 -0
  32. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/call_agent.py +0 -0
  33. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/instructions.py +0 -0
  34. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/run_tool.py +0 -0
  35. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/subagents/adapter.py +0 -0
  36. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/subagents/fork.py +0 -0
  37. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/subagents/prompt.py +0 -0
  38. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/subagents/registry.py +0 -0
  39. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/agent/subagents/run.py +0 -0
  40. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/cli.py +0 -0
  41. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/config.py +0 -0
  42. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/append_step.py +0 -0
  43. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/consume_stream.py +0 -0
  44. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/context_usage.py +0 -0
  45. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/environment_context.py +0 -0
  46. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/file_mentions.py +0 -0
  47. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  48. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/load_identity.py +0 -0
  49. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  50. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/loop_emit.py +0 -0
  51. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/manage_context.py +0 -0
  52. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/model_cost.py +0 -0
  53. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/notices.py +0 -0
  54. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/pastes.py +0 -0
  55. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/quick_memory.py +0 -0
  56. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  57. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/hooks/__init__.py +0 -0
  58. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/hooks/dispatch.py +0 -0
  59. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/hooks/events.py +0 -0
  60. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/hooks/load_hooks.py +0 -0
  61. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/hooks/run_hook.py +0 -0
  62. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/hooks/trust.py +0 -0
  63. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  64. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  65. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/mcp/server_config.py +0 -0
  66. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/mcp/token_store.py +0 -0
  67. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/memory/export_session.py +0 -0
  68. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  69. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/memory/shell_step.py +0 -0
  70. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/models/add_model_entry.py +0 -0
  71. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/models/list_models.py +0 -0
  72. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/models/opencode.py +0 -0
  73. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/skills/custom_commands.py +0 -0
  74. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/skills/discover_skills.py +0 -0
  75. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/skills/skill_command.py +0 -0
  76. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/tools/diff.py +0 -0
  77. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  78. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/tools/project_root.py +0 -0
  79. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  80. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/ui/__init__.py +0 -0
  81. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/ui/doctor.py +0 -0
  82. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/ui/emit.py +0 -0
  83. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/ui/prompt_history.py +0 -0
  84. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/helpers/ui/terminal_signals.py +0 -0
  85. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/checkpoints.py +0 -0
  86. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/exceptions.py +0 -0
  87. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/mcp/mcp_client.py +0 -0
  88. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  89. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  90. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/memory/chroma.py +0 -0
  91. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  92. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  93. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/memory/session_store.py +0 -0
  94. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/memory/stores.py +0 -0
  95. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/memory/types.py +0 -0
  96. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/model.py +0 -0
  97. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/tracing.py +0 -0
  98. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/lib/worktree.py +0 -0
  99. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/memory/__init__.py +0 -0
  100. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/setup_wizard.py +0 -0
  101. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/skills.py +0 -0
  102. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/templates/config.example.yaml +0 -0
  103. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/templates/env.example +0 -0
  104. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/__init__.py +0 -0
  105. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/agent.py +0 -0
  106. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/bash/bash_command.py +0 -0
  107. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/bash/bash_output.py +0 -0
  108. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/bash/jobs.py +0 -0
  109. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/bash/kill_shell.py +0 -0
  110. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/create_agent_type.py +0 -0
  111. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/files/delete_file.py +0 -0
  112. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/files/edit_file.py +0 -0
  113. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/files/list_files.py +0 -0
  114. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/files/read_file.py +0 -0
  115. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/files/write_file.py +0 -0
  116. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/get_current_datetime.py +0 -0
  117. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  118. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  119. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  120. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/memory/save_episode.py +0 -0
  121. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/memory/save_memory.py +0 -0
  122. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/search/glob.py +0 -0
  123. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/search/grep.py +0 -0
  124. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/search/walk.py +0 -0
  125. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/send_message.py +0 -0
  126. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/settings.py +0 -0
  127. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/stop_agent.py +0 -0
  128. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/todo_write.py +0 -0
  129. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/web_fetch.py +0 -0
  130. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff/tools/web_search.py +0 -0
  131. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff.egg-info/dependency_links.txt +0 -0
  132. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff.egg-info/entry_points.txt +0 -0
  133. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff.egg-info/requires.txt +0 -0
  134. {dostuff-0.2.6 → dostuff-0.2.8}/dostuff.egg-info/top_level.txt +0 -0
  135. {dostuff-0.2.6 → dostuff-0.2.8}/setup.cfg +0 -0
  136. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_bash_command.py +0 -0
  137. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_checkpoints_todos_caching.py +0 -0
  138. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_config_memory_mcp.py +0 -0
  139. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_create_agent_type.py +0 -0
  140. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_file_mentions.py +0 -0
  141. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_file_tools.py +0 -0
  142. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_hooks.py +0 -0
  143. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_jobs.py +0 -0
  144. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_mcp_e2e.py +0 -0
  145. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_mcp_oauth.py +0 -0
  146. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_opencode.py +0 -0
  147. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_optional_memory_and_instructions.py +0 -0
  148. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_pastes.py +0 -0
  149. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_roadmap_021.py +0 -0
  150. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_session_store.py +0 -0
  151. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_settings_tools.py +0 -0
  152. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_setup_wizard.py +0 -0
  153. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_skill_command.py +0 -0
  154. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_skills_discovery.py +0 -0
  155. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_slash_suggestion.py +0 -0
  156. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_subagent.py +0 -0
  157. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_subagents_background.py +0 -0
  158. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_subagents_fork.py +0 -0
  159. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_subagents_run.py +0 -0
  160. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_subagents_store.py +0 -0
  161. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_terminal_signals.py +0 -0
  162. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_web_fetch.py +0 -0
  163. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_web_search.py +0 -0
  164. {dostuff-0.2.6 → dostuff-0.2.8}/tests/test_worktree.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dostuff
3
- Version: 0.2.6
3
+ Version: 0.2.8
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,7 @@ 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)
86
87
  - **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
88
  - **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
89
  - **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)
@@ -295,6 +296,7 @@ In the TUI:
295
296
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
296
297
  | `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
298
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
299
+ | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
298
300
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
299
301
  | `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
302
 
@@ -396,6 +398,72 @@ paths). Directories older than 7 days are removed at startup.
396
398
 
397
399
  ---
398
400
 
401
+ ## Asking the user
402
+
403
+ `ask_user` lets the agent stop and ask instead of guessing: a library to use, a product decision, a name. It is
404
+ the one tool that talks to you, it never needs approval, and subagents never get it (they report back instead).
405
+
406
+ The questions arrive as a panel in place of the input:
407
+
408
+ ```
409
+ ✓ DB · ▌ Auth · Name
410
+ Which auth methods should the API support?
411
+ ❯ 1. JWT stateless, no extra service
412
+ 2. OAuth a provider to configure
413
+ 3. Other (type your own)
414
+ ────────────────────────────────────────────────────────
415
+ Submit answers (answer every question first)
416
+ ↑/↓ select · Enter confirm · ←/→ change question · Esc cancel
417
+ ```
418
+
419
+ The top line is the tab strip: `▌` marks the question you are on (bold and orange), `✓` marks one you have
420
+ answered, and both sit in the same slot so the tabs never shift as you answer. The submit row is dim until
421
+ every question has an answer, then it brightens and the parenthetical hint goes away.
422
+
423
+ - **Nothing submits on one key.** A pick records the answer and moves to the next question; `Submit answers` is
424
+ the only thing that sends, and it stays inert (`answer every question first`) until every question has one.
425
+ `←`/`Shift+Tab` goes back, so an earlier answer can be changed before submitting.
426
+ - **`2-4` options, one line each**, with the trade-off where it matters. A multi-select question toggles with
427
+ `space` or its number, and the joined answer comes back in option order.
428
+ - **`Other`** is always the last row, numbered after the options: pick it and the input takes a typed answer (a
429
+ pasted block is collapsed to one line). A question with no options shows as just that row, so it still appears
430
+ in the tab strip; **Enter** (or `o`) on it takes the input, and `←`/`Tab` still move between questions — so
431
+ landing on a free-text question never traps you in the input. A call where *every* question is free text skips
432
+ the panel entirely and the input takes each answer in turn, with the last Enter as the submission.
433
+ - **Esc** cancels the questions and ends the turn, like Esc on an approval prompt. **Ctrl+Q** / `/exit` with a
434
+ question open cancel it first and then quit.
435
+ - Up to 4 questions per call. The prompt tells the model when to ask: when the answer changes what it builds and
436
+ the repo can't tell it; never to confirm a plan, to ask permission, or for anything `grep` / `read_file` answers.
437
+
438
+ The answers reach the model as one tool result, and the transcript shows the same pairs as one block — live and
439
+ after `/resume`:
440
+
441
+ ```
442
+ ⎿ Which database should I use? → Postgres
443
+ Which auth methods should the API support? → JWT, OAuth
444
+ ```
445
+
446
+ Nothing is truncated and Ctrl+O has nothing to expand, unlike an ordinary tool result: reading back what you
447
+ answered is the point. What the model actually receives is `format_answers`' output:
448
+
449
+ ```text
450
+ Asked the user 2 questions; they answered:
451
+ 1. Which database should I use?
452
+ → Postgres
453
+ 2. Which auth methods should the API support?
454
+ → JWT, OAuth
455
+ ```
456
+
457
+ A cancelled, refused or unavailable call renders as an ordinary tool result, with the model told what to do
458
+ (state the assumption and continue). `/export` writes the result text verbatim.
459
+
460
+ **`dostuff -p`** asks on the terminal when both stdin and stderr are a TTY: each question and its numbered options
461
+ go to stderr, and it reads one line per question (`2`, `1,3`, or free text; an empty line is `(no answer)`). There
462
+ is no submit row, because a line reader has no way back. With piped stdin (or stderr redirected to a file) the tool
463
+ is still listed but answers "No user is available in this run", and the model states an assumption and carries on.
464
+
465
+ ---
466
+
399
467
  ## Subagents
400
468
 
401
469
  A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
@@ -686,6 +754,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
686
754
  | `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
687
755
  | `Read` | `read_file` | `file_path` → `path` |
688
756
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
757
+ | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
689
758
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
690
759
 
691
760
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
@@ -35,6 +35,7 @@ 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)
38
39
  - **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
40
  - **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
41
  - **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)
@@ -247,6 +248,7 @@ In the TUI:
247
248
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
248
249
  | `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
250
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
251
+ | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
250
252
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
251
253
  | `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
254
 
@@ -348,6 +350,72 @@ paths). Directories older than 7 days are removed at startup.
348
350
 
349
351
  ---
350
352
 
353
+ ## Asking the user
354
+
355
+ `ask_user` lets the agent stop and ask instead of guessing: a library to use, a product decision, a name. It is
356
+ the one tool that talks to you, it never needs approval, and subagents never get it (they report back instead).
357
+
358
+ The questions arrive as a panel in place of the input:
359
+
360
+ ```
361
+ ✓ DB · ▌ Auth · Name
362
+ Which auth methods should the API support?
363
+ ❯ 1. JWT stateless, no extra service
364
+ 2. OAuth a provider to configure
365
+ 3. Other (type your own)
366
+ ────────────────────────────────────────────────────────
367
+ Submit answers (answer every question first)
368
+ ↑/↓ select · Enter confirm · ←/→ change question · Esc cancel
369
+ ```
370
+
371
+ The top line is the tab strip: `▌` marks the question you are on (bold and orange), `✓` marks one you have
372
+ answered, and both sit in the same slot so the tabs never shift as you answer. The submit row is dim until
373
+ every question has an answer, then it brightens and the parenthetical hint goes away.
374
+
375
+ - **Nothing submits on one key.** A pick records the answer and moves to the next question; `Submit answers` is
376
+ the only thing that sends, and it stays inert (`answer every question first`) until every question has one.
377
+ `←`/`Shift+Tab` goes back, so an earlier answer can be changed before submitting.
378
+ - **`2-4` options, one line each**, with the trade-off where it matters. A multi-select question toggles with
379
+ `space` or its number, and the joined answer comes back in option order.
380
+ - **`Other`** is always the last row, numbered after the options: pick it and the input takes a typed answer (a
381
+ pasted block is collapsed to one line). A question with no options shows as just that row, so it still appears
382
+ in the tab strip; **Enter** (or `o`) on it takes the input, and `←`/`Tab` still move between questions — so
383
+ landing on a free-text question never traps you in the input. A call where *every* question is free text skips
384
+ the panel entirely and the input takes each answer in turn, with the last Enter as the submission.
385
+ - **Esc** cancels the questions and ends the turn, like Esc on an approval prompt. **Ctrl+Q** / `/exit` with a
386
+ question open cancel it first and then quit.
387
+ - Up to 4 questions per call. The prompt tells the model when to ask: when the answer changes what it builds and
388
+ the repo can't tell it; never to confirm a plan, to ask permission, or for anything `grep` / `read_file` answers.
389
+
390
+ The answers reach the model as one tool result, and the transcript shows the same pairs as one block — live and
391
+ after `/resume`:
392
+
393
+ ```
394
+ ⎿ Which database should I use? → Postgres
395
+ Which auth methods should the API support? → JWT, OAuth
396
+ ```
397
+
398
+ Nothing is truncated and Ctrl+O has nothing to expand, unlike an ordinary tool result: reading back what you
399
+ answered is the point. What the model actually receives is `format_answers`' output:
400
+
401
+ ```text
402
+ Asked the user 2 questions; they answered:
403
+ 1. Which database should I use?
404
+ → Postgres
405
+ 2. Which auth methods should the API support?
406
+ → JWT, OAuth
407
+ ```
408
+
409
+ A cancelled, refused or unavailable call renders as an ordinary tool result, with the model told what to do
410
+ (state the assumption and continue). `/export` writes the result text verbatim.
411
+
412
+ **`dostuff -p`** asks on the terminal when both stdin and stderr are a TTY: each question and its numbered options
413
+ go to stderr, and it reads one line per question (`2`, `1,3`, or free text; an empty line is `(no answer)`). There
414
+ is no submit row, because a line reader has no way back. With piped stdin (or stderr redirected to a file) the tool
415
+ is still listed but answers "No user is available in this run", and the model states an assumption and carries on.
416
+
417
+ ---
418
+
351
419
  ## Subagents
352
420
 
353
421
  A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
@@ -638,6 +706,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
638
706
  | `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
639
707
  | `Read` | `read_file` | `file_path` → `path` |
640
708
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
709
+ | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
641
710
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
642
711
 
643
712
  Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
@@ -1,4 +1,4 @@
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
3
  from dostuff.helpers.agent.model_cost import call_cost
4
4
  from dostuff.lib.model import current_session_id, get_litellm_model
@@ -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
 
@@ -498,9 +505,12 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
498
505
  call.result = f"Error: {exc}"
499
506
  else:
500
507
  call.result = str(task.result())
501
- if not was_cancelled:
508
+ if not task.cancelled():
502
509
  # 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)
510
+ # parallel read-only batch stays intact and its context reaches the tool step (D5).
511
+ # A call that returned on its own still fires it in a cancelled batch: Esc on an
512
+ # `ask_user` resolves the question, so the tool returns the cancel text rather
513
+ # than being cancelled (ask-user D7 — the hook sees that text).
504
514
  call.result, _ = await post_tool_use(call.name, call.args, call.result, tool_use_id=call.id, **hook_ids)
505
515
  await loop_emit("tool_result", f"{call.name}: {call.result}", adapter=adapter)
506
516
  return was_cancelled
@@ -512,7 +522,10 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
512
522
  if parallel:
513
523
  cancelled = await run_batch(parallel)
514
524
  for call in (c for c in runnable if not _runs_in_parallel(c.name)):
515
- if cancelled:
525
+ # The cancel flag can be set by the batch just finished (Esc on an ask_user):
526
+ # don't schedule a call that would only be cancelled before it starts
527
+ if cancelled or is_cancelled(adapter):
528
+ cancelled = True
516
529
  break
517
530
  cancelled = await run_batch([call])
518
531
 
@@ -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
 
@@ -73,8 +74,11 @@ _GIT_SAFE_ARGS: dict[str, set[str]] = {
73
74
  # `env` / `printenv` are intentionally absent: they dump secrets into the transcript.
74
75
 
75
76
  _FORBIDDEN_SUBSTRINGS = (
76
- ">", "<", "`", "$(", "${", "out-file", "set-content", "add-content", "env:", ".env", ".dostuff",
77
+ ">", "<", "`", "$(", "${", "out-file", "set-content", "add-content", "env:", ".env",
77
78
  )
79
+ # A `.dostuff` path (`.dostuff/config.yaml`, `~/.dostuff`, cwd=".dostuff"), not a dotted attribute such
80
+ # as `cli_tui.DostuffTUI` — that is ordinary code, and treating it as one denied reads in plan mode.
81
+ _DOSTUFF_REF = re.compile(r"(?<![\w-])\.dostuff(?![\w-])", re.IGNORECASE)
78
82
  # Flags that make otherwise read-only commands write, delete or execute (find -exec, rg --pre, git --output …).
79
83
  _FORBIDDEN_FLAGS = re.compile(
80
84
  r"(?<![\w-])(-delete|-exec\w*|-ok\w*|-fprint\w*|-fls|--output|--pre)(?![\w-])",
@@ -141,6 +145,7 @@ def has_unsafe_constructs(command: str) -> bool:
141
145
  lowered = _WORKTREES_PREFIX.sub("", lowered)
142
146
  return (
143
147
  any(s in lowered for s in _FORBIDDEN_SUBSTRINGS)
148
+ or bool(_DOSTUFF_REF.search(lowered))
144
149
  or bool(_FORBIDDEN_FLAGS.search(command))
145
150
  or bool(_ENV_EXPANSION.search(command))
146
151
  )
@@ -268,11 +273,11 @@ def _plan_denies(kind: ToolKind, args: dict[str, Any]) -> bool:
268
273
 
269
274
 
270
275
  def _mentions_dostuff_dir(text: str) -> bool:
271
- """`.dostuff` named in a shell command or cwd, other than a path into a subagent worktree."""
276
+ """`.dostuff` named as a path in a shell command or cwd, other than a path into a subagent worktree."""
272
277
  lowered = text.lower()
273
278
  if ".." not in lowered: # same worktree exemption as has_unsafe_constructs
274
279
  lowered = _WORKTREES_PREFIX.sub("", lowered)
275
- return ".dostuff" in lowered
280
+ return bool(_DOSTUFF_REF.search(lowered))
276
281
 
277
282
 
278
283
  def effective_kind(kind: ToolKind, args: dict[str, Any]) -> ToolKind:
@@ -280,6 +285,7 @@ def effective_kind(kind: ToolKind, args: dict[str, Any]) -> ToolKind:
280
285
 
281
286
  So does a shell command naming `.dostuff` (in `command` or `cwd`): otherwise auto mode would let
282
287
  `echo … >> ~/.dostuff/config.yaml` add a user hook, which no trust check covers, without a prompt.
288
+ Only a `.dostuff` path counts — `cli_tui.DostuffTUI` is a dotted attribute, not a settings path.
283
289
  A heuristic: a name built indirectly (`.dost''uff`, a variable holding it) is not caught here.
284
290
  """
285
291
  if kind == "write" and _is_settings_path(str(args.get("path") or "")):
@@ -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