dostuff 0.2.10__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 (183) hide show
  1. {dostuff-0.2.10 → dostuff-0.2.12}/PKG-INFO +75 -27
  2. {dostuff-0.2.10 → dostuff-0.2.12}/README.md +74 -26
  3. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/call_agent.py +32 -2
  4. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/instructions.py +18 -12
  5. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/loop.py +15 -5
  6. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/permissions.py +213 -23
  7. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/run_tool.py +19 -5
  8. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/subagents/definitions.py +2 -2
  9. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/subagents/fork.py +1 -1
  10. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/subagents/prompt.py +2 -2
  11. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/cli.py +11 -4
  12. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/cli_tui.py +206 -26
  13. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/headless.py +20 -7
  14. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/constants.py +10 -6
  15. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/consume_stream.py +14 -1
  16. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/context_usage.py +10 -3
  17. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/environment_context.py +1 -1
  18. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/file_mentions.py +6 -2
  19. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/manage_context.py +3 -0
  20. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/side_question.py +6 -9
  21. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/slash_suggestion.py +9 -0
  22. dostuff-0.2.12/dostuff/helpers/agent/turn_context.py +58 -0
  23. dostuff-0.2.12/dostuff/helpers/config_secrets.py +41 -0
  24. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/hooks/dispatch.py +9 -1
  25. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/hooks/events.py +2 -7
  26. dostuff-0.2.12/dostuff/helpers/mcp/server_config.py +68 -0
  27. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/memory/export_session.py +3 -0
  28. dostuff-0.2.12/dostuff/helpers/skills/discover_skills.py +89 -0
  29. dostuff-0.2.12/dostuff/helpers/skills/skill_command.py +96 -0
  30. dostuff-0.2.12/dostuff/helpers/tools/resolve_safe_path.py +70 -0
  31. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/ui/doctor.py +19 -1
  32. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/ui/tools_listing.py +1 -1
  33. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/checkpoints.py +2 -2
  34. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/mcp/mcp_client.py +8 -3
  35. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/memory/session_store.py +6 -3
  36. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/templates/config.example.yaml +2 -2
  37. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/create_agent_type.py +1 -1
  38. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/definitions.py +5 -2
  39. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/files/edit_file.py +33 -17
  40. dostuff-0.2.12/dostuff/tools/files/multi_edit.py +77 -0
  41. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/names.py +1 -1
  42. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/settings.py +44 -10
  43. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff.egg-info/PKG-INFO +75 -27
  44. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff.egg-info/SOURCES.txt +6 -0
  45. {dostuff-0.2.10 → dostuff-0.2.12}/pyproject.toml +1 -1
  46. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_checkpoints_todos_caching.py +11 -0
  47. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_cli_commands.py +79 -1
  48. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_create_agent_type.py +2 -1
  49. dostuff-0.2.12/tests/test_export_session.py +27 -0
  50. dostuff-0.2.12/tests/test_file_tools.py +405 -0
  51. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_hooks.py +72 -1
  52. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_loop.py +212 -7
  53. dostuff-0.2.12/tests/test_mcp_env_references.py +177 -0
  54. dostuff-0.2.12/tests/test_optional_memory_and_instructions.py +220 -0
  55. dostuff-0.2.12/tests/test_permissions.py +808 -0
  56. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_roadmap_021.py +23 -0
  57. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_session_store.py +71 -0
  58. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_settings_tools.py +61 -5
  59. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_side_question.py +15 -16
  60. dostuff-0.2.12/tests/test_skill_command.py +138 -0
  61. dostuff-0.2.12/tests/test_skills_discovery.py +287 -0
  62. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_slash_suggestion.py +11 -1
  63. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_subagents_fork.py +48 -4
  64. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_subagents_run.py +18 -0
  65. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_subagents_store.py +2 -3
  66. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_subagents_types.py +15 -1
  67. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_tui.py +1265 -40
  68. dostuff-0.2.12/tests/test_turn_context.py +197 -0
  69. dostuff-0.2.10/dostuff/helpers/mcp/server_config.py +0 -36
  70. dostuff-0.2.10/dostuff/helpers/skills/discover_skills.py +0 -49
  71. dostuff-0.2.10/dostuff/helpers/skills/skill_command.py +0 -48
  72. dostuff-0.2.10/dostuff/helpers/tools/resolve_safe_path.py +0 -33
  73. dostuff-0.2.10/tests/test_file_tools.py +0 -116
  74. dostuff-0.2.10/tests/test_optional_memory_and_instructions.py +0 -85
  75. dostuff-0.2.10/tests/test_permissions.py +0 -422
  76. dostuff-0.2.10/tests/test_skill_command.py +0 -37
  77. dostuff-0.2.10/tests/test_skills_discovery.py +0 -37
  78. {dostuff-0.2.10 → dostuff-0.2.12}/LICENSE +0 -0
  79. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/__init__.py +0 -0
  80. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/__main__.py +0 -0
  81. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/subagents/__init__.py +0 -0
  82. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/subagents/adapter.py +0 -0
  83. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/subagents/registry.py +0 -0
  84. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/agent/subagents/run.py +0 -0
  85. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/config.py +0 -0
  86. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/append_step.py +0 -0
  87. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  88. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/load_identity.py +0 -0
  89. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  90. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  91. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/loop_emit.py +0 -0
  92. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/model_cost.py +0 -0
  93. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/notices.py +0 -0
  94. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/pastes.py +0 -0
  95. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/quick_memory.py +0 -0
  96. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/steering.py +0 -0
  97. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/agent/tool_output.py +0 -0
  98. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/hooks/__init__.py +0 -0
  99. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/hooks/load_hooks.py +0 -0
  100. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/hooks/run_hook.py +0 -0
  101. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/hooks/trust.py +0 -0
  102. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  103. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  104. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/mcp/token_store.py +0 -0
  105. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  106. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/memory/shell_step.py +0 -0
  107. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/models/add_model_entry.py +0 -0
  108. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/models/list_models.py +0 -0
  109. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/models/opencode.py +0 -0
  110. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/skills/custom_commands.py +0 -0
  111. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/tools/diff.py +0 -0
  112. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  113. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/tools/project_root.py +0 -0
  114. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/ui/__init__.py +0 -0
  115. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/ui/ask_answers.py +0 -0
  116. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/ui/emit.py +0 -0
  117. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/ui/prompt_history.py +0 -0
  118. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/helpers/ui/terminal_signals.py +0 -0
  119. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/exceptions.py +0 -0
  120. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  121. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  122. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/memory/chroma.py +0 -0
  123. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  124. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  125. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/memory/stores.py +0 -0
  126. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/memory/types.py +0 -0
  127. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/model.py +0 -0
  128. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/tracing.py +0 -0
  129. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/lib/worktree.py +0 -0
  130. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/memory/__init__.py +0 -0
  131. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/setup_wizard.py +0 -0
  132. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/skills.py +0 -0
  133. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/templates/env.example +0 -0
  134. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/__init__.py +0 -0
  135. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/agent.py +0 -0
  136. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/ask_user.py +0 -0
  137. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/bash/bash_command.py +0 -0
  138. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/bash/bash_output.py +0 -0
  139. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/bash/jobs.py +0 -0
  140. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/bash/kill_shell.py +0 -0
  141. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/files/delete_file.py +0 -0
  142. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/files/list_files.py +0 -0
  143. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/files/read_file.py +0 -0
  144. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/files/write_file.py +0 -0
  145. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/get_current_datetime.py +0 -0
  146. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  147. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  148. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  149. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/memory/save_episode.py +0 -0
  150. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/memory/save_memory.py +0 -0
  151. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/search/glob.py +0 -0
  152. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/search/grep.py +0 -0
  153. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/search/walk.py +0 -0
  154. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/send_message.py +0 -0
  155. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/stop_agent.py +0 -0
  156. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/todo_write.py +0 -0
  157. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/web_fetch.py +0 -0
  158. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff/tools/web_search.py +0 -0
  159. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff.egg-info/dependency_links.txt +0 -0
  160. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff.egg-info/entry_points.txt +0 -0
  161. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff.egg-info/requires.txt +0 -0
  162. {dostuff-0.2.10 → dostuff-0.2.12}/dostuff.egg-info/top_level.txt +0 -0
  163. {dostuff-0.2.10 → dostuff-0.2.12}/setup.cfg +0 -0
  164. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_ask_user.py +0 -0
  165. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_bash_command.py +0 -0
  166. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_config_memory_mcp.py +0 -0
  167. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_file_mentions.py +0 -0
  168. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_jobs.py +0 -0
  169. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_mcp_e2e.py +0 -0
  170. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_mcp_oauth.py +0 -0
  171. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_opencode.py +0 -0
  172. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_pastes.py +0 -0
  173. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_setup_wizard.py +0 -0
  174. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_side_question_litellm.py +0 -0
  175. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_steering.py +0 -0
  176. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_subagent.py +0 -0
  177. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_subagents_background.py +0 -0
  178. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_terminal_signals.py +0 -0
  179. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_tool_schemas.py +0 -0
  180. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_tools_listing.py +0 -0
  181. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_web_fetch.py +0 -0
  182. {dostuff-0.2.10 → dostuff-0.2.12}/tests/test_web_search.py +0 -0
  183. {dostuff-0.2.10 → 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.10
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 and never read `.env*` files or `~/.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
@@ -250,7 +250,7 @@ In the TUI:
250
250
  | `/model [<provider/model>] [--active]` | Pick a model: your saved ones (`models:` in config.yaml) first, then "More <provider> models…" for each provider's list (type to filter; Enter on no match uses what you typed). A model that isn't saved yet is added to `~/.dostuff/config.yaml`. A plain `/model` switch lasts only for this session; add `--active` (e.g. `/model --active`, or `/model anthropic/claude-sonnet-5-5 --active`) to make it the default that new sessions start with |
251
251
  | `/config [mcp] [project]` | Edit a settings file right in the TUI: pick `config.yaml` or the MCP servers, user (`~/.dostuff`) or project (`./.dostuff`), or name one (`/config mcp project`). `Ctrl+S` checks the file, saves it and applies it without a restart (an invalid file stays open with the error); `Esc` closes, twice if there are unsaved changes. A new file starts with every option commented out. `.env` files aren't offered |
252
252
  | `/status` | Session, directory, model, permission mode, tokens, context use, MCP servers |
253
- | `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
253
+ | `/context` | What fills the context window: system prompt, turn context (the environment, recalled memories and hook context sent with each prompt), tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
254
254
  | `/memory [project\|global]` | Edit `AGENTS.md` (this project's or `~/.dostuff/AGENTS.md`) in the same editor as `/config`; `Ctrl+S` saves and the agent follows it from the next message |
255
255
  | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
256
256
  | `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then each connected MCP server's tools (reached through `call_mcp_tool`) |
@@ -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`) |
@@ -273,9 +274,10 @@ In the TUI:
273
274
  **Visual elements:**
274
275
 
275
276
  - **Messages** — `>` for your prompts (on a grey band), `●` for agent replies and tool calls, `⎿` for tool results; the terminal background shows through
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
276
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
277
279
  - **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
278
- - **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
279
281
  - **Errors** — red background
280
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
281
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
@@ -295,7 +297,7 @@ In the TUI:
295
297
  | ---- | ---- | ----- |
296
298
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
297
299
  | `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
298
- | `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) |
299
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 |
300
302
  | `call_mcp_tool` | mcp | yes |
301
303
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
@@ -303,24 +305,35 @@ In the TUI:
303
305
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
304
306
  | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
305
307
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
306
- | `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) |
307
309
 
308
310
  File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
309
- settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
310
- into subagent worktrees (`.dostuff/worktrees/…`) are exempt. The shell check matches the text `.dostuff`, so a name the
311
- 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`.
312
322
 
313
323
  `permissions.mode` in `config.yaml`:
314
324
 
315
325
  - `ask` (default) — as in the table above.
316
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`).
317
- - `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.
318
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`.
319
329
 
320
330
  In the TUI, `Shift+Tab` cycles the mode for the session (ask → auto → plan → allowlist); `/permissions <mode>` picks one.
321
331
 
322
332
  Answering `a` (always) approves that tool, or for the shell those commands, for the rest of the session.
323
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
+
324
337
  **Changing settings by asking.** Instead of editing `~/.dostuff/config.yaml` or `mcp_config.json` by hand, ask
325
338
  the agent: "hide the session id in the status bar", "set max_iterations to 50 for this project", "add the GitHub
326
339
  MCP server". It reads the settings with `read_settings`, changes `config.yaml` with `edit_config` (an exact-text
@@ -328,12 +341,13 @@ edit that keeps your comments, checked to be valid YAML) and adds, updates or re
328
341
  `set_mcp_server` / `remove_mcp_server`, in the user files (`~/.dostuff/`) or the project's (`./.dostuff/`).
329
342
  Changes apply at once, without a restart (MCP servers connect or disconnect; tracing changes need a restart).
330
343
  Because these files hold the permission rules and an MCP server is a command that runs on your machine, every
331
- 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.
332
345
  API keys stay in `.env` files, which the agent can't read or change. Subagents don't get these tools.
333
346
 
334
347
  > [!IMPORTANT]
335
348
  > File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
336
- > outside it are rejected, and `.env*` files and `~/.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**:
337
351
  > `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
338
352
  > The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
339
353
 
@@ -568,7 +582,7 @@ both modes: a skill is a turn's prompt, not a correction.
568
582
  order you sent them, so a message holding a big file never jumps ahead of the one after it. The `Attached …` lines
569
583
  show as they finish, as for a prompt.
570
584
  - **Hooks and the sandbox still apply**: `UserPromptSubmit` runs for each correction at the boundary, so a hook can
571
- block it — it is shown like a blocked prompt and never reaches the model — or add context for this turn, written as a
585
+ block it — it is shown like a blocked prompt and never reaches the model — or add context, written as a
572
586
  note right before the correction (the system prompt never changes mid-turn, so the prompt cache holds); a preparation
573
587
  failure is reported instead of half-delivered.
574
588
 
@@ -650,7 +664,7 @@ You are a code reviewer. Report findings as a list, most severe first.
650
664
  |---|---|
651
665
  | `Read` | `read_file` |
652
666
  | `Write` | `write_file` |
653
- | `Edit`, `MultiEdit` | `edit_file` |
667
+ | `Edit`, `MultiEdit` | `edit_file`, `multi_edit` |
654
668
  | `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
655
669
  | `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
656
670
  | `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
@@ -718,7 +732,7 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
718
732
  | Event | When | Matcher is matched against | What a hook can do |
719
733
  |---|---|---|---|
720
734
  | `SessionStart` | Before the first turn of a session, and after a compaction | the source: `startup`, `resume`, `clear`, `compact` | Add context for the rest of the session |
721
- | `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context for this turn |
735
+ | `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context sent with it (hidden from the transcript, and stays in the model's history) |
722
736
  | `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
723
737
  | `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
724
738
  | `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
@@ -729,8 +743,15 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
729
743
 
730
744
  `matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
731
745
  matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
732
- 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
733
- 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:
734
755
 
735
756
  ```yaml
736
757
  hooks:
@@ -886,6 +907,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
886
907
  | `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
887
908
  | `Write` | `write_file` | `file_path` → `path` |
888
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` |
889
911
  | `Read` | `read_file` | `file_path` → `path` |
890
912
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
891
913
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
@@ -956,7 +978,7 @@ See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-str
956
978
 
957
979
  ### `.env`
958
980
 
959
- **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:
960
982
 
961
983
  ```bash
962
984
  # ~/.dostuff/.env (chmod 600 on Unix)
@@ -1023,32 +1045,40 @@ Manage servers with `dostuff mcp list` / `add` / `remove` instead of editing the
1023
1045
  "tavily": {
1024
1046
  "transport": "stdio",
1025
1047
  "command": "npx",
1026
- "args": ["-y", "@tavily/mcp-server"],
1027
- "env": { "TAVILY_API_KEY": "tvly-..." }
1048
+ "args": ["-y", "@tavily/mcp-server"]
1028
1049
  },
1029
1050
  "github": {
1030
1051
  "transport": "stdio",
1031
1052
  "command": "uvx",
1032
1053
  "args": ["mcp-server-github"],
1033
- "env": { "GITHUB_TOKEN": "ghp_..." }
1054
+ "env": { "GITHUB_TOKEN": "${MY_WORK_GITHUB_KEY}" }
1034
1055
  },
1035
1056
  "remote": {
1036
1057
  "transport": "http",
1037
1058
  "url": "https://mcp.example.com/sse",
1038
- "headers": { "Authorization": "Bearer xxx" }
1059
+ "headers": { "Authorization": "Bearer ${SEARCH_API_KEY}" }
1039
1060
  }
1040
1061
  }
1041
1062
  }
1042
1063
  ```
1043
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
+
1044
1074
  | Field | Required for | Notes |
1045
1075
  | ----------- | ------------ | ------------------------------ |
1046
1076
  | `transport` | optional | `stdio` (default) or `http` |
1047
1077
  | `command` | stdio | Executable (`npx`, `uvx`, ...) |
1048
1078
  | `args` | stdio | Argument list |
1049
- | `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` |
1050
1080
  | `url` | http | Remote MCP server URL |
1051
- | `headers` | http | HTTP headers |
1081
+ | `headers` | http | HTTP headers; `${NAME}` is read from `.env` |
1052
1082
  | `connect_timeout` | optional | Seconds before giving up on this server (default 150, enough for a browser OAuth login) |
1053
1083
 
1054
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.
@@ -1090,7 +1120,11 @@ Skills are directories containing a `SKILL.md` (frontmatter with `name` and `des
1090
1120
  4. `~/.agents/skills/`
1091
1121
  5. `<cwd>/skills/`
1092
1122
 
1093
- **Conflict resolution:** No deduplication in the system prompt. If two skills share the same name (from different directories), both are loaded and passed to the model — the agent may see the same skill twice with different `location` paths. To avoid confusion, keep names unique across the search paths.
1123
+ **Conflict resolution:** Skills are deduplicated by name: if two share a name, the first one found (in the order above) wins and the other is dropped, from the system prompt and from the slash commands alike.
1124
+
1125
+ **How a skill reaches the model:** the system prompt lists each skill's `name`, `description` and `dir` (its absolute folder), and only those. When the model decides to use a skill it reads the `SKILL.md` in that dir with `read_file`, so a body costs nothing until it is needed. Frontmatter is parsed as YAML, so quoted and folded (`>`, `|`) descriptions arrive as plain text; a file with invalid YAML still loads, with its fields read line by line.
1126
+
1127
+ File tools can read a discovered skill's folder wherever it lives, including the files next to `SKILL.md` (`scripts/`, `reference/`), but never write there. `.env*` files stay unreadable inside a skill folder too, and of `~/.dostuff/` only discovered skills under `~/.dostuff/skills/` can be read.
1094
1128
 
1095
1129
  **Example structure:**
1096
1130
 
@@ -1115,6 +1149,20 @@ Detailed instructions for the agent go here.
1115
1149
 
1116
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.
1117
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
+
1118
1166
  Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder. Restart the agent after adding new skills.
1119
1167
 
1120
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 and never read `.env*` files or `~/.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
@@ -202,7 +202,7 @@ In the TUI:
202
202
  | `/model [<provider/model>] [--active]` | Pick a model: your saved ones (`models:` in config.yaml) first, then "More <provider> models…" for each provider's list (type to filter; Enter on no match uses what you typed). A model that isn't saved yet is added to `~/.dostuff/config.yaml`. A plain `/model` switch lasts only for this session; add `--active` (e.g. `/model --active`, or `/model anthropic/claude-sonnet-5-5 --active`) to make it the default that new sessions start with |
203
203
  | `/config [mcp] [project]` | Edit a settings file right in the TUI: pick `config.yaml` or the MCP servers, user (`~/.dostuff`) or project (`./.dostuff`), or name one (`/config mcp project`). `Ctrl+S` checks the file, saves it and applies it without a restart (an invalid file stays open with the error); `Esc` closes, twice if there are unsaved changes. A new file starts with every option commented out. `.env` files aren't offered |
204
204
  | `/status` | Session, directory, model, permission mode, tokens, context use, MCP servers |
205
- | `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
205
+ | `/context` | What fills the context window: system prompt, turn context (the environment, recalled memories and hook context sent with each prompt), tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
206
206
  | `/memory [project\|global]` | Edit `AGENTS.md` (this project's or `~/.dostuff/AGENTS.md`) in the same editor as `/config`; `Ctrl+S` saves and the agent follows it from the next message |
207
207
  | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
208
208
  | `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then each connected MCP server's tools (reached through `call_mcp_tool`) |
@@ -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`) |
@@ -225,9 +226,10 @@ In the TUI:
225
226
  **Visual elements:**
226
227
 
227
228
  - **Messages** — `>` for your prompts (on a grey band), `●` for agent replies and tool calls, `⎿` for tool results; the terminal background shows through
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
228
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
229
231
  - **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
230
- - **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
231
233
  - **Errors** — red background
232
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
233
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
@@ -247,7 +249,7 @@ In the TUI:
247
249
  | ---- | ---- | ----- |
248
250
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
249
251
  | `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
250
- | `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) |
251
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 |
252
254
  | `call_mcp_tool` | mcp | yes |
253
255
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
@@ -255,24 +257,35 @@ In the TUI:
255
257
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
256
258
  | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
257
259
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
258
- | `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) |
259
261
 
260
262
  File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
261
- settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
262
- into subagent worktrees (`.dostuff/worktrees/…`) are exempt. The shell check matches the text `.dostuff`, so a name the
263
- 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`.
264
274
 
265
275
  `permissions.mode` in `config.yaml`:
266
276
 
267
277
  - `ask` (default) — as in the table above.
268
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`).
269
- - `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.
270
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`.
271
281
 
272
282
  In the TUI, `Shift+Tab` cycles the mode for the session (ask → auto → plan → allowlist); `/permissions <mode>` picks one.
273
283
 
274
284
  Answering `a` (always) approves that tool, or for the shell those commands, for the rest of the session.
275
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
+
276
289
  **Changing settings by asking.** Instead of editing `~/.dostuff/config.yaml` or `mcp_config.json` by hand, ask
277
290
  the agent: "hide the session id in the status bar", "set max_iterations to 50 for this project", "add the GitHub
278
291
  MCP server". It reads the settings with `read_settings`, changes `config.yaml` with `edit_config` (an exact-text
@@ -280,12 +293,13 @@ edit that keeps your comments, checked to be valid YAML) and adds, updates or re
280
293
  `set_mcp_server` / `remove_mcp_server`, in the user files (`~/.dostuff/`) or the project's (`./.dostuff/`).
281
294
  Changes apply at once, without a restart (MCP servers connect or disconnect; tracing changes need a restart).
282
295
  Because these files hold the permission rules and an MCP server is a command that runs on your machine, every
283
- 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.
284
297
  API keys stay in `.env` files, which the agent can't read or change. Subagents don't get these tools.
285
298
 
286
299
  > [!IMPORTANT]
287
300
  > File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
288
- > outside it are rejected, and `.env*` files and `~/.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**:
289
303
  > `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
290
304
  > The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
291
305
 
@@ -520,7 +534,7 @@ both modes: a skill is a turn's prompt, not a correction.
520
534
  order you sent them, so a message holding a big file never jumps ahead of the one after it. The `Attached …` lines
521
535
  show as they finish, as for a prompt.
522
536
  - **Hooks and the sandbox still apply**: `UserPromptSubmit` runs for each correction at the boundary, so a hook can
523
- block it — it is shown like a blocked prompt and never reaches the model — or add context for this turn, written as a
537
+ block it — it is shown like a blocked prompt and never reaches the model — or add context, written as a
524
538
  note right before the correction (the system prompt never changes mid-turn, so the prompt cache holds); a preparation
525
539
  failure is reported instead of half-delivered.
526
540
 
@@ -602,7 +616,7 @@ You are a code reviewer. Report findings as a list, most severe first.
602
616
  |---|---|
603
617
  | `Read` | `read_file` |
604
618
  | `Write` | `write_file` |
605
- | `Edit`, `MultiEdit` | `edit_file` |
619
+ | `Edit`, `MultiEdit` | `edit_file`, `multi_edit` |
606
620
  | `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
607
621
  | `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
608
622
  | `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
@@ -670,7 +684,7 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
670
684
  | Event | When | Matcher is matched against | What a hook can do |
671
685
  |---|---|---|---|
672
686
  | `SessionStart` | Before the first turn of a session, and after a compaction | the source: `startup`, `resume`, `clear`, `compact` | Add context for the rest of the session |
673
- | `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context for this turn |
687
+ | `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context sent with it (hidden from the transcript, and stays in the model's history) |
674
688
  | `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
675
689
  | `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
676
690
  | `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
@@ -681,8 +695,15 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
681
695
 
682
696
  `matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
683
697
  matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
684
- 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
685
- 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:
686
707
 
687
708
  ```yaml
688
709
  hooks:
@@ -838,6 +859,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
838
859
  | `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
839
860
  | `Write` | `write_file` | `file_path` → `path` |
840
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` |
841
863
  | `Read` | `read_file` | `file_path` → `path` |
842
864
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
843
865
  | `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
@@ -908,7 +930,7 @@ See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-str
908
930
 
909
931
  ### `.env`
910
932
 
911
- **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:
912
934
 
913
935
  ```bash
914
936
  # ~/.dostuff/.env (chmod 600 on Unix)
@@ -975,32 +997,40 @@ Manage servers with `dostuff mcp list` / `add` / `remove` instead of editing the
975
997
  "tavily": {
976
998
  "transport": "stdio",
977
999
  "command": "npx",
978
- "args": ["-y", "@tavily/mcp-server"],
979
- "env": { "TAVILY_API_KEY": "tvly-..." }
1000
+ "args": ["-y", "@tavily/mcp-server"]
980
1001
  },
981
1002
  "github": {
982
1003
  "transport": "stdio",
983
1004
  "command": "uvx",
984
1005
  "args": ["mcp-server-github"],
985
- "env": { "GITHUB_TOKEN": "ghp_..." }
1006
+ "env": { "GITHUB_TOKEN": "${MY_WORK_GITHUB_KEY}" }
986
1007
  },
987
1008
  "remote": {
988
1009
  "transport": "http",
989
1010
  "url": "https://mcp.example.com/sse",
990
- "headers": { "Authorization": "Bearer xxx" }
1011
+ "headers": { "Authorization": "Bearer ${SEARCH_API_KEY}" }
991
1012
  }
992
1013
  }
993
1014
  }
994
1015
  ```
995
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
+
996
1026
  | Field | Required for | Notes |
997
1027
  | ----------- | ------------ | ------------------------------ |
998
1028
  | `transport` | optional | `stdio` (default) or `http` |
999
1029
  | `command` | stdio | Executable (`npx`, `uvx`, ...) |
1000
1030
  | `args` | stdio | Argument list |
1001
- | `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` |
1002
1032
  | `url` | http | Remote MCP server URL |
1003
- | `headers` | http | HTTP headers |
1033
+ | `headers` | http | HTTP headers; `${NAME}` is read from `.env` |
1004
1034
  | `connect_timeout` | optional | Seconds before giving up on this server (default 150, enough for a browser OAuth login) |
1005
1035
 
1006
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.
@@ -1042,7 +1072,11 @@ Skills are directories containing a `SKILL.md` (frontmatter with `name` and `des
1042
1072
  4. `~/.agents/skills/`
1043
1073
  5. `<cwd>/skills/`
1044
1074
 
1045
- **Conflict resolution:** No deduplication in the system prompt. If two skills share the same name (from different directories), both are loaded and passed to the model — the agent may see the same skill twice with different `location` paths. To avoid confusion, keep names unique across the search paths.
1075
+ **Conflict resolution:** Skills are deduplicated by name: if two share a name, the first one found (in the order above) wins and the other is dropped, from the system prompt and from the slash commands alike.
1076
+
1077
+ **How a skill reaches the model:** the system prompt lists each skill's `name`, `description` and `dir` (its absolute folder), and only those. When the model decides to use a skill it reads the `SKILL.md` in that dir with `read_file`, so a body costs nothing until it is needed. Frontmatter is parsed as YAML, so quoted and folded (`>`, `|`) descriptions arrive as plain text; a file with invalid YAML still loads, with its fields read line by line.
1078
+
1079
+ File tools can read a discovered skill's folder wherever it lives, including the files next to `SKILL.md` (`scripts/`, `reference/`), but never write there. `.env*` files stay unreadable inside a skill folder too, and of `~/.dostuff/` only discovered skills under `~/.dostuff/skills/` can be read.
1046
1080
 
1047
1081
  **Example structure:**
1048
1082
 
@@ -1067,6 +1101,20 @@ Detailed instructions for the agent go here.
1067
1101
 
1068
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.
1069
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
+
1070
1118
  Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder. Restart the agent after adding new skills.
1071
1119
 
1072
1120
  ### Custom commands
@@ -8,7 +8,7 @@ from dostuff.lib.tracing import content_attr, tracer
8
8
  from opentelemetry.trace import Status, StatusCode
9
9
 
10
10
 
11
- # Two breakpoints: the system prompt (tools + instructions, stable within a turn) and the last
11
+ # Two breakpoints: the system prompt (tools + instructions, stable across turns) and the last
12
12
  # message, which moves each call, so the next call reads everything before it from the cache.
13
13
  CACHE_BREAKPOINTS: list[dict[str, Any]] = [
14
14
  {"location": "message", "role": "system"},
@@ -39,11 +39,41 @@ def build_request_kwargs(stream: bool) -> dict[str, Any]:
39
39
  return kwargs
40
40
 
41
41
 
42
+ def _as_blocks(content: Any) -> list[Any]:
43
+ if isinstance(content, list):
44
+ return content
45
+ return [{"type": "text", "text": content}] if content else []
46
+
47
+
48
+ def _join_user_content(first: Any, second: Any) -> Any:
49
+ if isinstance(first, list) or isinstance(second, list):
50
+ return _as_blocks(first) + _as_blocks(second) # an image block must survive, so no flattening to text
51
+ return "\n\n".join(text for text in (first, second) if text)
52
+
53
+
54
+ def provider_messages(steps: list[dict[str, Any]]) -> list[dict[str, Any]]:
55
+ """The history as a provider may see it. The steps themselves are left alone: the store and every reader need
56
+ them apart, while a request needs valid turns.
57
+
58
+ `meta` is dostuff's own (the turn-context marker), so it is dropped. Adjacent user steps become one message,
59
+ because Perplexity and strict chat templates (vLLM's Gemma, Mistral) reject two in a row, and a turn's context
60
+ step always sits right before its prompt. Same history, same result, so the cached prefix holds.
61
+ """
62
+ messages: list[dict[str, Any]] = []
63
+ for step in steps:
64
+ message = {k: v for k, v in step.items() if k != "meta"} if "meta" in step else step
65
+ if messages and message.get("role") == "user" and messages[-1].get("role") == "user":
66
+ messages[-1] = {**messages[-1], "content": _join_user_content(messages[-1].get("content"), message.get("content"))}
67
+ else:
68
+ messages.append(message)
69
+ return messages
70
+
71
+
42
72
  async def call_agent(steps_history: list, system_instruction: str, tool_names: list[str] | None = None, stream: bool = False):
43
73
  if tool_names is None:
44
74
  tool_names = default_tool_names()
45
75
  active_schemas = [TOOL_SCHEMAS[name] for name in tool_names if name in TOOL_SCHEMAS]
46
- messages = [{"role": "system", "content": system_instruction}] + steps_history
76
+ messages = [{"role": "system", "content": system_instruction}] + provider_messages(steps_history)
47
77
  request = build_request_kwargs(stream)
48
78
 
49
79
  span = tracer.start_span("model_call")