dostuff 0.2.4__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 (141) hide show
  1. {dostuff-0.2.4 → dostuff-0.2.5}/PKG-INFO +68 -3
  2. {dostuff-0.2.4 → dostuff-0.2.5}/README.md +67 -2
  3. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/agent/instructions.py +17 -3
  4. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/agent/loop.py +33 -6
  5. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/agent/permissions.py +4 -1
  6. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/agent/run_tool.py +9 -3
  7. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/cli_tui.py +668 -71
  8. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/config.py +36 -2
  9. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/headless.py +18 -0
  10. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/constants.py +17 -3
  11. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/hooks/dispatch.py +4 -2
  12. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/templates/config.example.yaml +10 -2
  13. dostuff-0.2.5/dostuff/tools/bash/bash_command.py +227 -0
  14. dostuff-0.2.5/dostuff/tools/bash/bash_output.py +42 -0
  15. dostuff-0.2.5/dostuff/tools/bash/jobs.py +653 -0
  16. dostuff-0.2.5/dostuff/tools/bash/kill_shell.py +28 -0
  17. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/definitions.py +19 -1
  18. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/delegate_to_subagent.py +11 -3
  19. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/settings.py +3 -3
  20. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff.egg-info/PKG-INFO +68 -3
  21. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff.egg-info/SOURCES.txt +5 -0
  22. {dostuff-0.2.4 → dostuff-0.2.5}/pyproject.toml +1 -1
  23. dostuff-0.2.5/tests/test_bash_command.py +379 -0
  24. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_cli_commands.py +53 -0
  25. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_config_memory_mcp.py +9 -0
  26. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_hooks.py +82 -0
  27. dostuff-0.2.5/tests/test_jobs.py +751 -0
  28. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_permissions.py +52 -0
  29. dostuff-0.2.5/tests/test_subagent.py +164 -0
  30. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_tool_schemas.py +1 -1
  31. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_tui.py +819 -0
  32. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_worktree.py +1 -1
  33. dostuff-0.2.4/dostuff/tools/bash/bash_command.py +0 -170
  34. dostuff-0.2.4/tests/test_subagent.py +0 -82
  35. {dostuff-0.2.4 → dostuff-0.2.5}/LICENSE +0 -0
  36. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/__init__.py +0 -0
  37. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/__main__.py +0 -0
  38. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/agent/call_agent.py +0 -0
  39. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/cli.py +0 -0
  40. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/append_step.py +0 -0
  41. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/consume_stream.py +0 -0
  42. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/context_usage.py +0 -0
  43. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/environment_context.py +0 -0
  44. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/file_mentions.py +0 -0
  45. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  46. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/load_identity.py +0 -0
  47. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  48. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  49. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/loop_emit.py +0 -0
  50. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/manage_context.py +0 -0
  51. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/model_cost.py +0 -0
  52. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/pastes.py +0 -0
  53. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/quick_memory.py +0 -0
  54. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  55. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/agent/tool_output.py +0 -0
  56. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/hooks/__init__.py +0 -0
  57. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/hooks/events.py +0 -0
  58. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/hooks/load_hooks.py +0 -0
  59. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/hooks/run_hook.py +0 -0
  60. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/hooks/trust.py +0 -0
  61. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  62. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  63. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/mcp/server_config.py +0 -0
  64. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/mcp/token_store.py +0 -0
  65. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/memory/export_session.py +0 -0
  66. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  67. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/memory/shell_step.py +0 -0
  68. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/models/add_model_entry.py +0 -0
  69. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/models/list_models.py +0 -0
  70. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/models/opencode.py +0 -0
  71. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/skills/custom_commands.py +0 -0
  72. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/skills/discover_skills.py +0 -0
  73. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/skills/skill_command.py +0 -0
  74. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/tools/diff.py +0 -0
  75. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  76. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/tools/project_root.py +0 -0
  77. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  78. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/ui/__init__.py +0 -0
  79. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/ui/doctor.py +0 -0
  80. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/ui/emit.py +0 -0
  81. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/ui/prompt_history.py +0 -0
  82. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/helpers/ui/terminal_signals.py +0 -0
  83. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/checkpoints.py +0 -0
  84. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/exceptions.py +0 -0
  85. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_client.py +0 -0
  86. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  87. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  88. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/memory/chroma.py +0 -0
  89. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  90. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  91. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/memory/session_store.py +0 -0
  92. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/memory/stores.py +0 -0
  93. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/memory/types.py +0 -0
  94. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/model.py +0 -0
  95. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/tracing.py +0 -0
  96. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/lib/worktree.py +0 -0
  97. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/memory/__init__.py +0 -0
  98. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/setup_wizard.py +0 -0
  99. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/skills.py +0 -0
  100. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/templates/env.example +0 -0
  101. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/__init__.py +0 -0
  102. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/files/delete_file.py +0 -0
  103. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/files/edit_file.py +0 -0
  104. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/files/list_files.py +0 -0
  105. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/files/read_file.py +0 -0
  106. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/files/write_file.py +0 -0
  107. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/get_current_datetime.py +0 -0
  108. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  109. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  110. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  111. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/memory/save_episode.py +0 -0
  112. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/memory/save_memory.py +0 -0
  113. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/search/glob.py +0 -0
  114. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/search/grep.py +0 -0
  115. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/search/walk.py +0 -0
  116. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/todo_write.py +0 -0
  117. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/web_fetch.py +0 -0
  118. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff/tools/web_search.py +0 -0
  119. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff.egg-info/dependency_links.txt +0 -0
  120. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff.egg-info/entry_points.txt +0 -0
  121. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff.egg-info/requires.txt +0 -0
  122. {dostuff-0.2.4 → dostuff-0.2.5}/dostuff.egg-info/top_level.txt +0 -0
  123. {dostuff-0.2.4 → dostuff-0.2.5}/setup.cfg +0 -0
  124. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_checkpoints_todos_caching.py +0 -0
  125. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_file_mentions.py +0 -0
  126. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_file_tools.py +0 -0
  127. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_loop.py +0 -0
  128. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_mcp_e2e.py +0 -0
  129. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_mcp_oauth.py +0 -0
  130. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_opencode.py +0 -0
  131. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_optional_memory_and_instructions.py +0 -0
  132. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_pastes.py +0 -0
  133. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_roadmap_021.py +0 -0
  134. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_session_store.py +0 -0
  135. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_settings_tools.py +0 -0
  136. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_setup_wizard.py +0 -0
  137. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_skill_command.py +0 -0
  138. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_slash_suggestion.py +0 -0
  139. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_terminal_signals.py +0 -0
  140. {dostuff-0.2.4 → dostuff-0.2.5}/tests/test_web_fetch.py +0 -0
  141. {dostuff-0.2.4 → 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.4
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
@@ -85,6 +85,7 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
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
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)
88
89
  - **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
89
90
  - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
90
91
  - **Subagents** — `delegate_to_subagent` runs a bounded task with a restricted tool set; its approval prompts and ESC go through the same TUI
@@ -229,6 +230,7 @@ In the TUI:
229
230
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
230
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 |
231
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) |
232
234
  | `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
233
235
  | `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
234
236
  | `/exit` | Save the session and quit |
@@ -246,6 +248,8 @@ In the TUI:
246
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 |
247
249
  | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
248
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) |
249
253
  | `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
250
254
  | `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
251
255
  | `/rename <title>` | Name this session (shown by `dostuff sessions`) |
@@ -267,7 +271,9 @@ In the TUI:
267
271
  - **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
268
272
  - **Errors** — red background
269
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
270
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
271
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
272
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
273
279
 
@@ -278,6 +284,7 @@ In the TUI:
278
284
  | Tool | Kind | Asks? |
279
285
  | ---- | ---- | ----- |
280
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) |
281
288
  | `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
282
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 |
283
290
  | `call_mcp_tool` | mcp | yes |
@@ -321,12 +328,70 @@ API keys stay in `.env` files, which the agent can't read or change. Subagents d
321
328
 
322
329
  > [!NOTE]
323
330
  > **Cancelling a running tool.** ESC stops waiting for tools at once and the turn ends; results that already
324
- > finished are kept. Tools that run in a worker thread (file tools, `bash_command`) cannot be interrupted
325
- > 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
326
333
  > `Cancelled by user (may still be running)`.
327
334
 
328
335
  ---
329
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
+
330
395
  ## Hooks
331
396
 
332
397
  Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
@@ -37,6 +37,7 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
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
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)
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)
40
41
  - **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
41
42
  - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
42
43
  - **Subagents** — `delegate_to_subagent` runs a bounded task with a restricted tool set; its approval prompts and ESC go through the same TUI
@@ -181,6 +182,7 @@ In the TUI:
181
182
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
182
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 |
183
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) |
184
186
  | `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
185
187
  | `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
186
188
  | `/exit` | Save the session and quit |
@@ -198,6 +200,8 @@ In the TUI:
198
200
  | `/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 |
199
201
  | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
200
202
  | `/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
+ | `/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
+ | `/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) |
201
205
  | `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
202
206
  | `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
203
207
  | `/rename <title>` | Name this session (shown by `dostuff sessions`) |
@@ -219,7 +223,9 @@ In the TUI:
219
223
  - **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
220
224
  - **Errors** — red background
221
225
  - **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
226
+ - **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
222
227
  - **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
228
+ - **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
223
229
  - **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
224
230
  - **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
225
231
 
@@ -230,6 +236,7 @@ In the TUI:
230
236
  | Tool | Kind | Asks? |
231
237
  | ---- | ---- | ----- |
232
238
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
239
+ | `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
233
240
  | `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
234
241
  | `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 |
235
242
  | `call_mcp_tool` | mcp | yes |
@@ -273,12 +280,70 @@ API keys stay in `.env` files, which the agent can't read or change. Subagents d
273
280
 
274
281
  > [!NOTE]
275
282
  > **Cancelling a running tool.** ESC stops waiting for tools at once and the turn ends; results that already
276
- > finished are kept. Tools that run in a worker thread (file tools, `bash_command`) cannot be interrupted
277
- > mid-call, so one that was still running may finish in the background; its result is recorded as
283
+ > finished are kept. A running `bash_command` is killed with its children; tools that run in a worker thread (file tools) cannot
284
+ > be interrupted mid-call, so one that was still running may finish in the background; its result is recorded as
278
285
  > `Cancelled by user (may still be running)`.
279
286
 
280
287
  ---
281
288
 
289
+ ## Background jobs
290
+
291
+ Dev servers, file watchers and long test runs don't fit a shell call that has to finish within its timeout. The agent
292
+ starts them as **background jobs** instead and keeps working while they run:
293
+
294
+ | Tool | What it does |
295
+ |---|---|
296
+ | `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 |
297
+ | `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 |
298
+ | `kill_shell("dev")` | Kills the job and everything it started, and shows its last lines |
299
+
300
+ The approval prompt for a background start reads `Run shell command (background job "dev"):`; `bash_output` and
301
+ `kill_shell` never ask, because they only reach the calling agent's own jobs. Hooks see `run_in_background` and
302
+ `background_id` in `PreToolUse`, and can deny `kill_shell` like any tool. Plan mode allows a background job only for a
303
+ read-only command.
304
+
305
+ **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
306
+ `<background-job id="test" status="exited" code="1" runtime="42s">` message holding the last 20 lines of each stream,
307
+ so it doesn't have to poll to notice a crashed server. In the TUI the same moment shows as `⚙ job "test" exited (1)
308
+ after 42s`, with a notification when the terminal is in the background (`ui.notifications`). If the agent is idle,
309
+ the TUI starts a turn for it right away (`⚙ Resuming the agent: …`), so it can look at the failed test run or crashed
310
+ server on its own. It waits while you are typing, an approval is open or a command like `/compact` runs; if you send a
311
+ prompt first, that turn gets the message instead. A `/jobs kill` alone doesn't wake it, and after 3 such automatic
312
+ turns in a row it waits for your next message. Turn this off with `jobs: {wake_on_end: false}` in `config.yaml`; the
313
+ agent then sees the message with your next prompt.
314
+
315
+ **In the TUI:**
316
+
317
+ - `Ctrl+B` while the agent waits on a shell command (the loader says `Ctrl+B to background`) moves that command, and
318
+ any a subagent is running in the same turn, to the background. The agent gets what it printed so far and carries on;
319
+ the transcript shows `⎿ moved to background as "bg-3"`. `!command`s can't be backgrounded.
320
+ - `/jobs` lists the session's jobs: id, owner (`main` or `subagent: <role>`), status, runtime and command.
321
+ `/jobs <id>` shows the last 40 lines of each stream and the log paths, `/jobs kill <id>` stops one.
322
+ - 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
323
+ from a list (status, start time, runtime, command) and show its output or stop it.
324
+
325
+ **Logs** go to `~/.dostuff/jobs/<session>/<job>.out` and `.err` (you can `tail -f` them; `/jobs <id>` prints the
326
+ paths). Directories older than 7 days are removed at startup.
327
+
328
+ **Jobs live until their owner ends; in the TUI that is the app, not the conversation:**
329
+
330
+ | Event | What happens to the jobs |
331
+ |---|---|
332
+ | Subagent run ends (done, error or cancelled) | its jobs are killed |
333
+ | `/compact` | kept |
334
+ | `/clear` | kept, no prompt: they move to the new session, which gets their end notices and can use `bash_output`/`kill_shell` on them |
335
+ | `/resume` another session | same as `/clear`: the running jobs follow you into the resumed session |
336
+ | Quit (`Ctrl+Q`, `/exit`) | "Quit and stop 2 background jobs?", then they are killed |
337
+ | Headless run (`dostuff -p`) ends, or `Ctrl+C` | all killed, one stderr line each (`stream-json`: `{"type": "job", …}` events) |
338
+
339
+ > [!WARNING]
340
+ > If DoStuff is killed hard (task manager, `kill -9`, power loss), its jobs keep running: they are detached from the
341
+ > terminal by design. Each session records its jobs in `~/.dostuff/jobs/<session>/jobs.json`, and the next start
342
+ > warns `1 background job from an earlier session may still be running (npm run dev, pid 4812)`. It doesn't kill
343
+ > them, since a pid may have been reused by then; check with your OS tools.
344
+
345
+ ---
346
+
282
347
  ## Hooks
283
348
 
284
349
  Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
@@ -4,7 +4,9 @@ from pathlib import Path
4
4
  from typing import Any
5
5
 
6
6
  from dostuff.config import get_config
7
- from dostuff.helpers.agent.constants import MEMORY_INSTRUCTIONS, SYSTEM_INSTRUCTIONS
7
+ from dostuff.helpers.agent.constants import (
8
+ BACKGROUND_WAIT_HEADLESS, BACKGROUND_WAIT_INTERACTIVE, MEMORY_INSTRUCTIONS, SYSTEM_INSTRUCTIONS,
9
+ )
8
10
  from dostuff.helpers.agent.environment_context import build_environment_block
9
11
  from dostuff.helpers.agent.load_identity import load_identity
10
12
  from dostuff.helpers.agent.load_project_instructions import load_project_instructions
@@ -13,8 +15,19 @@ from dostuff.helpers.ui.emit import emit
13
15
  from dostuff.lib.memory import chroma
14
16
 
15
17
 
16
- def build_base_instructions() -> tuple[str, list[dict[str, Any]]]:
17
- """(identity + skills + project instructions, the skills found). Built once per session."""
18
+ def _background_wait(interactive: bool) -> str:
19
+ """How to wait for a background job: the TUI resumes the agent when one ends (unless
20
+ jobs.wake_on_end is off, then nothing is said); headless kills them at the end of the run."""
21
+ if not interactive:
22
+ return BACKGROUND_WAIT_HEADLESS
23
+ return BACKGROUND_WAIT_INTERACTIVE if get_config().jobs_wake_on_end else ""
24
+
25
+
26
+ def build_base_instructions(interactive: bool = False) -> tuple[str, list[dict[str, Any]]]:
27
+ """(identity + skills + project instructions, the skills found). Built once per session.
28
+
29
+ `interactive`: the TUI, which wakes the agent when a background job ends; headless doesn't.
30
+ """
18
31
  skills = discover_skills()
19
32
  skills_summary = "\n\n".join(
20
33
  f"- name: {s['name']}\n description: {s['description']}\n location: {s['location']}"
@@ -24,6 +37,7 @@ def build_base_instructions() -> tuple[str, list[dict[str, Any]]]:
24
37
  dostuff_identity=load_identity(),
25
38
  skills_summary=skills_summary or "(none available)",
26
39
  memory_section=MEMORY_INSTRUCTIONS if chroma.chroma_available() else "",
40
+ background_wait=_background_wait(interactive),
27
41
  )
28
42
  project_instructions = load_project_instructions()
29
43
  if project_instructions:
@@ -26,7 +26,9 @@ from dostuff.helpers.hooks.events import (
26
26
  from dostuff.helpers.hooks.run_hook import payload_for
27
27
  from dostuff.config import AUTO_COMPACT_THRESHOLD, get_config
28
28
  from dostuff.tools.definitions import TOOL_MAP
29
- from typing import Any, Literal
29
+ from dostuff.tools.bash.jobs import Job, JobEvent, format_notice, get_registry
30
+ from typing import Any, Iterator, Literal
31
+ import contextlib
30
32
  import json
31
33
  import litellm
32
34
  from dostuff.helpers.agent.consume_stream import StreamProgress, consume_stream as _consume_stream
@@ -162,13 +164,30 @@ async def _sleep_or_cancel(seconds: float, adapter: Any) -> bool:
162
164
  return is_cancelled(adapter)
163
165
 
164
166
 
165
- async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_instruction: str, mcp_client: MCPClient, working_history: list, turn_type: Literal['interactive_loop', 'subagent_loop'], current_session_history=None, steps_history=None, store=None, adapter=None, compaction_notes: str = "", session_prompt_tokens: int = 0, session_completion_tokens: int = 0, session_total_tokens: int = 0, last_input_tokens: int = 0, stream: bool = True, max_iterations: int = MAX_ITERATIONS, tool_names: list[str] | None = None, permissions: SessionPermissions | None = None, session_hook_context: dict[str, str] | None = None) -> str:
167
+ @contextlib.contextmanager
168
+ def _job_events(owner: str, adapter: Any) -> Iterator[None]:
169
+ """While a run is going, emit `("job", {id, status, code})` for its own background jobs (spec D13)."""
170
+ def on_job(job: Job, event: JobEvent) -> None:
171
+ if job.owner == owner and not job.foreground and adapter is not None and hasattr(adapter, "emit"):
172
+ adapter.emit("job", {"id": job.id, "status": job.status, "code": job.exit_code})
173
+ registry = get_registry()
174
+ registry.add_listener(on_job)
175
+ try:
176
+ yield
177
+ finally:
178
+ registry.remove_listener(on_job)
179
+
180
+
181
+ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_instruction: str, mcp_client: MCPClient, working_history: list, turn_type: Literal['interactive_loop', 'subagent_loop'], current_session_history=None, steps_history=None, store=None, adapter=None, compaction_notes: str = "", session_prompt_tokens: int = 0, session_completion_tokens: int = 0, session_total_tokens: int = 0, last_input_tokens: int = 0, stream: bool = True, max_iterations: int = MAX_ITERATIONS, tool_names: list[str] | None = None, permissions: SessionPermissions | None = None, session_hook_context: dict[str, str] | None = None, owner: str | None = None) -> str:
166
182
  """Run one agent turn. `working_history` is mutated in place (appends and compaction).
167
183
 
168
184
  `session_hook_context` is the caller's per-session SessionStart context (hooks spec REQ-2.4): added to
169
185
  every model call's system instruction, refreshed here on compaction, never written to history.
186
+
187
+ `owner` is who this run's shell jobs belong to: the session, or `<session>/sub/<run>` for a subagent.
170
188
  """
171
189
  current_session_id.set(session_id)
190
+ owner = owner or session_id
172
191
  iteration = 0
173
192
  token_limit = get_model_token_limit()
174
193
  config = get_config()
@@ -208,6 +227,10 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
208
227
  turn_type=turn_type, adapter=adapter)
209
228
  return True
210
229
 
230
+ async def append_note(text: str) -> None:
231
+ """A harness-authored user step: a Stop-hook continuation or background-job notices."""
232
+ await append_step({"role": "user", "content": text}, steps_history, working_history, current_session_history, session_id, store, turn_type)
233
+
211
234
  async def check_cancelled() -> bool:
212
235
  return await loop_check_cancelled(steps_history, working_history, current_session_history, session_id, store, turn_type, adapter=adapter)
213
236
 
@@ -217,7 +240,7 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
217
240
  if context_token_threshold is not None and last_input_tokens > context_token_threshold:
218
241
  await compact("Token threshold exceeded.", keep_recent_token_budget)
219
242
 
220
- with tracer.start_as_current_span("turn") as turn_span:
243
+ with tracer.start_as_current_span("turn") as turn_span, _job_events(owner, adapter):
221
244
  turn_span.set_attribute("session_id", session_id)
222
245
  turn_span.set_attribute("turn_type", turn_type)
223
246
  turn_span.set_attribute("turn_id", turn_id)
@@ -234,6 +257,11 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
234
257
  if await check_cancelled():
235
258
  return "Cancelled by user."
236
259
 
260
+ # Background jobs of this run that ended since the last model call (spec D7)
261
+ notices = get_registry().drain_notices(owner)
262
+ if notices:
263
+ await append_note(format_notice(notices))
264
+
237
265
  # Model call with classified retries and exponential backoff
238
266
  interaction = None
239
267
  model_span = None
@@ -355,8 +383,7 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
355
383
  name = stop.decided_by or stop_event
356
384
  if stop_blocks < config.hooks_stop_block_limit:
357
385
  stop_blocks += 1
358
- note = STOP_NOTE.format(name=name, reason=stop.reason or "keep going")
359
- await append_step({"role": "user", "content": note}, steps_history, working_history, current_session_history, session_id, store, turn_type)
386
+ await append_note(STOP_NOTE.format(name=name, reason=stop.reason or "keep going"))
360
387
  iter_span.set_status(Status(StatusCode.OK))
361
388
  continue
362
389
  await loop_emit("system", STOP_LIMIT_MESSAGE.format(
@@ -429,7 +456,7 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
429
456
 
430
457
  def start(call: _ToolCall) -> asyncio.Task:
431
458
  return asyncio.ensure_future(asyncio.wait_for(
432
- dispatch_tool(call.name, dict(call.args), mcp_client=mcp_client, session_id=session_id, turn_id=turn_id, adapter=adapter, permissions=permissions),
459
+ dispatch_tool(call.name, dict(call.args), mcp_client=mcp_client, session_id=session_id, turn_id=turn_id, adapter=adapter, permissions=permissions, owner=owner),
433
460
  timeout=None if call.name in _UNTIMED_TOOLS else TOOL_TIMEOUT_S,
434
461
  ))
435
462
 
@@ -217,7 +217,10 @@ def _patterns_allow(patterns: list[str], tool: str, tokens: list[str] | None) ->
217
217
 
218
218
  def _describe_call(tool: str, args: dict[str, Any]) -> str:
219
219
  if tool == "bash_command":
220
- return f"Run shell command:\n {args.get('command', '')}"
220
+ mode = ""
221
+ if args.get("run_in_background"): # the user is approving something that keeps running
222
+ mode = f' (background job "{args["background_id"]}")' if args.get("background_id") else " (background job)"
223
+ return f"Run shell command{mode}:\n {args.get('command', '')}"
221
224
  if tool == "call_mcp_tool":
222
225
  return f"Call MCP tool '{args.get('name', '')}' with arguments:\n {str(args.get('arguments', {}))[:500]}"
223
226
  if tool == "web_fetch":
@@ -65,6 +65,7 @@ def _approval_preview(tool: str, args: dict[str, Any]) -> str:
65
65
 
66
66
  def permission_config() -> PermissionConfig:
67
67
  cfg = get_config()
68
+ cfg.reload_if_changed() # permissions edited in config.yaml by hand apply from the next tool call
68
69
  return PermissionConfig(mode=cast(PermissionMode, cfg.permission_mode), allow=list(cfg.permission_allow))
69
70
 
70
71
 
@@ -231,15 +232,19 @@ async def dispatch_tool(
231
232
  turn_id: str | None = None,
232
233
  adapter: Any = None,
233
234
  permissions: SessionPermissions | None = None,
235
+ owner: str | None = None,
234
236
  ) -> Any:
235
- """Execute an already-authorized tool call, injecting harness params the tool declares."""
237
+ """Execute an already-authorized tool call, injecting harness params the tool declares.
238
+
239
+ `owner` is the agent shell jobs belong to: the session, or `<session>/sub/<run>` for a subagent.
240
+ """
236
241
  spec = TOOL_MAP.get(fn_name)
237
242
  if spec is None:
238
243
  raise KeyError(f"Tool '{fn_name}' not found.")
239
244
  args = _sanitize_args(spec, fn_args)
240
245
  available: dict[str, Any] = {
241
246
  "mcp_client": mcp_client, "session_id": session_id, "turn_id": turn_id,
242
- "adapter": adapter, "permissions": permissions,
247
+ "adapter": adapter, "permissions": permissions, "owner": owner or session_id or "",
243
248
  }
244
249
  for param in spec.injected:
245
250
  if available[param] is None and param in ("mcp_client", "session_id", "turn_id"):
@@ -284,6 +289,7 @@ async def run_tool(
284
289
  adapter: Any = None,
285
290
  permissions: SessionPermissions | None = None,
286
291
  turn_type: str = "interactive_loop",
292
+ owner: str | None = None,
287
293
  ) -> Any:
288
294
  """Hooks, authorize, dispatch, hooks: the same order as loop(). A denial is returned as the result, not raised."""
289
295
  if not isinstance(fn_name, str):
@@ -299,7 +305,7 @@ async def run_tool(
299
305
  return denial
300
306
  result = await dispatch_tool(
301
307
  fn_name, fn_args, mcp_client=mcp_client, session_id=session_id, turn_id=turn_id,
302
- adapter=adapter, permissions=permissions,
308
+ adapter=adapter, permissions=permissions, owner=owner,
303
309
  )
304
310
  result, _ = await post_tool_use(fn_name, fn_args, result, **ids)
305
311
  return result