dostuff 0.2.3__tar.gz → 0.2.5__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 (143) hide show
  1. {dostuff-0.2.3 → dostuff-0.2.5}/PKG-INFO +264 -5
  2. {dostuff-0.2.3 → dostuff-0.2.5}/README.md +263 -4
  3. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/instructions.py +17 -3
  4. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/loop.py +96 -12
  5. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/permissions.py +34 -3
  6. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/run_tool.py +109 -13
  7. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/cli.py +6 -3
  8. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/cli_tui.py +732 -73
  9. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/config.py +50 -4
  10. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/headless.py +54 -1
  11. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/constants.py +18 -3
  12. dostuff-0.2.5/dostuff/helpers/hooks/__init__.py +10 -0
  13. dostuff-0.2.5/dostuff/helpers/hooks/dispatch.py +141 -0
  14. dostuff-0.2.5/dostuff/helpers/hooks/events.py +84 -0
  15. dostuff-0.2.5/dostuff/helpers/hooks/load_hooks.py +248 -0
  16. dostuff-0.2.5/dostuff/helpers/hooks/run_hook.py +186 -0
  17. dostuff-0.2.5/dostuff/helpers/hooks/trust.py +157 -0
  18. dostuff-0.2.5/dostuff/helpers/ui/doctor.py +191 -0
  19. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/templates/config.example.yaml +50 -2
  20. dostuff-0.2.5/dostuff/tools/bash/bash_command.py +227 -0
  21. dostuff-0.2.5/dostuff/tools/bash/bash_output.py +42 -0
  22. dostuff-0.2.5/dostuff/tools/bash/jobs.py +653 -0
  23. dostuff-0.2.5/dostuff/tools/bash/kill_shell.py +28 -0
  24. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/definitions.py +19 -1
  25. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/delegate_to_subagent.py +15 -4
  26. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/settings.py +13 -4
  27. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/PKG-INFO +264 -5
  28. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/SOURCES.txt +12 -0
  29. {dostuff-0.2.3 → dostuff-0.2.5}/pyproject.toml +1 -1
  30. dostuff-0.2.5/tests/test_bash_command.py +379 -0
  31. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_cli_commands.py +152 -0
  32. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_config_memory_mcp.py +9 -0
  33. dostuff-0.2.5/tests/test_hooks.py +1683 -0
  34. dostuff-0.2.5/tests/test_jobs.py +751 -0
  35. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_permissions.py +77 -0
  36. dostuff-0.2.5/tests/test_subagent.py +164 -0
  37. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_tool_schemas.py +1 -1
  38. dostuff-0.2.5/tests/test_tui.py +2330 -0
  39. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_worktree.py +1 -1
  40. dostuff-0.2.3/dostuff/helpers/ui/doctor.py +0 -47
  41. dostuff-0.2.3/dostuff/tools/bash/bash_command.py +0 -170
  42. dostuff-0.2.3/tests/test_subagent.py +0 -82
  43. dostuff-0.2.3/tests/test_tui.py +0 -1197
  44. {dostuff-0.2.3 → dostuff-0.2.5}/LICENSE +0 -0
  45. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/__init__.py +0 -0
  46. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/__main__.py +0 -0
  47. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/call_agent.py +0 -0
  48. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/append_step.py +0 -0
  49. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/consume_stream.py +0 -0
  50. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/context_usage.py +0 -0
  51. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/environment_context.py +0 -0
  52. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/file_mentions.py +0 -0
  53. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  54. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/load_identity.py +0 -0
  55. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  56. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  57. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/loop_emit.py +0 -0
  58. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/manage_context.py +0 -0
  59. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/model_cost.py +0 -0
  60. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/pastes.py +0 -0
  61. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/quick_memory.py +0 -0
  62. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  63. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/tool_output.py +0 -0
  64. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  65. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  66. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/server_config.py +0 -0
  67. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/token_store.py +0 -0
  68. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/memory/export_session.py +0 -0
  69. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  70. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/memory/shell_step.py +0 -0
  71. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/models/add_model_entry.py +0 -0
  72. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/models/list_models.py +0 -0
  73. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/models/opencode.py +0 -0
  74. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/skills/custom_commands.py +0 -0
  75. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/skills/discover_skills.py +0 -0
  76. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/skills/skill_command.py +0 -0
  77. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/diff.py +0 -0
  78. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  79. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/project_root.py +0 -0
  80. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  81. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/__init__.py +0 -0
  82. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/emit.py +0 -0
  83. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/prompt_history.py +0 -0
  84. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/terminal_signals.py +0 -0
  85. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/checkpoints.py +0 -0
  86. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/exceptions.py +0 -0
  87. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_client.py +0 -0
  88. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  89. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  90. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/chroma.py +0 -0
  91. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  92. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  93. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/session_store.py +0 -0
  94. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/stores.py +0 -0
  95. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/types.py +0 -0
  96. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/model.py +0 -0
  97. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/tracing.py +0 -0
  98. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/worktree.py +0 -0
  99. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/memory/__init__.py +0 -0
  100. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/setup_wizard.py +0 -0
  101. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/skills.py +0 -0
  102. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/templates/env.example +0 -0
  103. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/__init__.py +0 -0
  104. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/delete_file.py +0 -0
  105. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/edit_file.py +0 -0
  106. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/list_files.py +0 -0
  107. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/read_file.py +0 -0
  108. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/write_file.py +0 -0
  109. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/get_current_datetime.py +0 -0
  110. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  111. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  112. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  113. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/memory/save_episode.py +0 -0
  114. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/memory/save_memory.py +0 -0
  115. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/search/glob.py +0 -0
  116. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/search/grep.py +0 -0
  117. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/search/walk.py +0 -0
  118. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/todo_write.py +0 -0
  119. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/web_fetch.py +0 -0
  120. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/web_search.py +0 -0
  121. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/dependency_links.txt +0 -0
  122. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/entry_points.txt +0 -0
  123. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/requires.txt +0 -0
  124. {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/top_level.txt +0 -0
  125. {dostuff-0.2.3 → dostuff-0.2.5}/setup.cfg +0 -0
  126. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_checkpoints_todos_caching.py +0 -0
  127. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_file_mentions.py +0 -0
  128. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_file_tools.py +0 -0
  129. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_loop.py +0 -0
  130. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_mcp_e2e.py +0 -0
  131. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_mcp_oauth.py +0 -0
  132. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_opencode.py +0 -0
  133. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_optional_memory_and_instructions.py +0 -0
  134. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_pastes.py +0 -0
  135. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_roadmap_021.py +0 -0
  136. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_session_store.py +0 -0
  137. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_settings_tools.py +0 -0
  138. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_setup_wizard.py +0 -0
  139. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_skill_command.py +0 -0
  140. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_slash_suggestion.py +0 -0
  141. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_terminal_signals.py +0 -0
  142. {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_web_fetch.py +0 -0
  143. {dostuff-0.2.3 → dostuff-0.2.5}/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.3
3
+ Version: 0.2.5
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,6 +84,8 @@ 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)
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)
87
89
  - **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
88
90
  - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
89
91
  - **Subagents** — `delegate_to_subagent` runs a bounded task with a restricted tool set; its approval prompts and ESC go through the same TUI
@@ -203,7 +205,7 @@ In the TUI:
203
205
  | `dostuff sessions rm <id>... [-y]` | Delete sessions and their `/undo` checkpoints |
204
206
  | `dostuff sessions prune [--older-than 30d] [--dry-run] [-y]` | Delete empty sessions, and sessions not used for the given time (`45m`, `12h`, `30d`, `2w`) |
205
207
  | `dostuff export [<id>] [-o file\|-]` | Save a session (default: latest here) as Markdown: prompts, answers, tool calls and results |
206
- | `dostuff -p "<prompt>"` | Headless: run one prompt, print the answer to stdout, exit. Progress goes to stderr. Piped stdin is appended to the prompt (`-p -` reads the prompt from stdin). `--session <id>` continues a session, `--output-format json` (or `--json`) prints `{result, session_id, usage, ...}`, `--output-format stream-json` prints one JSON event per line (`init`, `assistant`, `tool_call`, `tool_result`, `usage`, `error`, then `result`), `-q` hides progress, `--permission-mode ask\|allowlist\|auto\|plan`. `--max-turns N` stops after N model calls (exit code 1). `--allowed-tools` (comma-separated or repeated) runs matching calls without asking in any mode, in the `permissions.allow` syntax (`"npm test"`, `web_fetch:docs.python.org`) or a tool name for every call of it (`write_file`, `bash_command`). Without a terminal, other calls that need approval are denied |
208
+ | `dostuff -p "<prompt>"` | Headless: run one prompt, print the answer to stdout, exit. Progress goes to stderr. Piped stdin is appended to the prompt (`-p -` reads the prompt from stdin). `--session <id>` continues a session, `--output-format json` (or `--json`) prints `{result, session_id, usage, ...}`, `--output-format stream-json` prints one JSON event per line (`init`, `assistant`, `tool_call`, `tool_result`, `usage`, `error`, then `result`), `-q` hides progress, `--permission-mode ask\|allowlist\|auto\|plan`. `--max-turns N` stops after N model calls (exit code 1). `--allowed-tools` (comma-separated or repeated) runs matching calls without asking in any mode, in the `permissions.allow` syntax (`"npm test"`, `web_fetch:docs.python.org`) or a tool name for every call of it (`write_file`, `bash_command`). Without a terminal, other calls that need approval are denied. `--trust-project-hooks` runs the project's [hooks](#project-hooks-and-trust) without a saved trust answer |
207
209
  | `dostuff mcp list` | Show MCP servers and the file each comes from |
208
210
  | `dostuff mcp add <name> [-e K=V] -- <command> [args...]` | Add a stdio server; `--url <url> [-H "Name: value"]` for HTTP; `--project` writes `./.dostuff/mcp_config.json` |
209
211
  | `dostuff mcp remove <name> [--project]` | Remove a server |
@@ -228,6 +230,7 @@ In the TUI:
228
230
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
229
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 |
230
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) |
231
234
  | `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
232
235
  | `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
233
236
  | `/exit` | Save the session and quit |
@@ -243,7 +246,10 @@ In the TUI:
243
246
  | `/status` | Session, directory, model, permission mode, tokens, context use, MCP servers |
244
247
  | `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
245
248
  | `/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 |
246
- | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory), with a fix for each problem |
249
+ | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
250
+ | `/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
+ | `/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
+ | `/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) |
247
253
  | `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
248
254
  | `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
249
255
  | `/rename <title>` | Name this session (shown by `dostuff sessions`) |
@@ -265,7 +271,9 @@ In the TUI:
265
271
  - **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
266
272
  - **Errors** — red background
267
273
  - **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
274
+ - **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
268
275
  - **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
276
+ - **Queued prompts** — prompts sent while a turn runs wait above the input, one row each, and run in order. Click the list (or `/queue`) to pick one and edit it (back into the input), run it next or remove it, or clear them all (`/queue clear`). `Esc` cancels the turn and moves the queued prompts back into the input instead of running them
269
277
  - **Terminal title** — the tab / window title shows the run status: `⏳ dostuff · <folder>` while working, `✋` while an approval waits, `✓` when done; the old title comes back on exit. `ui.terminal_title: false` turns it off
270
278
  - **Notifications** (off by default) — `ui.notifications: bell` (terminal bell) or `osc9` (desktop notification in iTerm2, WezTerm, Ghostty, kitty …) when a turn finishes or an approval is waiting, if it took longer than `ui.notify_after_seconds` (30) or the terminal is in the background. `/notifications` switches it per session
271
279
 
@@ -276,6 +284,7 @@ In the TUI:
276
284
  | Tool | Kind | Asks? |
277
285
  | ---- | ---- | ----- |
278
286
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
287
+ | `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
279
288
  | `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
280
289
  | `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 |
281
290
  | `call_mcp_tool` | mcp | yes |
@@ -285,6 +294,11 @@ In the TUI:
285
294
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
286
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) |
287
296
 
297
+ File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
298
+ settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
299
+ into subagent worktrees (`.dostuff/worktrees/…`) are exempt. The shell check matches the text `.dostuff`, so a name the
300
+ command builds indirectly is not caught.
301
+
288
302
  `permissions.mode` in `config.yaml`:
289
303
 
290
304
  - `ask` (default) — as in the table above.
@@ -314,12 +328,257 @@ API keys stay in `.env` files, which the agent can't read or change. Subagents d
314
328
 
315
329
  > [!NOTE]
316
330
  > **Cancelling a running tool.** ESC stops waiting for tools at once and the turn ends; results that already
317
- > finished are kept. Tools that run in a worker thread (file tools, `bash_command`) cannot be interrupted
318
- > mid-call, so one that was still running may finish in the background; its result is recorded as
331
+ > finished are kept. A running `bash_command` is killed with its children; tools that run in a worker thread (file tools) cannot
332
+ > be interrupted mid-call, so one that was still running may finish in the background; its result is recorded as
319
333
  > `Cancelled by user (may still be running)`.
320
334
 
321
335
  ---
322
336
 
337
+ ## Background jobs
338
+
339
+ Dev servers, file watchers and long test runs don't fit a shell call that has to finish within its timeout. The agent
340
+ starts them as **background jobs** instead and keeps working while they run:
341
+
342
+ | Tool | What it does |
343
+ |---|---|
344
+ | `bash_command(command, run_in_background=true, background_id="dev")` | Starts the job and returns at once with its id, pid and log files. `background_id` is optional (`bg-1`, `bg-2`, … otherwise); starting an id that is still running is refused. At most 8 running jobs per agent |
345
+ | `bash_output("dev", filter=…, wait_for=…, timeout=…)` | The job's status and the stdout / stderr it printed since the last read. `wait_for` is a regex: wait (1–110 s) until a new line matches, e.g. a server's `ready` line, instead of sleeping. `filter` keeps only matching lines |
346
+ | `kill_shell("dev")` | Kills the job and everything it started, and shows its last lines |
347
+
348
+ The approval prompt for a background start reads `Run shell command (background job "dev"):`; `bash_output` and
349
+ `kill_shell` never ask, because they only reach the calling agent's own jobs. Hooks see `run_in_background` and
350
+ `background_id` in `PreToolUse`, and can deny `kill_shell` like any tool. Plan mode allows a background job only for a
351
+ read-only command.
352
+
353
+ **When a job ends** on its own (or you stop it with `/jobs kill`), the agent is told before its next model call with a
354
+ `<background-job id="test" status="exited" code="1" runtime="42s">` message holding the last 20 lines of each stream,
355
+ so it doesn't have to poll to notice a crashed server. In the TUI the same moment shows as `⚙ job "test" exited (1)
356
+ after 42s`, with a notification when the terminal is in the background (`ui.notifications`). If the agent is idle,
357
+ the TUI starts a turn for it right away (`⚙ Resuming the agent: …`), so it can look at the failed test run or crashed
358
+ server on its own. It waits while you are typing, an approval is open or a command like `/compact` runs; if you send a
359
+ prompt first, that turn gets the message instead. A `/jobs kill` alone doesn't wake it, and after 3 such automatic
360
+ turns in a row it waits for your next message. Turn this off with `jobs: {wake_on_end: false}` in `config.yaml`; the
361
+ agent then sees the message with your next prompt.
362
+
363
+ **In the TUI:**
364
+
365
+ - `Ctrl+B` while the agent waits on a shell command (the loader says `Ctrl+B to background`) moves that command, and
366
+ any a subagent is running in the same turn, to the background. The agent gets what it printed so far and carries on;
367
+ the transcript shows `⎿ moved to background as "bg-3"`. `!command`s can't be backgrounded.
368
+ - `/jobs` lists the session's jobs: id, owner (`main` or `subagent: <role>`), status, runtime and command.
369
+ `/jobs <id>` shows the last 40 lines of each stream and the log paths, `/jobs kill <id>` stops one.
370
+ - While any run, a `⚙ 2 shells` item shows at the end of the status bar; click it (or `↓` in an empty input) to pick a job
371
+ from a list (status, start time, runtime, command) and show its output or stop it.
372
+
373
+ **Logs** go to `~/.dostuff/jobs/<session>/<job>.out` and `.err` (you can `tail -f` them; `/jobs <id>` prints the
374
+ paths). Directories older than 7 days are removed at startup.
375
+
376
+ **Jobs live until their owner ends; in the TUI that is the app, not the conversation:**
377
+
378
+ | Event | What happens to the jobs |
379
+ |---|---|
380
+ | Subagent run ends (done, error or cancelled) | its jobs are killed |
381
+ | `/compact` | kept |
382
+ | `/clear` | kept, no prompt: they move to the new session, which gets their end notices and can use `bash_output`/`kill_shell` on them |
383
+ | `/resume` another session | same as `/clear`: the running jobs follow you into the resumed session |
384
+ | Quit (`Ctrl+Q`, `/exit`) | "Quit and stop 2 background jobs?", then they are killed |
385
+ | Headless run (`dostuff -p`) ends, or `Ctrl+C` | all killed, one stderr line each (`stream-json`: `{"type": "job", …}` events) |
386
+
387
+ > [!WARNING]
388
+ > If DoStuff is killed hard (task manager, `kill -9`, power loss), its jobs keep running: they are detached from the
389
+ > terminal by design. Each session records its jobs in `~/.dostuff/jobs/<session>/jobs.json`, and the next start
390
+ > warns `1 background job from an earlier session may still be running (npm run dev, pid 4812)`. It doesn't kill
391
+ > them, since a pid may have been reused by then; check with your OS tools.
392
+
393
+ ---
394
+
395
+ ## Hooks
396
+
397
+ Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
398
+ to the model, keep the turn going until the tests pass. They are configured under `hooks:` in `config.yaml` and use
399
+ Claude Code's I/O contract (stdin JSON, exit codes, JSON output), so an existing Claude Code hook script works once its
400
+ matcher and tool argument names are renamed (see [the table below](#coming-from-claude-code)).
401
+
402
+ > [!WARNING]
403
+ > Hooks run with your privileges, **unsandboxed**, and are not permission-checked: they are your config, not model
404
+ > output. Read a project's hooks before you trust them.
405
+
406
+ | Event | When | Matcher is matched against | What a hook can do |
407
+ |---|---|---|---|
408
+ | `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 |
409
+ | `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context for this turn |
410
+ | `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
411
+ | `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
412
+ | `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 |
414
+
415
+ ### Config
416
+
417
+ `matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
418
+ matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
419
+ 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
420
+ the example from the spec, and the two scripts it runs are below:
421
+
422
+ ```yaml
423
+ hooks:
424
+ project_trust: ask # ask | allow | deny (D4) — only read from ~/.dostuff/config.yaml
425
+ stop_block_limit: 3 # Stop blocks honoured per turn before the loop is allowed to end (1–10)
426
+ SessionStart:
427
+ - matcher: "startup|resume|clear" # regex, full match against the source; empty or "*" = all
428
+ hooks:
429
+ - type: command
430
+ command: "git status --short"
431
+ PreToolUse:
432
+ - matcher: "bash_command" # regex, full match against the tool name
433
+ if: "(?i)^\\s*git\\s+push" # optional regex, searched in tool_input.command (shell tool only)
434
+ fail_closed: true
435
+ timeout: 10
436
+ hooks:
437
+ - type: command
438
+ name: block-main-push
439
+ command: "python .dostuff/hooks/block_main_push.py"
440
+ PostToolUse:
441
+ - matcher: "write_file|edit_file"
442
+ hooks:
443
+ # the script reads tool_input.path from the stdin JSON and runs the formatter on it;
444
+ # its stdout is fed back to the model (D5)
445
+ - type: command
446
+ name: format
447
+ command: "python .dostuff/hooks/format_file.py"
448
+ Stop:
449
+ - hooks:
450
+ - { type: command, name: tests, command: "python .dostuff/hooks/run_tests.py" }
451
+ ```
452
+
453
+ - **`fail_closed: true`** (`PreToolUse` and `UserPromptSubmit` only) is for guardrails: if the hook crashes or times
454
+ out, the call is denied (or the prompt rejected) instead of going ahead. A `fail_closed` hook with a config mistake,
455
+ such as a bad regex, is kept and denies everything it matches; any other invalid hook is dropped with a warning.
456
+ - **`stop_block_limit`** (1–10) bounds how many times `Stop` hooks can continue one turn; after that the turn ends with
457
+ a note.
458
+ - User hooks come first, then the project's are added after them; a project file can't remove or reorder yours.
459
+
460
+ ```python
461
+ # .dostuff/hooks/block_main_push.py: PreToolUse on bash_command; the group's `if` already matched `git push`
462
+ import json
463
+ import subprocess
464
+ import sys
465
+
466
+ payload = json.load(sys.stdin)
467
+ words = payload["tool_input"].get("command", "").replace(":", " ").split()
468
+ branch = subprocess.run(["git", "branch", "--show-current"], capture_output=True, text=True,
469
+ cwd=payload["cwd"]).stdout.strip()
470
+ if "main" in words or branch == "main":
471
+ print("Don't push to main: push a feature branch and open a pull request.", file=sys.stderr)
472
+ sys.exit(2) # exit 2 = deny; stderr is the reason the model sees
473
+ ```
474
+
475
+ ```python
476
+ # .dostuff/hooks/format_file.py: PostToolUse on write_file|edit_file; stdout is appended to the tool result
477
+ import json
478
+ import subprocess
479
+ import sys
480
+
481
+ payload = json.load(sys.stdin)
482
+ path = payload["tool_input"].get("path", "")
483
+ if path.endswith(".py"):
484
+ result = subprocess.run(["ruff", "format", path], capture_output=True, text=True, cwd=payload["cwd"])
485
+ print((result.stdout + result.stderr).strip())
486
+ ```
487
+
488
+ ```python
489
+ # .dostuff/hooks/run_tests.py: Stop; exit 2 sends the failures back and the turn continues
490
+ import json
491
+ import subprocess
492
+ import sys
493
+
494
+ payload = json.load(sys.stdin)
495
+ result = subprocess.run([sys.executable, "-m", "pytest", "-q", "-x"], capture_output=True, text=True,
496
+ cwd=payload["cwd"])
497
+ if result.returncode not in (0, 5): # 5: no tests collected
498
+ print("Tests fail; fix them before finishing:\n" + result.stdout[-3000:], file=sys.stderr)
499
+ sys.exit(2)
500
+ ```
501
+
502
+ ### Input and output
503
+
504
+ Each hook runs through the same shell as `bash_command`, in the project directory (a worktree subagent's own
505
+ worktree), with no terminal. stdin is one JSON object:
506
+
507
+ ```json
508
+ {"hook_event_name": "PreToolUse", "session_id": "…", "turn_id": "…", "cwd": "…", "turn_type": "interactive_loop",
509
+ "tool_name": "bash_command", "tool_input": {"command": "git push origin main"}, "tool_use_id": "…"}
510
+ ```
511
+
512
+ | Event | Extra keys |
513
+ |---|---|
514
+ | `PreToolUse`, `PostToolUse` | `tool_name`, `tool_input`, `tool_use_id`; `PostToolUse` also `tool_response` (the result, already truncated) |
515
+ | `UserPromptSubmit` | `prompt` |
516
+ | `SessionStart` | `source` |
517
+ | `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
518
+
519
+ The environment adds `DOSTUFF_HOOK_EVENT`, `DOSTUFF_SESSION_ID`, `DOSTUFF_TURN_ID`, `DOSTUFF_PROJECT_ROOT` and
520
+ `DOSTUFF_TURN_TYPE`. Output is capped at `loop.max_tool_output_chars`.
521
+
522
+ | Exit code | Meaning |
523
+ |---|---|
524
+ | `0` | Success. Plain stdout is context (`SessionStart`, `UserPromptSubmit`, `PostToolUse`); JSON on stdout can carry a decision (below) |
525
+ | `2` | Block. stderr (or stdout) is the reason: `PreToolUse` denies the call, `PostToolUse` appends it to the result, `UserPromptSubmit` rejects the prompt, `Stop` continues the turn |
526
+ | other | The hook failed: an error line in the transcript, and the run goes on (unless `fail_closed`) |
527
+
528
+ JSON on stdout (exit 0), in either Claude Code spelling:
529
+
530
+ ```json
531
+ {"decision": "block", "reason": "…"}
532
+ {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow|deny|ask",
533
+ "permissionDecisionReason": "…", "updatedInput": {"command": "…"},
534
+ "additionalContext": "…"}}
535
+ ```
536
+
537
+ When several hooks match, they run one after another, each on the original input: the strictest decision wins
538
+ (`deny` > `ask` > `allow`), contexts are joined in config order, and the last `updatedInput` wins. Plan mode still
539
+ applies: a hook `allow` never runs a call plan mode refused, and settings changes still ask. Rewritten arguments are
540
+ checked again, so a rewrite can't skip the prompt the new call needs. Each hook's effect shows in the transcript as a
541
+ line like `⚓ PreToolUse bash_command → deny (reason)` (a `hook` event in `--output-format stream-json`). ESC kills a
542
+ running hook.
543
+
544
+ ### Project hooks and trust
545
+
546
+ Hooks in `./.dostuff/config.yaml` come with the repo, so they are code from whoever wrote it. They run only once you
547
+ trust them, set by `hooks.project_trust` in **`~/.dostuff/config.yaml`** (a project file can't set it):
548
+
549
+ - `ask` (default): before the first project hook would run, the TUI lists every project hook's command and file and
550
+ asks. A yes is saved in `~/.dostuff/trusted_hooks.json` for that project, until the hooks block or any file in
551
+ `.dostuff/hooks/` changes; then it asks again. A no skips them for the session.
552
+ - `allow` runs them without asking; `deny` never runs them.
553
+ - Headless (`dostuff -p`) can't ask: it honours a saved yes, runs them with `--trust-project-hooks`, and otherwise
554
+ skips them with a warning. If a skipped hook is `fail_closed`, it refuses to start (exit code 2) instead.
555
+
556
+ Keep hook scripts in `.dostuff/hooks/`: trust covers the files there, and the model can't edit anything under
557
+ `.dostuff/` without a settings prompt. A script elsewhere in the repo can be changed after you trusted it.
558
+
559
+ `/hooks` lists every hook per event with its file, matcher, timeout, `fail_closed` and whether it runs (`user`,
560
+ `trusted`, `untrusted`, `disabled` or `broken`); `/hooks r` re-reads the config files. `dostuff doctor` reports
561
+ invalid hooks, commands not found on `PATH` and project scripts outside `.dostuff/hooks/`.
562
+
563
+ ### Coming from Claude Code
564
+
565
+ The stdin envelope, exit codes, JSON output, event names and the `matcher` + `hooks: [{type: command, command}]`
566
+ nesting are the same. Tool names and some argument names differ, so rename the matcher and any `tool_input` keys:
567
+
568
+ | Claude Code | DoStuff `tool_name` | `tool_input` keys that differ |
569
+ |---|---|---|
570
+ | `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
571
+ | `Write` | `write_file` | `file_path` → `path` |
572
+ | `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
573
+ | `Read` | `read_file` | `file_path` → `path` |
574
+ | `Grep` / `Glob` | `grep` / `glob` | per tool |
575
+ | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
576
+
577
+ Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact`, `SessionEnd` and
578
+ `SubagentStart` events.
579
+
580
+ ---
581
+
323
582
  ## Configuration
324
583
 
325
584
  Config is layered, with later sources overriding earlier ones: