dostuff 0.2.11__tar.gz → 0.2.12__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 (177) hide show
  1. {dostuff-0.2.11 → dostuff-0.2.12}/PKG-INFO +66 -24
  2. {dostuff-0.2.11 → dostuff-0.2.12}/README.md +65 -23
  3. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/instructions.py +3 -2
  4. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/permissions.py +209 -23
  5. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/run_tool.py +19 -5
  6. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/subagents/definitions.py +2 -2
  7. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/cli.py +11 -4
  8. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/cli_tui.py +109 -17
  9. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/headless.py +9 -2
  10. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/constants.py +7 -4
  11. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/file_mentions.py +6 -2
  12. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/slash_suggestion.py +9 -0
  13. dostuff-0.2.12/dostuff/helpers/config_secrets.py +41 -0
  14. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/hooks/dispatch.py +9 -1
  15. dostuff-0.2.12/dostuff/helpers/mcp/server_config.py +68 -0
  16. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/skills/discover_skills.py +22 -7
  17. dostuff-0.2.12/dostuff/helpers/skills/skill_command.py +96 -0
  18. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/tools/resolve_safe_path.py +25 -12
  19. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/ui/doctor.py +19 -1
  20. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/ui/tools_listing.py +1 -1
  21. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/checkpoints.py +2 -2
  22. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/mcp/mcp_client.py +8 -3
  23. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/templates/config.example.yaml +2 -2
  24. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/create_agent_type.py +1 -1
  25. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/definitions.py +5 -2
  26. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/files/edit_file.py +33 -17
  27. dostuff-0.2.12/dostuff/tools/files/multi_edit.py +77 -0
  28. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/names.py +1 -1
  29. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/settings.py +44 -10
  30. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff.egg-info/PKG-INFO +66 -24
  31. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff.egg-info/SOURCES.txt +3 -0
  32. {dostuff-0.2.11 → dostuff-0.2.12}/pyproject.toml +1 -1
  33. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_checkpoints_todos_caching.py +11 -0
  34. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_cli_commands.py +53 -0
  35. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_create_agent_type.py +2 -1
  36. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_file_tools.py +157 -1
  37. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_hooks.py +72 -1
  38. dostuff-0.2.12/tests/test_mcp_env_references.py +177 -0
  39. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_optional_memory_and_instructions.py +26 -2
  40. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_permissions.py +348 -19
  41. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_settings_tools.py +61 -5
  42. dostuff-0.2.12/tests/test_skill_command.py +138 -0
  43. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_skills_discovery.py +57 -0
  44. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_slash_suggestion.py +11 -1
  45. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_subagents_run.py +14 -0
  46. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_subagents_types.py +15 -1
  47. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_tui.py +693 -0
  48. dostuff-0.2.11/dostuff/helpers/mcp/server_config.py +0 -36
  49. dostuff-0.2.11/dostuff/helpers/skills/skill_command.py +0 -48
  50. dostuff-0.2.11/tests/test_skill_command.py +0 -37
  51. {dostuff-0.2.11 → dostuff-0.2.12}/LICENSE +0 -0
  52. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/__init__.py +0 -0
  53. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/__main__.py +0 -0
  54. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/call_agent.py +0 -0
  55. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/loop.py +0 -0
  56. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/subagents/__init__.py +0 -0
  57. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/subagents/adapter.py +0 -0
  58. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/subagents/fork.py +0 -0
  59. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/subagents/prompt.py +0 -0
  60. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/subagents/registry.py +0 -0
  61. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/agent/subagents/run.py +0 -0
  62. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/config.py +0 -0
  63. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/append_step.py +0 -0
  64. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/consume_stream.py +0 -0
  65. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/context_usage.py +0 -0
  66. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/environment_context.py +0 -0
  67. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  68. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/load_identity.py +0 -0
  69. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  70. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  71. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/loop_emit.py +0 -0
  72. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/manage_context.py +0 -0
  73. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/model_cost.py +0 -0
  74. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/notices.py +0 -0
  75. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/pastes.py +0 -0
  76. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/quick_memory.py +0 -0
  77. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/side_question.py +0 -0
  78. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/steering.py +0 -0
  79. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/tool_output.py +0 -0
  80. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/agent/turn_context.py +0 -0
  81. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/hooks/__init__.py +0 -0
  82. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/hooks/events.py +0 -0
  83. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/hooks/load_hooks.py +0 -0
  84. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/hooks/run_hook.py +0 -0
  85. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/hooks/trust.py +0 -0
  86. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  87. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  88. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/mcp/token_store.py +0 -0
  89. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/memory/export_session.py +0 -0
  90. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  91. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/memory/shell_step.py +0 -0
  92. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/models/add_model_entry.py +0 -0
  93. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/models/list_models.py +0 -0
  94. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/models/opencode.py +0 -0
  95. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/skills/custom_commands.py +0 -0
  96. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/tools/diff.py +0 -0
  97. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  98. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/tools/project_root.py +0 -0
  99. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/ui/__init__.py +0 -0
  100. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/ui/ask_answers.py +0 -0
  101. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/ui/emit.py +0 -0
  102. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/ui/prompt_history.py +0 -0
  103. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/helpers/ui/terminal_signals.py +0 -0
  104. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/exceptions.py +0 -0
  105. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  106. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  107. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/memory/chroma.py +0 -0
  108. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  109. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  110. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/memory/session_store.py +0 -0
  111. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/memory/stores.py +0 -0
  112. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/memory/types.py +0 -0
  113. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/model.py +0 -0
  114. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/tracing.py +0 -0
  115. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/lib/worktree.py +0 -0
  116. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/memory/__init__.py +0 -0
  117. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/setup_wizard.py +0 -0
  118. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/skills.py +0 -0
  119. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/templates/env.example +0 -0
  120. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/__init__.py +0 -0
  121. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/agent.py +0 -0
  122. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/ask_user.py +0 -0
  123. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/bash/bash_command.py +0 -0
  124. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/bash/bash_output.py +0 -0
  125. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/bash/jobs.py +0 -0
  126. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/bash/kill_shell.py +0 -0
  127. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/files/delete_file.py +0 -0
  128. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/files/list_files.py +0 -0
  129. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/files/read_file.py +0 -0
  130. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/files/write_file.py +0 -0
  131. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/get_current_datetime.py +0 -0
  132. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  133. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  134. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  135. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/memory/save_episode.py +0 -0
  136. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/memory/save_memory.py +0 -0
  137. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/search/glob.py +0 -0
  138. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/search/grep.py +0 -0
  139. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/search/walk.py +0 -0
  140. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/send_message.py +0 -0
  141. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/stop_agent.py +0 -0
  142. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/todo_write.py +0 -0
  143. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/web_fetch.py +0 -0
  144. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff/tools/web_search.py +0 -0
  145. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff.egg-info/dependency_links.txt +0 -0
  146. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff.egg-info/entry_points.txt +0 -0
  147. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff.egg-info/requires.txt +0 -0
  148. {dostuff-0.2.11 → dostuff-0.2.12}/dostuff.egg-info/top_level.txt +0 -0
  149. {dostuff-0.2.11 → dostuff-0.2.12}/setup.cfg +0 -0
  150. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_ask_user.py +0 -0
  151. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_bash_command.py +0 -0
  152. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_config_memory_mcp.py +0 -0
  153. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_export_session.py +0 -0
  154. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_file_mentions.py +0 -0
  155. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_jobs.py +0 -0
  156. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_loop.py +0 -0
  157. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_mcp_e2e.py +0 -0
  158. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_mcp_oauth.py +0 -0
  159. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_opencode.py +0 -0
  160. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_pastes.py +0 -0
  161. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_roadmap_021.py +0 -0
  162. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_session_store.py +0 -0
  163. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_setup_wizard.py +0 -0
  164. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_side_question.py +0 -0
  165. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_side_question_litellm.py +0 -0
  166. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_steering.py +0 -0
  167. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_subagent.py +0 -0
  168. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_subagents_background.py +0 -0
  169. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_subagents_fork.py +0 -0
  170. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_subagents_store.py +0 -0
  171. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_terminal_signals.py +0 -0
  172. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_tool_schemas.py +0 -0
  173. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_tools_listing.py +0 -0
  174. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_turn_context.py +0 -0
  175. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_web_fetch.py +0 -0
  176. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_web_search.py +0 -0
  177. {dostuff-0.2.11 → dostuff-0.2.12}/tests/test_worktree.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dostuff
3
- Version: 0.2.11
3
+ Version: 0.2.12
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
@@ -82,15 +82,15 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
82
82
  - **MCP server support** — stdio (npx, uvx) and HTTP transports
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
- - **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)
85
+ - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `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
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
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)
89
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
90
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)
91
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)
92
- - **File sandbox** — file tools stay inside the project directory, plus read-only access to discovered skill folders, and never read `.env*` files or the rest of `~/.dostuff/`
93
- - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
92
+ - **File sandbox** — file tools stay inside the project directory, plus read-only access to `.dostuff` (the project's and `~/.dostuff/`) and to discovered skill folders; `.env*` files, `mcp_config.json` and `.dostuff/data` (past sessions and prompts, saved MCP client secrets) are never readable
93
+ - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`, name one mid-message to allow it for that message, or keep one manual-only with `disable-model-invocation`. See [Skills](#skills)
94
94
  - **Subagents** — the `agent` tool starts agents in parallel, in the foreground or the background, from built-in types (`explore`, `plan`, `general-purpose`), your own Markdown agent files (Claude Code's `.claude/agents/` work too) or a `fork` of the conversation; continue one with `send_message`, stop it with `stop_agent`, see them all in `/agents`. See [Subagents](#subagents)
95
95
  - **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
96
96
  - **Retries with backoff** for rate limits, timeouts and 5xx errors (6 by default, exponential with jitter, honors `Retry-After`; `loop.max_retries` / `loop.retry_max_delay`); auth / bad-request errors fail fast
@@ -258,6 +258,7 @@ In the TUI:
258
258
  | `/queue` / `/queue clear` | List the prompts waiting for the current turn: edit one (back into the input), run it next or remove it / drop them all |
259
259
  | `/jobs [<id>]` / `/jobs kill <id>` | List this session's background jobs (id, owner, status, runtime, command) / show a job's last 40 lines of output and its log files / stop one (the agent is told). See [Background jobs](#background-jobs) |
260
260
  | `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
261
+ | `… /<skill> …` | Mid-message, makes that skill available for this message; the `/` menu offers skills as you type. See [Skills](#skills) |
261
262
  | `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
262
263
  | `/rename <title>` | Name this session (shown by `dostuff sessions`) |
263
264
  | `/export [<path>]` | Save this session as Markdown (default `dostuff-session-<id>.md`) |
@@ -276,7 +277,7 @@ In the TUI:
276
277
  - **Sticky prompt** — once a prompt or `!command` scrolls off the top, it stays pinned there on one row while you are in its turn, as the answer streams or when you scroll back through an old one, until the next prompt reaches the top. Click it to go back to the start of the turn; `↓ Jump to bottom` returns you to the latest message
277
278
  - **Approvals** — a selector (arrows, a number, or `y` = allow once, `a` = always this session, `n` = deny with an optional note); several calls in one response can be approved together
278
279
  - **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
279
- - **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
280
+ - **Diffs** — `write_file` / `edit_file` / `multi_edit` changes shown as a coloured diff
280
281
  - **Errors** — red background
281
282
  - **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
282
283
  - **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
@@ -296,7 +297,7 @@ In the TUI:
296
297
  | ---- | ---- | ----- |
297
298
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
298
299
  | `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
299
- | `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
300
+ | `write_file`, `edit_file`, `multi_edit`, `delete_file` | write | yes (shows a diff; `multi_edit` shows one diff for all its edits) |
300
301
  | `bash_command` | shell | yes, unless every part of the command is on the read-only allow-list (`ls`, `cat`, `git status`, `git diff`, …) with no redirection or substitution |
301
302
  | `call_mcp_tool` | mcp | yes |
302
303
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
@@ -304,24 +305,35 @@ In the TUI:
304
305
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
305
306
  | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
306
307
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
307
- | `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) |
308
+ | `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **yes, in every mode but `auto`, with no "always" option** (shows the diff or the server's command) |
308
309
 
309
310
  File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
310
- settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
311
- into subagent worktrees (`.dostuff/worktrees/…`) are exempt. The shell check matches the text `.dostuff`, so a name the
312
- command builds indirectly is not caught.
311
+ settings changes too, so `ask` and `allowlist` always prompt for them. Paths into subagent worktrees
312
+ (`.dostuff/worktrees/…`) are exempt, apart from the secrets copied there. The shell check matches the text `.dostuff`,
313
+ so a name the command builds indirectly is not caught.
314
+
315
+ Reading is not a settings change: a read-only shell command on `.dostuff` (`ls .dostuff/agents`, `cat
316
+ ~/.dostuff/config.yaml`) runs like any other, plan mode included. Only the part of a pipeline that names the path has to
317
+ be a read, so `grep FAIL ~/.dostuff/jobs/<session>/<job>.out | sed … | sort -u` is fine. The same paths `read_file` can
318
+ open qualify, so in `ask` and `allowlist` these still ask: `.env*` files and `mcp_config.json` (in a `.dostuff` dir, or
319
+ the legacy one at the project root), a wildcard in the path, a command that changes directory, a `cwd` other than the
320
+ project root, and `grep` / `rg` / `Select-String` over all of a `.dostuff` dir, `.dostuff/worktrees` or one worktree,
321
+ which would reach `.env`.
313
322
 
314
323
  `permissions.mode` in `config.yaml`:
315
324
 
316
325
  - `ask` (default) — as in the table above.
317
326
  - `allowlist` — as `ask`, plus the patterns in `permissions.allow` run without asking (a shell command prefix such as `npm test`, a tool name such as `write_file`, `call_mcp_tool:<server>__<tool>`, `web_fetch:<domain>`, or `web_search`).
318
- - `auto` — nothing asks. A red warning is shown at startup.
327
+ - `auto` — nothing asks, so the agent never stops to wait for approval. That includes settings changes: it can add hooks and MCP servers, create agents and skills, and change most of `.dostuff`, so use it only where you would let it do all of that. It refuses two things, and the call fails at once so the agent carries on: secrets (a `.env*` file, `mcp_config.json` or `.dostuff/data` named in a command, or a search that would reach one) and its own limits (`permissions`, `hooks.project_trust`, `trusted_hooks.json`). `config.yaml` changes only through `edit_config`, which can check them. There is no classifier reviewing commands, and the shell checks match text, so this is a guard against mistakes, not a sandbox. A `PreToolUse` hook that asks still prompts, because you configured it, and so does the one-time trust check for project hooks. A red warning is shown at startup.
319
328
  - `plan` — read-only: reads and read-only shell commands run; file changes, other shell commands and settings changes are denied with a "plan mode" note, and the model is told to investigate and answer with a plan. Web and MCP calls ask as in `ask`.
320
329
 
321
330
  In the TUI, `Shift+Tab` cycles the mode for the session (ask → auto → plan → allowlist); `/permissions <mode>` picks one.
322
331
 
323
332
  Answering `a` (always) approves that tool, or for the shell those commands, for the rest of the session.
324
333
 
334
+ `edit_file` and `multi_edit` grant the same thing, so a rule for either covers both: in `permissions.allow`, in
335
+ `--allowed-tools`, and for `a` (always). It stops there: neither covers `write_file` or `delete_file`.
336
+
325
337
  **Changing settings by asking.** Instead of editing `~/.dostuff/config.yaml` or `mcp_config.json` by hand, ask
326
338
  the agent: "hide the session id in the status bar", "set max_iterations to 50 for this project", "add the GitHub
327
339
  MCP server". It reads the settings with `read_settings`, changes `config.yaml` with `edit_config` (an exact-text
@@ -329,13 +341,13 @@ edit that keeps your comments, checked to be valid YAML) and adds, updates or re
329
341
  `set_mcp_server` / `remove_mcp_server`, in the user files (`~/.dostuff/`) or the project's (`./.dostuff/`).
330
342
  Changes apply at once, without a restart (MCP servers connect or disconnect; tracing changes need a restart).
331
343
  Because these files hold the permission rules and an MCP server is a command that runs on your machine, every
332
- change asks, even in `auto` mode, and so do `write_file` / `edit_file` on anything in a `.dostuff` folder.
344
+ change asks, except in `auto` mode, and so do `write_file` / `edit_file` / `multi_edit` on anything in a `.dostuff` folder.
333
345
  API keys stay in `.env` files, which the agent can't read or change. Subagents don't get these tools.
334
346
 
335
347
  > [!IMPORTANT]
336
348
  > File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
337
- > outside it are rejected, except that discovered skill folders can be read (never written), and `.env*` files and
338
- > the rest of `~/.dostuff/` cannot be read. **The shell is not sandboxed**:
349
+ > outside it are rejected, except that `.dostuff` (the project's and `~/.dostuff/`) and discovered skill folders
350
+ > can be read (never written), and `.env*` files, `mcp_config.json` and `.dostuff/data` cannot be read. **The shell is not sandboxed**:
339
351
  > `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
340
352
  > The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
341
353
 
@@ -652,7 +664,7 @@ You are a code reviewer. Report findings as a list, most severe first.
652
664
  |---|---|
653
665
  | `Read` | `read_file` |
654
666
  | `Write` | `write_file` |
655
- | `Edit`, `MultiEdit` | `edit_file` |
667
+ | `Edit`, `MultiEdit` | `edit_file`, `multi_edit` |
656
668
  | `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
657
669
  | `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
658
670
  | `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
@@ -731,8 +743,15 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
731
743
 
732
744
  `matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
733
745
  matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
734
- go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook. This is
735
- the example from the spec, and the two scripts it runs are below:
746
+ go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook.
747
+
748
+ A tool matcher that matches `edit_file` also fires for `multi_edit`, so a guard or a formatter on `edit_file` holds for
749
+ the same change made through `multi_edit`. It does not work the other way: a `multi_edit` matcher skips `edit_file`. The
750
+ payload stays true to the call, with `tool_name` set to `multi_edit` and `tool_input` to `{path, edits}`. A script that
751
+ reads `tool_input.path` keeps working; one that reads `tool_input.old_str` gets nothing there and needs to read `edits`.
752
+ A hook that rewrites `old_str` / `new_str` makes a `multi_edit` call fail with a tool error, and nothing is written.
753
+
754
+ This is the example from the spec, and the two scripts it runs are below:
736
755
 
737
756
  ```yaml
738
757
  hooks:
@@ -888,6 +907,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
888
907
  | `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
889
908
  | `Write` | `write_file` | `file_path` → `path` |
890
909
  | `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
910
+ | `MultiEdit` | `multi_edit` | `file_path` → `path`, and inside `edits`, `old_string`/`new_string` → `old_str`/`new_str` |
891
911
  | `Read` | `read_file` | `file_path` → `path` |
892
912
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
893
913
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
@@ -958,7 +978,7 @@ See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-str
958
978
 
959
979
  ### `.env`
960
980
 
961
- **Never put secrets in `config.yaml`.** Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
981
+ **Never put secrets in `config.yaml`.** `edit_config` refuses them, `/config` warns, and `dostuff doctor` flags any already there. Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
962
982
 
963
983
  ```bash
964
984
  # ~/.dostuff/.env (chmod 600 on Unix)
@@ -1025,32 +1045,40 @@ Manage servers with `dostuff mcp list` / `add` / `remove` instead of editing the
1025
1045
  "tavily": {
1026
1046
  "transport": "stdio",
1027
1047
  "command": "npx",
1028
- "args": ["-y", "@tavily/mcp-server"],
1029
- "env": { "TAVILY_API_KEY": "tvly-..." }
1048
+ "args": ["-y", "@tavily/mcp-server"]
1030
1049
  },
1031
1050
  "github": {
1032
1051
  "transport": "stdio",
1033
1052
  "command": "uvx",
1034
1053
  "args": ["mcp-server-github"],
1035
- "env": { "GITHUB_TOKEN": "ghp_..." }
1054
+ "env": { "GITHUB_TOKEN": "${MY_WORK_GITHUB_KEY}" }
1036
1055
  },
1037
1056
  "remote": {
1038
1057
  "transport": "http",
1039
1058
  "url": "https://mcp.example.com/sse",
1040
- "headers": { "Authorization": "Bearer xxx" }
1059
+ "headers": { "Authorization": "Bearer ${SEARCH_API_KEY}" }
1041
1060
  }
1042
1061
  }
1043
1062
  }
1044
1063
  ```
1045
1064
 
1065
+ **Keys go in `.dostuff/.env`, not in this file.** `${NAME}` in `headers` and `env` is replaced from `.env` (or the real environment) when the server connects:
1066
+
1067
+ - **HTTP server:** you pick the name. It only links the two files, so `SEARCH_API_KEY=...` in `.env` matches `${SEARCH_API_KEY}` above.
1068
+ - **Local (stdio) server:** the server picks the name, so copy it from the server's docs. It inherits `.env`, so a key under that exact name needs no `env` entry (`tavily` above reads `TAVILY_API_KEY`). Use `env` to pass a key you saved under another name (`github` above).
1069
+
1070
+ Only the exact form `${NAME}` is replaced, and only in `headers` and `env`. If a variable is missing or empty the server doesn't connect, and the error names it; after adding it, restart dostuff. `dostuff doctor` reports missing variables and plain keys left in the file, and `/config` and `dostuff mcp add` warn about them. On the command line use single quotes, so your shell doesn't expand the name itself: `dostuff mcp add search --url https://mcp.example.com -H 'Authorization: Bearer ${SEARCH_API_KEY}'`.
1071
+
1072
+ A server's `url` receives whatever its headers name, so read a project's `.dostuff/mcp_config.json` before you run dostuff in a repository you don't trust, just as you would for a `command` it runs.
1073
+
1046
1074
  | Field | Required for | Notes |
1047
1075
  | ----------- | ------------ | ------------------------------ |
1048
1076
  | `transport` | optional | `stdio` (default) or `http` |
1049
1077
  | `command` | stdio | Executable (`npx`, `uvx`, ...) |
1050
1078
  | `args` | stdio | Argument list |
1051
- | `env` | stdio | Env vars for the child process |
1079
+ | `env` | stdio | Env vars for the child process, added to what it inherits; `${NAME}` is read from `.env` |
1052
1080
  | `url` | http | Remote MCP server URL |
1053
- | `headers` | http | HTTP headers |
1081
+ | `headers` | http | HTTP headers; `${NAME}` is read from `.env` |
1054
1082
  | `connect_timeout` | optional | Seconds before giving up on this server (default 150, enough for a browser OAuth login) |
1055
1083
 
1056
1084
  MCP servers connect concurrently in the background, so the TUI never blanks during boot. Each server is announced in the chat area upon successful or failed connection.
@@ -1121,6 +1149,20 @@ Detailed instructions for the agent go here.
1121
1149
 
1122
1150
  **Running a skill yourself:** each skill is also a slash command, `/<name> [arguments]` (e.g. `/my-skill src/app.py`), in the TUI and with `dostuff -p "/my-skill ..."`. The turn's message is the skill's `SKILL.md` body plus your arguments (which can use `@path` mentions), so the model follows it straight away instead of deciding whether to read it. The command shows in the `/` menu marked `(skill)` and in `/help`. Built-in commands win a name clash, the first skill found (in the order above) wins between skills, and names with spaces can't be run this way; the model can still use those skills on its own.
1123
1151
 
1152
+ **Manual-only skills:** add `disable-model-invocation: true` to the frontmatter and the model is not told about the skill. It is left out of the system prompt and every subagent's prompt, so it only runs when you ask for it, with `/<name>` or a mention (below). It stays in the `/` menu and `/help`, and the `Skills loaded` line at startup marks it `(manual only)`. Only `false`, `no`, `off`, `0` or an empty value leave a skill visible to the model; anything else, a typo included, hides it.
1153
+
1154
+ > [!IMPORTANT]
1155
+ > `disable-model-invocation` is **not a security boundary**. It stops the model from discovering and choosing the
1156
+ > skill; it does not block anything. The skill's folder stays readable by the file tools, a project skill is an
1157
+ > ordinary project file, and the shell can read whatever your user can. To guarantee a dangerous command never runs,
1158
+ > put a `PreToolUse` [hook](#hooks) on that command.
1159
+
1160
+ **Mentioning a skill:** write `/<name>` inside a message, as in `go ahead and /deploy`, to make that skill available for that message. This is how the model gets to use a manual-only skill, and it works for any skill. The `SKILL.md` is not expanded: the model gets a note after your message with the skill's name, description and folder, and judges from your wording, so `don't run /deploy yet` works. You keep seeing the message as you typed it, plus a line, `Skill available for this message: deploy`; if that line is missing, the name wasn't recognised. It works in prompts, queued prompts, steering messages and `dostuff -p`. The permission lasts for that message, and subagents don't inherit it.
1161
+
1162
+ A mention follows a space or a new line, can be any case, and may end in one `.`, `,`, `!`, `?`, `:` or `;`. So `` `/deploy` ``, `(/deploy)` and `/deploy/x` are not mentions, and neither is a path like `/tmp/notes.md`. Custom commands can't be mentioned. Only what you type counts: a `/deploy` inside an `@file` or a paste collapsed to `[Pasted text #1 …]` grants nothing. A message that starts with a skill or custom command is that command's run, so `/review then /deploy` grants nothing for `deploy`.
1163
+
1164
+ While you type, `/` after a space opens the menu with skills only. Tab and Enter there replace just that word: your sentence stays and nothing is sent until the next Enter.
1165
+
1124
1166
  Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder. Restart the agent after adding new skills.
1125
1167
 
1126
1168
  ### Custom commands
@@ -34,15 +34,15 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
34
34
  - **MCP server support** — stdio (npx, uvx) and HTTP transports
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
- - **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)
37
+ - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `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
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
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)
41
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
42
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)
43
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)
44
- - **File sandbox** — file tools stay inside the project directory, plus read-only access to discovered skill folders, and never read `.env*` files or the rest of `~/.dostuff/`
45
- - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
44
+ - **File sandbox** — file tools stay inside the project directory, plus read-only access to `.dostuff` (the project's and `~/.dostuff/`) and to discovered skill folders; `.env*` files, `mcp_config.json` and `.dostuff/data` (past sessions and prompts, saved MCP client secrets) are never readable
45
+ - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`, name one mid-message to allow it for that message, or keep one manual-only with `disable-model-invocation`. See [Skills](#skills)
46
46
  - **Subagents** — the `agent` tool starts agents in parallel, in the foreground or the background, from built-in types (`explore`, `plan`, `general-purpose`), your own Markdown agent files (Claude Code's `.claude/agents/` work too) or a `fork` of the conversation; continue one with `send_message`, stop it with `stop_agent`, see them all in `/agents`. See [Subagents](#subagents)
47
47
  - **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
48
48
  - **Retries with backoff** for rate limits, timeouts and 5xx errors (6 by default, exponential with jitter, honors `Retry-After`; `loop.max_retries` / `loop.retry_max_delay`); auth / bad-request errors fail fast
@@ -210,6 +210,7 @@ In the TUI:
210
210
  | `/queue` / `/queue clear` | List the prompts waiting for the current turn: edit one (back into the input), run it next or remove it / drop them all |
211
211
  | `/jobs [<id>]` / `/jobs kill <id>` | List this session's background jobs (id, owner, status, runtime, command) / show a job's last 40 lines of output and its log files / stop one (the agent is told). See [Background jobs](#background-jobs) |
212
212
  | `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
213
+ | `… /<skill> …` | Mid-message, makes that skill available for this message; the `/` menu offers skills as you type. See [Skills](#skills) |
213
214
  | `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
214
215
  | `/rename <title>` | Name this session (shown by `dostuff sessions`) |
215
216
  | `/export [<path>]` | Save this session as Markdown (default `dostuff-session-<id>.md`) |
@@ -228,7 +229,7 @@ In the TUI:
228
229
  - **Sticky prompt** — once a prompt or `!command` scrolls off the top, it stays pinned there on one row while you are in its turn, as the answer streams or when you scroll back through an old one, until the next prompt reaches the top. Click it to go back to the start of the turn; `↓ Jump to bottom` returns you to the latest message
229
230
  - **Approvals** — a selector (arrows, a number, or `y` = allow once, `a` = always this session, `n` = deny with an optional note); several calls in one response can be approved together
230
231
  - **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
231
- - **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
232
+ - **Diffs** — `write_file` / `edit_file` / `multi_edit` changes shown as a coloured diff
232
233
  - **Errors** — red background
233
234
  - **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
234
235
  - **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
@@ -248,7 +249,7 @@ In the TUI:
248
249
  | ---- | ---- | ----- |
249
250
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
250
251
  | `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
251
- | `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
252
+ | `write_file`, `edit_file`, `multi_edit`, `delete_file` | write | yes (shows a diff; `multi_edit` shows one diff for all its edits) |
252
253
  | `bash_command` | shell | yes, unless every part of the command is on the read-only allow-list (`ls`, `cat`, `git status`, `git diff`, …) with no redirection or substitution |
253
254
  | `call_mcp_tool` | mcp | yes |
254
255
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
@@ -256,24 +257,35 @@ In the TUI:
256
257
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
257
258
  | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
258
259
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
259
- | `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) |
260
+ | `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **yes, in every mode but `auto`, with no "always" option** (shows the diff or the server's command) |
260
261
 
261
262
  File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
262
- settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
263
- into subagent worktrees (`.dostuff/worktrees/…`) are exempt. The shell check matches the text `.dostuff`, so a name the
264
- command builds indirectly is not caught.
263
+ settings changes too, so `ask` and `allowlist` always prompt for them. Paths into subagent worktrees
264
+ (`.dostuff/worktrees/…`) are exempt, apart from the secrets copied there. The shell check matches the text `.dostuff`,
265
+ so a name the command builds indirectly is not caught.
266
+
267
+ Reading is not a settings change: a read-only shell command on `.dostuff` (`ls .dostuff/agents`, `cat
268
+ ~/.dostuff/config.yaml`) runs like any other, plan mode included. Only the part of a pipeline that names the path has to
269
+ be a read, so `grep FAIL ~/.dostuff/jobs/<session>/<job>.out | sed … | sort -u` is fine. The same paths `read_file` can
270
+ open qualify, so in `ask` and `allowlist` these still ask: `.env*` files and `mcp_config.json` (in a `.dostuff` dir, or
271
+ the legacy one at the project root), a wildcard in the path, a command that changes directory, a `cwd` other than the
272
+ project root, and `grep` / `rg` / `Select-String` over all of a `.dostuff` dir, `.dostuff/worktrees` or one worktree,
273
+ which would reach `.env`.
265
274
 
266
275
  `permissions.mode` in `config.yaml`:
267
276
 
268
277
  - `ask` (default) — as in the table above.
269
278
  - `allowlist` — as `ask`, plus the patterns in `permissions.allow` run without asking (a shell command prefix such as `npm test`, a tool name such as `write_file`, `call_mcp_tool:<server>__<tool>`, `web_fetch:<domain>`, or `web_search`).
270
- - `auto` — nothing asks. A red warning is shown at startup.
279
+ - `auto` — nothing asks, so the agent never stops to wait for approval. That includes settings changes: it can add hooks and MCP servers, create agents and skills, and change most of `.dostuff`, so use it only where you would let it do all of that. It refuses two things, and the call fails at once so the agent carries on: secrets (a `.env*` file, `mcp_config.json` or `.dostuff/data` named in a command, or a search that would reach one) and its own limits (`permissions`, `hooks.project_trust`, `trusted_hooks.json`). `config.yaml` changes only through `edit_config`, which can check them. There is no classifier reviewing commands, and the shell checks match text, so this is a guard against mistakes, not a sandbox. A `PreToolUse` hook that asks still prompts, because you configured it, and so does the one-time trust check for project hooks. A red warning is shown at startup.
271
280
  - `plan` — read-only: reads and read-only shell commands run; file changes, other shell commands and settings changes are denied with a "plan mode" note, and the model is told to investigate and answer with a plan. Web and MCP calls ask as in `ask`.
272
281
 
273
282
  In the TUI, `Shift+Tab` cycles the mode for the session (ask → auto → plan → allowlist); `/permissions <mode>` picks one.
274
283
 
275
284
  Answering `a` (always) approves that tool, or for the shell those commands, for the rest of the session.
276
285
 
286
+ `edit_file` and `multi_edit` grant the same thing, so a rule for either covers both: in `permissions.allow`, in
287
+ `--allowed-tools`, and for `a` (always). It stops there: neither covers `write_file` or `delete_file`.
288
+
277
289
  **Changing settings by asking.** Instead of editing `~/.dostuff/config.yaml` or `mcp_config.json` by hand, ask
278
290
  the agent: "hide the session id in the status bar", "set max_iterations to 50 for this project", "add the GitHub
279
291
  MCP server". It reads the settings with `read_settings`, changes `config.yaml` with `edit_config` (an exact-text
@@ -281,13 +293,13 @@ edit that keeps your comments, checked to be valid YAML) and adds, updates or re
281
293
  `set_mcp_server` / `remove_mcp_server`, in the user files (`~/.dostuff/`) or the project's (`./.dostuff/`).
282
294
  Changes apply at once, without a restart (MCP servers connect or disconnect; tracing changes need a restart).
283
295
  Because these files hold the permission rules and an MCP server is a command that runs on your machine, every
284
- change asks, even in `auto` mode, and so do `write_file` / `edit_file` on anything in a `.dostuff` folder.
296
+ change asks, except in `auto` mode, and so do `write_file` / `edit_file` / `multi_edit` on anything in a `.dostuff` folder.
285
297
  API keys stay in `.env` files, which the agent can't read or change. Subagents don't get these tools.
286
298
 
287
299
  > [!IMPORTANT]
288
300
  > File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
289
- > outside it are rejected, except that discovered skill folders can be read (never written), and `.env*` files and
290
- > the rest of `~/.dostuff/` cannot be read. **The shell is not sandboxed**:
301
+ > outside it are rejected, except that `.dostuff` (the project's and `~/.dostuff/`) and discovered skill folders
302
+ > can be read (never written), and `.env*` files, `mcp_config.json` and `.dostuff/data` cannot be read. **The shell is not sandboxed**:
291
303
  > `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
292
304
  > The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
293
305
 
@@ -604,7 +616,7 @@ You are a code reviewer. Report findings as a list, most severe first.
604
616
  |---|---|
605
617
  | `Read` | `read_file` |
606
618
  | `Write` | `write_file` |
607
- | `Edit`, `MultiEdit` | `edit_file` |
619
+ | `Edit`, `MultiEdit` | `edit_file`, `multi_edit` |
608
620
  | `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
609
621
  | `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
610
622
  | `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
@@ -683,8 +695,15 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
683
695
 
684
696
  `matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
685
697
  matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
686
- go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook. This is
687
- the example from the spec, and the two scripts it runs are below:
698
+ go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook.
699
+
700
+ A tool matcher that matches `edit_file` also fires for `multi_edit`, so a guard or a formatter on `edit_file` holds for
701
+ the same change made through `multi_edit`. It does not work the other way: a `multi_edit` matcher skips `edit_file`. The
702
+ payload stays true to the call, with `tool_name` set to `multi_edit` and `tool_input` to `{path, edits}`. A script that
703
+ reads `tool_input.path` keeps working; one that reads `tool_input.old_str` gets nothing there and needs to read `edits`.
704
+ A hook that rewrites `old_str` / `new_str` makes a `multi_edit` call fail with a tool error, and nothing is written.
705
+
706
+ This is the example from the spec, and the two scripts it runs are below:
688
707
 
689
708
  ```yaml
690
709
  hooks:
@@ -840,6 +859,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
840
859
  | `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
841
860
  | `Write` | `write_file` | `file_path` → `path` |
842
861
  | `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
862
+ | `MultiEdit` | `multi_edit` | `file_path` → `path`, and inside `edits`, `old_string`/`new_string` → `old_str`/`new_str` |
843
863
  | `Read` | `read_file` | `file_path` → `path` |
844
864
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
845
865
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
@@ -910,7 +930,7 @@ See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-str
910
930
 
911
931
  ### `.env`
912
932
 
913
- **Never put secrets in `config.yaml`.** Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
933
+ **Never put secrets in `config.yaml`.** `edit_config` refuses them, `/config` warns, and `dostuff doctor` flags any already there. Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
914
934
 
915
935
  ```bash
916
936
  # ~/.dostuff/.env (chmod 600 on Unix)
@@ -977,32 +997,40 @@ Manage servers with `dostuff mcp list` / `add` / `remove` instead of editing the
977
997
  "tavily": {
978
998
  "transport": "stdio",
979
999
  "command": "npx",
980
- "args": ["-y", "@tavily/mcp-server"],
981
- "env": { "TAVILY_API_KEY": "tvly-..." }
1000
+ "args": ["-y", "@tavily/mcp-server"]
982
1001
  },
983
1002
  "github": {
984
1003
  "transport": "stdio",
985
1004
  "command": "uvx",
986
1005
  "args": ["mcp-server-github"],
987
- "env": { "GITHUB_TOKEN": "ghp_..." }
1006
+ "env": { "GITHUB_TOKEN": "${MY_WORK_GITHUB_KEY}" }
988
1007
  },
989
1008
  "remote": {
990
1009
  "transport": "http",
991
1010
  "url": "https://mcp.example.com/sse",
992
- "headers": { "Authorization": "Bearer xxx" }
1011
+ "headers": { "Authorization": "Bearer ${SEARCH_API_KEY}" }
993
1012
  }
994
1013
  }
995
1014
  }
996
1015
  ```
997
1016
 
1017
+ **Keys go in `.dostuff/.env`, not in this file.** `${NAME}` in `headers` and `env` is replaced from `.env` (or the real environment) when the server connects:
1018
+
1019
+ - **HTTP server:** you pick the name. It only links the two files, so `SEARCH_API_KEY=...` in `.env` matches `${SEARCH_API_KEY}` above.
1020
+ - **Local (stdio) server:** the server picks the name, so copy it from the server's docs. It inherits `.env`, so a key under that exact name needs no `env` entry (`tavily` above reads `TAVILY_API_KEY`). Use `env` to pass a key you saved under another name (`github` above).
1021
+
1022
+ Only the exact form `${NAME}` is replaced, and only in `headers` and `env`. If a variable is missing or empty the server doesn't connect, and the error names it; after adding it, restart dostuff. `dostuff doctor` reports missing variables and plain keys left in the file, and `/config` and `dostuff mcp add` warn about them. On the command line use single quotes, so your shell doesn't expand the name itself: `dostuff mcp add search --url https://mcp.example.com -H 'Authorization: Bearer ${SEARCH_API_KEY}'`.
1023
+
1024
+ A server's `url` receives whatever its headers name, so read a project's `.dostuff/mcp_config.json` before you run dostuff in a repository you don't trust, just as you would for a `command` it runs.
1025
+
998
1026
  | Field | Required for | Notes |
999
1027
  | ----------- | ------------ | ------------------------------ |
1000
1028
  | `transport` | optional | `stdio` (default) or `http` |
1001
1029
  | `command` | stdio | Executable (`npx`, `uvx`, ...) |
1002
1030
  | `args` | stdio | Argument list |
1003
- | `env` | stdio | Env vars for the child process |
1031
+ | `env` | stdio | Env vars for the child process, added to what it inherits; `${NAME}` is read from `.env` |
1004
1032
  | `url` | http | Remote MCP server URL |
1005
- | `headers` | http | HTTP headers |
1033
+ | `headers` | http | HTTP headers; `${NAME}` is read from `.env` |
1006
1034
  | `connect_timeout` | optional | Seconds before giving up on this server (default 150, enough for a browser OAuth login) |
1007
1035
 
1008
1036
  MCP servers connect concurrently in the background, so the TUI never blanks during boot. Each server is announced in the chat area upon successful or failed connection.
@@ -1073,6 +1101,20 @@ Detailed instructions for the agent go here.
1073
1101
 
1074
1102
  **Running a skill yourself:** each skill is also a slash command, `/<name> [arguments]` (e.g. `/my-skill src/app.py`), in the TUI and with `dostuff -p "/my-skill ..."`. The turn's message is the skill's `SKILL.md` body plus your arguments (which can use `@path` mentions), so the model follows it straight away instead of deciding whether to read it. The command shows in the `/` menu marked `(skill)` and in `/help`. Built-in commands win a name clash, the first skill found (in the order above) wins between skills, and names with spaces can't be run this way; the model can still use those skills on its own.
1075
1103
 
1104
+ **Manual-only skills:** add `disable-model-invocation: true` to the frontmatter and the model is not told about the skill. It is left out of the system prompt and every subagent's prompt, so it only runs when you ask for it, with `/<name>` or a mention (below). It stays in the `/` menu and `/help`, and the `Skills loaded` line at startup marks it `(manual only)`. Only `false`, `no`, `off`, `0` or an empty value leave a skill visible to the model; anything else, a typo included, hides it.
1105
+
1106
+ > [!IMPORTANT]
1107
+ > `disable-model-invocation` is **not a security boundary**. It stops the model from discovering and choosing the
1108
+ > skill; it does not block anything. The skill's folder stays readable by the file tools, a project skill is an
1109
+ > ordinary project file, and the shell can read whatever your user can. To guarantee a dangerous command never runs,
1110
+ > put a `PreToolUse` [hook](#hooks) on that command.
1111
+
1112
+ **Mentioning a skill:** write `/<name>` inside a message, as in `go ahead and /deploy`, to make that skill available for that message. This is how the model gets to use a manual-only skill, and it works for any skill. The `SKILL.md` is not expanded: the model gets a note after your message with the skill's name, description and folder, and judges from your wording, so `don't run /deploy yet` works. You keep seeing the message as you typed it, plus a line, `Skill available for this message: deploy`; if that line is missing, the name wasn't recognised. It works in prompts, queued prompts, steering messages and `dostuff -p`. The permission lasts for that message, and subagents don't inherit it.
1113
+
1114
+ A mention follows a space or a new line, can be any case, and may end in one `.`, `,`, `!`, `?`, `:` or `;`. So `` `/deploy` ``, `(/deploy)` and `/deploy/x` are not mentions, and neither is a path like `/tmp/notes.md`. Custom commands can't be mentioned. Only what you type counts: a `/deploy` inside an `@file` or a paste collapsed to `[Pasted text #1 …]` grants nothing. A message that starts with a skill or custom command is that command's run, so `/review then /deploy` grants nothing for `deploy`.
1115
+
1116
+ While you type, `/` after a space opens the menu with skills only. Tab and Enter there replace just that word: your sentence stays and nothing is sent until the next Enter.
1117
+
1076
1118
  Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder. Restart the agent after adding new skills.
1077
1119
 
1078
1120
  ### Custom commands
@@ -25,10 +25,11 @@ def _background_wait(interactive: bool) -> str:
25
25
 
26
26
 
27
27
  def skills_summary(skills: list[dict[str, Any]]) -> str:
28
- """The skills list as the system prompt shows it."""
28
+ """The skills list as the system prompt shows it: every prompt goes through here, so a manual-only skill
29
+ (`disable-model-invocation`) is left out in this one place."""
29
30
  summary = "\n\n".join(
30
31
  f"- name: {s['name']}\n description: {s['description']}\n dir: {s['dir']}"
31
- for s in skills
32
+ for s in skills if not s.get("disable_model_invocation")
32
33
  )
33
34
  return summary or "(none available)"
34
35