dostuff 0.2.5__tar.gz → 0.2.7__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. {dostuff-0.2.5 → dostuff-0.2.7}/PKG-INFO +132 -11
  2. {dostuff-0.2.5 → dostuff-0.2.7}/README.md +131 -10
  3. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/agent/instructions.py +31 -9
  4. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/agent/loop.py +44 -20
  5. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/agent/permissions.py +11 -3
  6. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/agent/run_tool.py +11 -1
  7. dostuff-0.2.7/dostuff/agent/subagents/__init__.py +32 -0
  8. dostuff-0.2.7/dostuff/agent/subagents/adapter.py +103 -0
  9. dostuff-0.2.7/dostuff/agent/subagents/definitions.py +373 -0
  10. dostuff-0.2.7/dostuff/agent/subagents/fork.py +43 -0
  11. dostuff-0.2.7/dostuff/agent/subagents/prompt.py +53 -0
  12. dostuff-0.2.7/dostuff/agent/subagents/registry.py +576 -0
  13. dostuff-0.2.7/dostuff/agent/subagents/run.py +148 -0
  14. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/cli_tui.py +578 -95
  15. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/config.py +18 -2
  16. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/headless.py +122 -20
  17. dostuff-0.2.7/dostuff/helpers/agent/append_step.py +13 -0
  18. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/constants.py +53 -4
  19. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/get_model_token_limit.py +4 -4
  20. dostuff-0.2.7/dostuff/helpers/agent/notices.py +132 -0
  21. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/slash_suggestion.py +21 -1
  22. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/hooks/dispatch.py +5 -3
  23. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/hooks/events.py +26 -0
  24. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/hooks/load_hooks.py +2 -1
  25. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/hooks/run_hook.py +10 -1
  26. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/skills/discover_skills.py +17 -3
  27. dostuff-0.2.7/dostuff/helpers/ui/tools_listing.py +61 -0
  28. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/memory/session_store.py +99 -5
  29. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/model.py +23 -5
  30. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/templates/config.example.yaml +17 -2
  31. dostuff-0.2.7/dostuff/tools/agent.py +102 -0
  32. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/bash/jobs.py +15 -11
  33. dostuff-0.2.7/dostuff/tools/create_agent_type.py +138 -0
  34. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/definitions.py +15 -9
  35. dostuff-0.2.7/dostuff/tools/names.py +16 -0
  36. dostuff-0.2.7/dostuff/tools/send_message.py +53 -0
  37. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/settings.py +6 -3
  38. dostuff-0.2.7/dostuff/tools/stop_agent.py +21 -0
  39. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff.egg-info/PKG-INFO +132 -11
  40. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff.egg-info/SOURCES.txt +22 -1
  41. {dostuff-0.2.5 → dostuff-0.2.7}/pyproject.toml +1 -1
  42. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_bash_command.py +4 -2
  43. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_checkpoints_todos_caching.py +1 -1
  44. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_cli_commands.py +146 -0
  45. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_config_memory_mcp.py +55 -1
  46. dostuff-0.2.7/tests/test_create_agent_type.py +93 -0
  47. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_hooks.py +119 -5
  48. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_jobs.py +7 -5
  49. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_loop.py +2 -2
  50. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_permissions.py +26 -2
  51. dostuff-0.2.7/tests/test_session_store.py +440 -0
  52. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_settings_tools.py +1 -1
  53. dostuff-0.2.7/tests/test_skills_discovery.py +37 -0
  54. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_slash_suggestion.py +18 -0
  55. dostuff-0.2.7/tests/test_subagent.py +174 -0
  56. dostuff-0.2.7/tests/test_subagents_background.py +510 -0
  57. dostuff-0.2.7/tests/test_subagents_fork.py +241 -0
  58. dostuff-0.2.7/tests/test_subagents_run.py +499 -0
  59. dostuff-0.2.7/tests/test_subagents_store.py +324 -0
  60. dostuff-0.2.7/tests/test_subagents_types.py +485 -0
  61. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_tool_schemas.py +10 -1
  62. dostuff-0.2.7/tests/test_tools_listing.py +35 -0
  63. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_tui.py +843 -13
  64. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_worktree.py +26 -25
  65. dostuff-0.2.5/dostuff/helpers/agent/append_step.py +0 -11
  66. dostuff-0.2.5/dostuff/tools/delegate_to_subagent.py +0 -266
  67. dostuff-0.2.5/tests/test_session_store.py +0 -179
  68. dostuff-0.2.5/tests/test_subagent.py +0 -164
  69. {dostuff-0.2.5 → dostuff-0.2.7}/LICENSE +0 -0
  70. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/__init__.py +0 -0
  71. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/__main__.py +0 -0
  72. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/agent/call_agent.py +0 -0
  73. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/cli.py +0 -0
  74. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/consume_stream.py +0 -0
  75. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/context_usage.py +0 -0
  76. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/environment_context.py +0 -0
  77. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/file_mentions.py +0 -0
  78. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/load_identity.py +0 -0
  79. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  80. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  81. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/loop_emit.py +0 -0
  82. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/manage_context.py +0 -0
  83. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/model_cost.py +0 -0
  84. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/pastes.py +0 -0
  85. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/quick_memory.py +0 -0
  86. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/agent/tool_output.py +0 -0
  87. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/hooks/__init__.py +0 -0
  88. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/hooks/trust.py +0 -0
  89. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  90. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  91. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/mcp/server_config.py +0 -0
  92. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/mcp/token_store.py +0 -0
  93. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/memory/export_session.py +0 -0
  94. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  95. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/memory/shell_step.py +0 -0
  96. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/models/add_model_entry.py +0 -0
  97. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/models/list_models.py +0 -0
  98. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/models/opencode.py +0 -0
  99. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/skills/custom_commands.py +0 -0
  100. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/skills/skill_command.py +0 -0
  101. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/tools/diff.py +0 -0
  102. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  103. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/tools/project_root.py +0 -0
  104. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  105. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/ui/__init__.py +0 -0
  106. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/ui/doctor.py +0 -0
  107. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/ui/emit.py +0 -0
  108. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/ui/prompt_history.py +0 -0
  109. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/helpers/ui/terminal_signals.py +0 -0
  110. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/checkpoints.py +0 -0
  111. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/exceptions.py +0 -0
  112. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/mcp/mcp_client.py +0 -0
  113. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  114. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  115. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/memory/chroma.py +0 -0
  116. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  117. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  118. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/memory/stores.py +0 -0
  119. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/memory/types.py +0 -0
  120. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/tracing.py +0 -0
  121. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/lib/worktree.py +0 -0
  122. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/memory/__init__.py +0 -0
  123. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/setup_wizard.py +0 -0
  124. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/skills.py +0 -0
  125. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/templates/env.example +0 -0
  126. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/__init__.py +0 -0
  127. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/bash/bash_command.py +0 -0
  128. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/bash/bash_output.py +0 -0
  129. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/bash/kill_shell.py +0 -0
  130. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/files/delete_file.py +0 -0
  131. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/files/edit_file.py +0 -0
  132. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/files/list_files.py +0 -0
  133. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/files/read_file.py +0 -0
  134. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/files/write_file.py +0 -0
  135. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/get_current_datetime.py +0 -0
  136. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  137. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  138. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  139. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/memory/save_episode.py +0 -0
  140. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/memory/save_memory.py +0 -0
  141. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/search/glob.py +0 -0
  142. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/search/grep.py +0 -0
  143. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/search/walk.py +0 -0
  144. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/todo_write.py +0 -0
  145. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/web_fetch.py +0 -0
  146. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff/tools/web_search.py +0 -0
  147. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff.egg-info/dependency_links.txt +0 -0
  148. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff.egg-info/entry_points.txt +0 -0
  149. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff.egg-info/requires.txt +0 -0
  150. {dostuff-0.2.5 → dostuff-0.2.7}/dostuff.egg-info/top_level.txt +0 -0
  151. {dostuff-0.2.5 → dostuff-0.2.7}/setup.cfg +0 -0
  152. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_file_mentions.py +0 -0
  153. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_file_tools.py +0 -0
  154. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_mcp_e2e.py +0 -0
  155. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_mcp_oauth.py +0 -0
  156. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_opencode.py +0 -0
  157. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_optional_memory_and_instructions.py +0 -0
  158. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_pastes.py +0 -0
  159. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_roadmap_021.py +0 -0
  160. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_setup_wizard.py +0 -0
  161. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_skill_command.py +0 -0
  162. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_terminal_signals.py +0 -0
  163. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_web_fetch.py +0 -0
  164. {dostuff-0.2.5 → dostuff-0.2.7}/tests/test_web_search.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dostuff
3
- Version: 0.2.5
3
+ Version: 0.2.7
4
4
  Summary: DoStuff - a terminal coding agent for any LLM: TUI and headless mode, permissions, MCP, skills, web tools, sessions and git worktrees
5
5
  Author-email: Varun Kumawat <varunkumawatleap2@gmail.com>
6
6
  License-Expression: MIT
@@ -84,11 +84,11 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
84
84
  - **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
85
85
  - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
86
86
  - **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
87
- - **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` 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)
87
+ - **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
88
88
  - **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)
89
89
  - **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
90
90
  - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
91
- - **Subagents** — `delegate_to_subagent` runs a bounded task with a restricted tool set; its approval prompts and ESC go through the same TUI
91
+ - **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)
92
92
  - **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
93
93
  - **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
94
94
  - **Token and cost tracking** — per-turn and cumulative totals in `/status` and the line after each turn (`✻ Worked for 1m 5s · $0.01`); cost in USD from litellm's price table (hidden when the model has no known price). The table bundled with litellm is used, so startup doesn't wait on a download; set `LITELLM_LOCAL_MODEL_COST_MAP=False` to fetch the latest one from GitHub instead
@@ -230,9 +230,10 @@ In the TUI:
230
230
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
231
231
  | `Esc` `Esc` | With an empty input: take back your last prompt. It and everything after it (answer, tool calls) leave the conversation and the prompt goes back in the input to edit and resend. Files that turn changed stay as they are; `/undo` restores them |
232
232
  | `Ctrl+O` | Expand / collapse every truncated tool and shell result (click one to toggle just that one) |
233
- | `Ctrl+B` | While the agent waits on a shell command (the loader says `Ctrl+B to background`): move it, and any a subagent is running, to the background; the agent gets what it printed so far and carries on. Not for `!command`s. See [Background jobs](#background-jobs) |
233
+ | `Ctrl+B` | While the agent waits on a shell command or a foreground subagent (the loader says `Ctrl+B to background`): move them to the background; the agent gets what a command printed so far and carries on, and hears from the agent when it ends. Not for `!command`s. See [Background jobs](#background-jobs) and [Subagents](#subagents) |
234
234
  | `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
235
235
  | `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
236
+ | `/agents` / `/agents types` / `/agents reload` | This session's agents (running first): pick one to read its transcript, answer its approval prompt or stop it / the agent types with their source, model and tools (`/agents types <name>`: one type's system prompt and config) / re-read the agent files |
236
237
  | `/exit` | Save the session and quit |
237
238
  | `/clear` | Start a new session; the old one stays resumable |
238
239
  | `/resume [<id>]` | Pick another session from this directory (or switch to the given one) |
@@ -247,6 +248,7 @@ In the TUI:
247
248
  | `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
248
249
  | `/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 |
249
250
  | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
251
+ | `/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`) |
250
252
  | `/hooks [r]` | List the configured hooks per event: file, matcher, timeout, `fail_closed`, and whether each runs (`user` / `trusted` / `untrusted` / `disabled` / `broken`). `/hooks r` re-reads the config files. See [Hooks](#hooks) |
251
253
  | `/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 |
252
254
  | `/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) |
@@ -281,6 +283,8 @@ In the TUI:
281
283
 
282
284
  ## Tools and permissions
283
285
 
286
+ `/tools` lists these in the TUI, plus the tools of the connected MCP servers.
287
+
284
288
  | Tool | Kind | Asks? |
285
289
  | ---- | ---- | ----- |
286
290
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
@@ -290,9 +294,9 @@ In the TUI:
290
294
  | `call_mcp_tool` | mcp | yes |
291
295
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
292
296
  | `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url` |
293
- | `delegate_to_subagent` | — | no; the subagent's own calls ask |
297
+ | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
294
298
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
295
- | `edit_config`, `set_mcp_server`, `remove_mcp_server` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
299
+ | `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) |
296
300
 
297
301
  File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
298
302
  settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
@@ -392,6 +396,112 @@ paths). Directories older than 7 days are removed at startup.
392
396
 
393
397
  ---
394
398
 
399
+ ## Subagents
400
+
401
+ A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
402
+ `agent` tool and gets one report back, so the searching, reading and trial and error stay out of the main
403
+ conversation. Several `agent` calls in one response run in parallel. The main agent follows up with `send_message`
404
+ and can stop one with `stop_agent`.
405
+
406
+ | Tool | What it does |
407
+ |---|---|
408
+ | `agent(description, prompt, subagent_type, model, run_in_background, isolation)` | Start an agent. `description` is 3–5 words for the UI; `prompt` is the whole task (the agent sees nothing else); `subagent_type` picks the type (default `general-purpose`); `model` overrides the type's; `isolation="worktree"` runs it in its own git worktree. The result is its report, ending with `agent_id: <id>` |
409
+ | `send_message(to, message, run_in_background)` | Continue an agent. One that has ended runs again with its whole history plus the message; one still running reads it before its next step |
410
+ | `stop_agent(agent_id)` | Stop a running agent; its shell jobs are killed and its worktree is closed out |
411
+
412
+ A subagent can never start, message or stop agents, delete files, save memories, write the todo list or change
413
+ settings, whatever its type asks for. At most `agents.max_concurrent` (4) run at once; more are queued.
414
+
415
+ ### Agent types
416
+
417
+ | Type | Tools | For |
418
+ |---|---|---|
419
+ | `general-purpose` | every subagent tool | research and multi-step tasks, including changing files. The default |
420
+ | `explore` | read-only (its `bash_command` only runs read-only commands) | finding code and answering where things are; model: `agents.explore_model` |
421
+ | `plan` | read-only | investigating and returning a step-by-step plan |
422
+ | `fork` | the main agent's | a copy of the main agent that inherits the whole conversation (same system prompt, so a Claude model reuses the prompt cache). Costly: only when the task needs the conversation. Always the main model |
423
+
424
+ Your own types are Markdown files with YAML frontmatter. They are searched in this order, and the first file with a
425
+ given `name` wins: `.dostuff/agents/` and `.claude/agents/` in the project, then `~/.dostuff/agents/` and
426
+ `~/.claude/agents/`. `agents.read_claude_agents: false` skips both `.claude` folders. A file can replace a built-in
427
+ type, except `fork`. Files are re-read when they change; `/agents reload` forces it.
428
+
429
+ You can also ask the agent for one ("make a code-reviewer agent"): its `create_agent_type(name, description, prompt,
430
+ tools, model, max_iterations, scope, replace)` tool writes the file to `.dostuff/agents/` (`scope="user"`:
431
+ `~/.dostuff/agents/`) after showing it to you. Like the settings tools, it asks in every mode. The new type can be
432
+ started at once.
433
+
434
+ ```markdown
435
+ ---
436
+ name: code-reviewer
437
+ description: Reviews a diff for bugs and missing tests. Use after a change.
438
+ tools: Read, Grep, Glob, Bash # omit for every subagent tool
439
+ model: fast # inherit (default), an alias from agents.models, or a litellm model string
440
+ max_iterations: 30 # optional; default agents.max_iterations
441
+ ---
442
+ You are a code reviewer. Report findings as a list, most severe first.
443
+ ```
444
+
445
+ `tools:` takes DoStuff names or Claude Code's, so Claude Code agent files work unchanged:
446
+
447
+ | Claude Code | DoStuff |
448
+ |---|---|
449
+ | `Read` | `read_file` |
450
+ | `Write` | `write_file` |
451
+ | `Edit`, `MultiEdit` | `edit_file` |
452
+ | `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
453
+ | `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
454
+ | `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
455
+ | `mcp__*` | `search_mcp_tools`, `get_mcp_tool_details`, `call_mcp_tool` |
456
+
457
+ Unknown and forbidden names are dropped with a warning naming the file; `/agents types` lists each type with its
458
+ source, resolved model, tools and any warnings, and `/agents types <name>` shows one type's whole config: its
459
+ system prompt, model, tools and max iterations (for `fork`, the task message it gets). `model:` aliases come from `agents.models`; Claude Code's `sonnet`,
460
+ `opus` and `haiku` are looked up there too and fall back to the main model (with a warning in the report) when they
461
+ aren't defined. The call's `model=` wins over the type's `model:`.
462
+
463
+ ### Background agents
464
+
465
+ With `run_in_background=true` the call returns the `agent_id` at once and the main agent keeps working. When the agent
466
+ ends, its report arrives as a `<background-agent id=… status=…>` message before the main agent's next model call, and
467
+ the TUI shows `⚙ agent "<description>" (<type>) finished after 2m 10s`. If the TUI is idle it starts a turn for it
468
+ (`agents.wake_on_end`, at most 3 automatic turns in a row together with background jobs). `Ctrl+B` moves running
469
+ foreground agents to the background. Approval prompts from a background agent are titled
470
+ `[agent: <description> · <type>]` and wait while you type. The status line shows `⚙ 2 agents` (or
471
+ `⚠ 1 agent waiting` for approval); click it for `/agents`.
472
+
473
+ `dostuff -p` waits for background agents and runs a turn on their reports before it prints the answer, for at most 3
474
+ such turns; agents still running then are stopped and named on stderr. `--output-format stream-json` prints an
475
+ `{"type": "agent", …}` event when an agent starts and when it ends.
476
+
477
+ Quitting asks before it stops running agents. `/clear` and `/resume` keep background agents running in the new
478
+ session.
479
+
480
+ ### Transcripts and `/agents`
481
+
482
+ Every agent's steps are saved in the session database, apart from the main conversation. `/agents` lists this
483
+ session's agents (id, status, runtime, description and type, tokens, cost); pick one to read its whole transcript,
484
+ answer its approval prompt, stop it or show its type's system prompt and config. After a restart or `/resume` the agents come back as records (a run that was
485
+ going is `interrupted`) that `send_message` can continue.
486
+
487
+ ### Hooks and config
488
+
489
+ `SubagentStart` fires when a run starts and can add context to its task; `SubagentStop` fires on its final answer.
490
+ Both match the agent type, and tool hooks inside an agent see `agent_id` and `agent_type`. See [Hooks](#hooks).
491
+
492
+ ```yaml
493
+ agents:
494
+ max_iterations: 100 # model calls per run; default: the main agent's loop.max_iterations
495
+ max_concurrent: 4 # running or waiting for approval; more are queued
496
+ wake_on_end: true # a finished background agent resumes the idle TUI
497
+ read_claude_agents: true # also load .claude/agents/
498
+ explore_model: inherit # model of the built-in explore type
499
+ models: # aliases for model: and model=
500
+ fast: anthropic/claude-haiku-5-5
501
+ ```
502
+
503
+ ---
504
+
395
505
  ## Hooks
396
506
 
397
507
  Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
@@ -410,7 +520,8 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
410
520
  | `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
411
521
  | `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
412
522
  | `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
413
- | `SubagentStop` | Same, for a `delegate_to_subagent` run | — | Same |
523
+ | `SubagentStart` | When a subagent run starts (an `agent` call, or a `send_message` that continues one) | the agent type | Add context to the run's task. Can't block |
524
+ | `SubagentStop` | Same as `Stop`, for a subagent's final answer | the agent type | Same as `Stop` |
414
525
 
415
526
  ### Config
416
527
 
@@ -515,6 +626,9 @@ worktree), with no terminal. stdin is one JSON object:
515
626
  | `UserPromptSubmit` | `prompt` |
516
627
  | `SessionStart` | `source` |
517
628
  | `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
629
+ | `SubagentStart` | `agent_id`, `agent_type`, `background`, `prompt` |
630
+
631
+ Inside a subagent, `PreToolUse`, `PostToolUse` and `SubagentStop` payloads also carry `agent_id` and `agent_type`.
518
632
 
519
633
  The environment adds `DOSTUFF_HOOK_EVENT`, `DOSTUFF_SESSION_ID`, `DOSTUFF_TURN_ID`, `DOSTUFF_PROJECT_ROOT` and
520
634
  `DOSTUFF_TURN_TYPE`. Output is capped at `loop.max_tool_output_chars`.
@@ -574,8 +688,8 @@ nesting are the same. Tool names and some argument names differ, so rename the m
574
688
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
575
689
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
576
690
 
577
- Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact`, `SessionEnd` and
578
- `SubagentStart` events.
691
+ Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
692
+ events.
579
693
 
580
694
  ---
581
695
 
@@ -610,7 +724,6 @@ models:
610
724
 
611
725
  loop:
612
726
  max_iterations: 100
613
- subagent_max_iterations: 25
614
727
  # context_window: 128000 # override when dostuff/litellm don't know the model
615
728
  max_tool_output_chars: 30000 # longer tool results keep head + tail
616
729
  max_retries: 6 # retries on rate limits, timeouts, 5xx (0 = none)
@@ -622,6 +735,12 @@ memory:
622
735
  permissions:
623
736
  mode: ask # ask | allowlist | auto | plan
624
737
  allow: []
738
+
739
+ agents: # see Subagents
740
+ max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
741
+ max_concurrent: 4
742
+ models:
743
+ fast: anthropic/claude-haiku-5-5
625
744
  ```
626
745
 
627
746
  See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-structure/dostuff/templates/config.example.yaml) for a full template. `dostuff setup` writes it for you.
@@ -933,7 +1052,9 @@ dostuff/
933
1052
  │ ├── web_fetch.py # read a URL as text
934
1053
  │ ├── web_search.py # free web search (SearXNG / ddgs / DuckDuckGo)
935
1054
  │ ├── todo_write.py # visible task list
936
- │ └── delegate_to_subagent.py # bounded subagents (optionally in a worktree)
1055
+ │ ├── agent.py # the agent tool (subagents: dostuff/agent/subagents/)
1056
+ │ ├── create_agent_type.py # write a new agent type file
1057
+ │ └── send_message.py, stop_agent.py # continue or stop an agent
937
1058
  ├── cli.py # CLI typer entrypoints and doctor checkup utilities
938
1059
  ├── cli_tui.py # Textual TUI Application and adapter translates state
939
1060
  ├── config.py # layered config loader supporting project/global yaml and multi-model configuration
@@ -36,11 +36,11 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
36
36
  - **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
37
37
  - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
38
38
  - **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
39
- - **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` 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)
39
+ - **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
40
40
  - **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)
41
41
  - **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
42
42
  - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
43
- - **Subagents** — `delegate_to_subagent` runs a bounded task with a restricted tool set; its approval prompts and ESC go through the same TUI
43
+ - **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)
44
44
  - **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
45
45
  - **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
46
46
  - **Token and cost tracking** — per-turn and cumulative totals in `/status` and the line after each turn (`✻ Worked for 1m 5s · $0.01`); cost in USD from litellm's price table (hidden when the model has no known price). The table bundled with litellm is used, so startup doesn't wait on a download; set `LITELLM_LOCAL_MODEL_COST_MAP=False` to fetch the latest one from GitHub instead
@@ -182,9 +182,10 @@ In the TUI:
182
182
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
183
183
  | `Esc` `Esc` | With an empty input: take back your last prompt. It and everything after it (answer, tool calls) leave the conversation and the prompt goes back in the input to edit and resend. Files that turn changed stay as they are; `/undo` restores them |
184
184
  | `Ctrl+O` | Expand / collapse every truncated tool and shell result (click one to toggle just that one) |
185
- | `Ctrl+B` | While the agent waits on a shell command (the loader says `Ctrl+B to background`): move it, and any a subagent is running, to the background; the agent gets what it printed so far and carries on. Not for `!command`s. See [Background jobs](#background-jobs) |
185
+ | `Ctrl+B` | While the agent waits on a shell command or a foreground subagent (the loader says `Ctrl+B to background`): move them to the background; the agent gets what a command printed so far and carries on, and hears from the agent when it ends. Not for `!command`s. See [Background jobs](#background-jobs) and [Subagents](#subagents) |
186
186
  | `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
187
187
  | `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
188
+ | `/agents` / `/agents types` / `/agents reload` | This session's agents (running first): pick one to read its transcript, answer its approval prompt or stop it / the agent types with their source, model and tools (`/agents types <name>`: one type's system prompt and config) / re-read the agent files |
188
189
  | `/exit` | Save the session and quit |
189
190
  | `/clear` | Start a new session; the old one stays resumable |
190
191
  | `/resume [<id>]` | Pick another session from this directory (or switch to the given one) |
@@ -199,6 +200,7 @@ In the TUI:
199
200
  | `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
200
201
  | `/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 |
201
202
  | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
203
+ | `/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`) |
202
204
  | `/hooks [r]` | List the configured hooks per event: file, matcher, timeout, `fail_closed`, and whether each runs (`user` / `trusted` / `untrusted` / `disabled` / `broken`). `/hooks r` re-reads the config files. See [Hooks](#hooks) |
203
205
  | `/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 |
204
206
  | `/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) |
@@ -233,6 +235,8 @@ In the TUI:
233
235
 
234
236
  ## Tools and permissions
235
237
 
238
+ `/tools` lists these in the TUI, plus the tools of the connected MCP servers.
239
+
236
240
  | Tool | Kind | Asks? |
237
241
  | ---- | ---- | ----- |
238
242
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
@@ -242,9 +246,9 @@ In the TUI:
242
246
  | `call_mcp_tool` | mcp | yes |
243
247
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
244
248
  | `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url` |
245
- | `delegate_to_subagent` | — | no; the subagent's own calls ask |
249
+ | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
246
250
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
247
- | `edit_config`, `set_mcp_server`, `remove_mcp_server` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
251
+ | `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) |
248
252
 
249
253
  File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
250
254
  settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
@@ -344,6 +348,112 @@ paths). Directories older than 7 days are removed at startup.
344
348
 
345
349
  ---
346
350
 
351
+ ## Subagents
352
+
353
+ A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
354
+ `agent` tool and gets one report back, so the searching, reading and trial and error stay out of the main
355
+ conversation. Several `agent` calls in one response run in parallel. The main agent follows up with `send_message`
356
+ and can stop one with `stop_agent`.
357
+
358
+ | Tool | What it does |
359
+ |---|---|
360
+ | `agent(description, prompt, subagent_type, model, run_in_background, isolation)` | Start an agent. `description` is 3–5 words for the UI; `prompt` is the whole task (the agent sees nothing else); `subagent_type` picks the type (default `general-purpose`); `model` overrides the type's; `isolation="worktree"` runs it in its own git worktree. The result is its report, ending with `agent_id: <id>` |
361
+ | `send_message(to, message, run_in_background)` | Continue an agent. One that has ended runs again with its whole history plus the message; one still running reads it before its next step |
362
+ | `stop_agent(agent_id)` | Stop a running agent; its shell jobs are killed and its worktree is closed out |
363
+
364
+ A subagent can never start, message or stop agents, delete files, save memories, write the todo list or change
365
+ settings, whatever its type asks for. At most `agents.max_concurrent` (4) run at once; more are queued.
366
+
367
+ ### Agent types
368
+
369
+ | Type | Tools | For |
370
+ |---|---|---|
371
+ | `general-purpose` | every subagent tool | research and multi-step tasks, including changing files. The default |
372
+ | `explore` | read-only (its `bash_command` only runs read-only commands) | finding code and answering where things are; model: `agents.explore_model` |
373
+ | `plan` | read-only | investigating and returning a step-by-step plan |
374
+ | `fork` | the main agent's | a copy of the main agent that inherits the whole conversation (same system prompt, so a Claude model reuses the prompt cache). Costly: only when the task needs the conversation. Always the main model |
375
+
376
+ Your own types are Markdown files with YAML frontmatter. They are searched in this order, and the first file with a
377
+ given `name` wins: `.dostuff/agents/` and `.claude/agents/` in the project, then `~/.dostuff/agents/` and
378
+ `~/.claude/agents/`. `agents.read_claude_agents: false` skips both `.claude` folders. A file can replace a built-in
379
+ type, except `fork`. Files are re-read when they change; `/agents reload` forces it.
380
+
381
+ You can also ask the agent for one ("make a code-reviewer agent"): its `create_agent_type(name, description, prompt,
382
+ tools, model, max_iterations, scope, replace)` tool writes the file to `.dostuff/agents/` (`scope="user"`:
383
+ `~/.dostuff/agents/`) after showing it to you. Like the settings tools, it asks in every mode. The new type can be
384
+ started at once.
385
+
386
+ ```markdown
387
+ ---
388
+ name: code-reviewer
389
+ description: Reviews a diff for bugs and missing tests. Use after a change.
390
+ tools: Read, Grep, Glob, Bash # omit for every subagent tool
391
+ model: fast # inherit (default), an alias from agents.models, or a litellm model string
392
+ max_iterations: 30 # optional; default agents.max_iterations
393
+ ---
394
+ You are a code reviewer. Report findings as a list, most severe first.
395
+ ```
396
+
397
+ `tools:` takes DoStuff names or Claude Code's, so Claude Code agent files work unchanged:
398
+
399
+ | Claude Code | DoStuff |
400
+ |---|---|
401
+ | `Read` | `read_file` |
402
+ | `Write` | `write_file` |
403
+ | `Edit`, `MultiEdit` | `edit_file` |
404
+ | `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
405
+ | `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
406
+ | `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
407
+ | `mcp__*` | `search_mcp_tools`, `get_mcp_tool_details`, `call_mcp_tool` |
408
+
409
+ Unknown and forbidden names are dropped with a warning naming the file; `/agents types` lists each type with its
410
+ source, resolved model, tools and any warnings, and `/agents types <name>` shows one type's whole config: its
411
+ system prompt, model, tools and max iterations (for `fork`, the task message it gets). `model:` aliases come from `agents.models`; Claude Code's `sonnet`,
412
+ `opus` and `haiku` are looked up there too and fall back to the main model (with a warning in the report) when they
413
+ aren't defined. The call's `model=` wins over the type's `model:`.
414
+
415
+ ### Background agents
416
+
417
+ With `run_in_background=true` the call returns the `agent_id` at once and the main agent keeps working. When the agent
418
+ ends, its report arrives as a `<background-agent id=… status=…>` message before the main agent's next model call, and
419
+ the TUI shows `⚙ agent "<description>" (<type>) finished after 2m 10s`. If the TUI is idle it starts a turn for it
420
+ (`agents.wake_on_end`, at most 3 automatic turns in a row together with background jobs). `Ctrl+B` moves running
421
+ foreground agents to the background. Approval prompts from a background agent are titled
422
+ `[agent: <description> · <type>]` and wait while you type. The status line shows `⚙ 2 agents` (or
423
+ `⚠ 1 agent waiting` for approval); click it for `/agents`.
424
+
425
+ `dostuff -p` waits for background agents and runs a turn on their reports before it prints the answer, for at most 3
426
+ such turns; agents still running then are stopped and named on stderr. `--output-format stream-json` prints an
427
+ `{"type": "agent", …}` event when an agent starts and when it ends.
428
+
429
+ Quitting asks before it stops running agents. `/clear` and `/resume` keep background agents running in the new
430
+ session.
431
+
432
+ ### Transcripts and `/agents`
433
+
434
+ Every agent's steps are saved in the session database, apart from the main conversation. `/agents` lists this
435
+ session's agents (id, status, runtime, description and type, tokens, cost); pick one to read its whole transcript,
436
+ answer its approval prompt, stop it or show its type's system prompt and config. After a restart or `/resume` the agents come back as records (a run that was
437
+ going is `interrupted`) that `send_message` can continue.
438
+
439
+ ### Hooks and config
440
+
441
+ `SubagentStart` fires when a run starts and can add context to its task; `SubagentStop` fires on its final answer.
442
+ Both match the agent type, and tool hooks inside an agent see `agent_id` and `agent_type`. See [Hooks](#hooks).
443
+
444
+ ```yaml
445
+ agents:
446
+ max_iterations: 100 # model calls per run; default: the main agent's loop.max_iterations
447
+ max_concurrent: 4 # running or waiting for approval; more are queued
448
+ wake_on_end: true # a finished background agent resumes the idle TUI
449
+ read_claude_agents: true # also load .claude/agents/
450
+ explore_model: inherit # model of the built-in explore type
451
+ models: # aliases for model: and model=
452
+ fast: anthropic/claude-haiku-5-5
453
+ ```
454
+
455
+ ---
456
+
347
457
  ## Hooks
348
458
 
349
459
  Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
@@ -362,7 +472,8 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
362
472
  | `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
363
473
  | `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
364
474
  | `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
365
- | `SubagentStop` | Same, for a `delegate_to_subagent` run | — | Same |
475
+ | `SubagentStart` | When a subagent run starts (an `agent` call, or a `send_message` that continues one) | the agent type | Add context to the run's task. Can't block |
476
+ | `SubagentStop` | Same as `Stop`, for a subagent's final answer | the agent type | Same as `Stop` |
366
477
 
367
478
  ### Config
368
479
 
@@ -467,6 +578,9 @@ worktree), with no terminal. stdin is one JSON object:
467
578
  | `UserPromptSubmit` | `prompt` |
468
579
  | `SessionStart` | `source` |
469
580
  | `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
581
+ | `SubagentStart` | `agent_id`, `agent_type`, `background`, `prompt` |
582
+
583
+ Inside a subagent, `PreToolUse`, `PostToolUse` and `SubagentStop` payloads also carry `agent_id` and `agent_type`.
470
584
 
471
585
  The environment adds `DOSTUFF_HOOK_EVENT`, `DOSTUFF_SESSION_ID`, `DOSTUFF_TURN_ID`, `DOSTUFF_PROJECT_ROOT` and
472
586
  `DOSTUFF_TURN_TYPE`. Output is capped at `loop.max_tool_output_chars`.
@@ -526,8 +640,8 @@ nesting are the same. Tool names and some argument names differ, so rename the m
526
640
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
527
641
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
528
642
 
529
- Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact`, `SessionEnd` and
530
- `SubagentStart` events.
643
+ Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
644
+ events.
531
645
 
532
646
  ---
533
647
 
@@ -562,7 +676,6 @@ models:
562
676
 
563
677
  loop:
564
678
  max_iterations: 100
565
- subagent_max_iterations: 25
566
679
  # context_window: 128000 # override when dostuff/litellm don't know the model
567
680
  max_tool_output_chars: 30000 # longer tool results keep head + tail
568
681
  max_retries: 6 # retries on rate limits, timeouts, 5xx (0 = none)
@@ -574,6 +687,12 @@ memory:
574
687
  permissions:
575
688
  mode: ask # ask | allowlist | auto | plan
576
689
  allow: []
690
+
691
+ agents: # see Subagents
692
+ max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
693
+ max_concurrent: 4
694
+ models:
695
+ fast: anthropic/claude-haiku-5-5
577
696
  ```
578
697
 
579
698
  See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-structure/dostuff/templates/config.example.yaml) for a full template. `dostuff setup` writes it for you.
@@ -885,7 +1004,9 @@ dostuff/
885
1004
  │ ├── web_fetch.py # read a URL as text
886
1005
  │ ├── web_search.py # free web search (SearXNG / ddgs / DuckDuckGo)
887
1006
  │ ├── todo_write.py # visible task list
888
- │ └── delegate_to_subagent.py # bounded subagents (optionally in a worktree)
1007
+ │ ├── agent.py # the agent tool (subagents: dostuff/agent/subagents/)
1008
+ │ ├── create_agent_type.py # write a new agent type file
1009
+ │ └── send_message.py, stop_agent.py # continue or stop an agent
889
1010
  ├── cli.py # CLI typer entrypoints and doctor checkup utilities
890
1011
  ├── cli_tui.py # Textual TUI Application and adapter translates state
891
1012
  ├── config.py # layered config loader supporting project/global yaml and multi-model configuration
@@ -5,7 +5,7 @@ from typing import Any
5
5
 
6
6
  from dostuff.config import get_config
7
7
  from dostuff.helpers.agent.constants import (
8
- BACKGROUND_WAIT_HEADLESS, BACKGROUND_WAIT_INTERACTIVE, MEMORY_INSTRUCTIONS, SYSTEM_INSTRUCTIONS,
8
+ AGENT_BACKGROUND, BACKGROUND_WAIT_HEADLESS, BACKGROUND_WAIT_INTERACTIVE, MEMORY_INSTRUCTIONS, SYSTEM_INSTRUCTIONS,
9
9
  )
10
10
  from dostuff.helpers.agent.environment_context import build_environment_block
11
11
  from dostuff.helpers.agent.load_identity import load_identity
@@ -23,25 +23,47 @@ def _background_wait(interactive: bool) -> str:
23
23
  return BACKGROUND_WAIT_INTERACTIVE if get_config().jobs_wake_on_end else ""
24
24
 
25
25
 
26
+ def skills_summary(skills: list[dict[str, Any]]) -> str:
27
+ """The skills list as the system prompt shows it."""
28
+ summary = "\n\n".join(
29
+ f"- name: {s['name']}\n description: {s['description']}\n location: {s['location']}"
30
+ for s in skills
31
+ )
32
+ return summary or "(none available)"
33
+
34
+
35
+ def project_instructions_section(cwd: Path | None = None) -> str:
36
+ """`## Project Instructions` + every applicable AGENTS.md / CLAUDE.md, or "" when there are none."""
37
+ project_instructions = load_project_instructions(cwd)
38
+ return "## Project Instructions\n" + project_instructions if project_instructions else ""
39
+
40
+
41
+ def agent_types_list() -> str:
42
+ """One ` - name: description` line per agent type, fork included (subagents spec D11, D13)."""
43
+ from dostuff.agent.subagents.definitions import current_definitions
44
+ from dostuff.agent.subagents.fork import FORK_DESCRIPTION, FORK_TYPE
45
+ descriptions = {name: d.description for name, d in current_definitions().types.items()}
46
+ descriptions[FORK_TYPE] = FORK_DESCRIPTION
47
+ return "\n".join(f" - {name}: {descriptions[name]}" for name in sorted(descriptions))
48
+
49
+
26
50
  def build_base_instructions(interactive: bool = False) -> tuple[str, list[dict[str, Any]]]:
27
51
  """(identity + skills + project instructions, the skills found). Built once per session.
28
52
 
29
53
  `interactive`: the TUI, which wakes the agent when a background job ends; headless doesn't.
30
54
  """
31
55
  skills = discover_skills()
32
- skills_summary = "\n\n".join(
33
- f"- name: {s['name']}\n description: {s['description']}\n location: {s['location']}"
34
- for s in skills
35
- )
36
56
  instructions = SYSTEM_INSTRUCTIONS.format(
37
57
  dostuff_identity=load_identity(),
38
- skills_summary=skills_summary or "(none available)",
58
+ skills_summary=skills_summary(skills),
39
59
  memory_section=MEMORY_INSTRUCTIONS if chroma.chroma_available() else "",
40
60
  background_wait=_background_wait(interactive),
61
+ agent_types=agent_types_list(),
62
+ agent_background=AGENT_BACKGROUND if interactive or get_config().agents_wake_on_end else "",
41
63
  )
42
- project_instructions = load_project_instructions()
43
- if project_instructions:
44
- instructions += "\n\n## Project Instructions\n" + project_instructions
64
+ project = project_instructions_section()
65
+ if project:
66
+ instructions += "\n\n" + project
45
67
  return instructions, skills
46
68
 
47
69