dostuff 0.2.9__tar.gz → 0.2.11__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.
- {dostuff-0.2.9 → dostuff-0.2.11}/PKG-INFO +105 -7
- {dostuff-0.2.9 → dostuff-0.2.11}/README.md +104 -6
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/call_agent.py +32 -2
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/instructions.py +15 -10
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/loop.py +102 -13
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/permissions.py +4 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/subagents/fork.py +1 -1
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/subagents/prompt.py +2 -2
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/cli_tui.py +304 -35
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/config.py +4 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/headless.py +11 -5
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/constants.py +7 -4
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/consume_stream.py +14 -1
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/context_usage.py +10 -3
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/environment_context.py +1 -1
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/manage_context.py +3 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/side_question.py +6 -9
- dostuff-0.2.11/dostuff/helpers/agent/steering.py +107 -0
- dostuff-0.2.11/dostuff/helpers/agent/turn_context.py +58 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/hooks/events.py +2 -7
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/memory/export_session.py +3 -0
- dostuff-0.2.11/dostuff/helpers/skills/discover_skills.py +74 -0
- dostuff-0.2.11/dostuff/helpers/tools/resolve_safe_path.py +57 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/memory/session_store.py +6 -3
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/templates/config.example.yaml +3 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff.egg-info/PKG-INFO +105 -7
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff.egg-info/SOURCES.txt +5 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/pyproject.toml +1 -1
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_cli_commands.py +26 -1
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_config_memory_mcp.py +15 -0
- dostuff-0.2.11/tests/test_export_session.py +27 -0
- dostuff-0.2.11/tests/test_file_tools.py +249 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_loop.py +623 -7
- dostuff-0.2.11/tests/test_optional_memory_and_instructions.py +196 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_permissions.py +58 -1
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_roadmap_021.py +23 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_session_store.py +71 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_side_question.py +15 -16
- dostuff-0.2.11/tests/test_skills_discovery.py +230 -0
- dostuff-0.2.11/tests/test_steering.py +121 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_subagents_fork.py +48 -4
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_subagents_run.py +4 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_subagents_store.py +2 -3
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_tui.py +1417 -41
- dostuff-0.2.11/tests/test_turn_context.py +197 -0
- dostuff-0.2.9/dostuff/helpers/skills/discover_skills.py +0 -49
- dostuff-0.2.9/dostuff/helpers/tools/resolve_safe_path.py +0 -33
- dostuff-0.2.9/tests/test_file_tools.py +0 -116
- dostuff-0.2.9/tests/test_optional_memory_and_instructions.py +0 -85
- dostuff-0.2.9/tests/test_skills_discovery.py +0 -37
- {dostuff-0.2.9 → dostuff-0.2.11}/LICENSE +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/__init__.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/__main__.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/run_tool.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/subagents/__init__.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/subagents/adapter.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/subagents/definitions.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/subagents/registry.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/agent/subagents/run.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/cli.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/append_step.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/file_mentions.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/load_identity.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/load_project_instructions.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/loop_emit.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/model_cost.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/notices.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/pastes.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/quick_memory.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/slash_suggestion.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/agent/tool_output.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/hooks/__init__.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/hooks/dispatch.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/hooks/load_hooks.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/hooks/run_hook.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/hooks/trust.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/mcp/server_config.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/mcp/token_store.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/memory/shell_step.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/models/add_model_entry.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/models/list_models.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/models/opencode.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/skills/custom_commands.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/skills/skill_command.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/tools/diff.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/tools/project_root.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/ui/__init__.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/ui/ask_answers.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/ui/doctor.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/ui/emit.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/ui/prompt_history.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/ui/terminal_signals.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/helpers/ui/tools_listing.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/checkpoints.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/exceptions.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/mcp/mcp_client.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/memory/chroma.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/memory/episodic_memory_store.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/memory/semantic_memory_store.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/memory/stores.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/memory/types.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/model.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/tracing.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/lib/worktree.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/memory/__init__.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/setup_wizard.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/skills.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/templates/env.example +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/__init__.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/agent.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/ask_user.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/bash/bash_command.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/bash/bash_output.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/bash/jobs.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/bash/kill_shell.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/create_agent_type.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/definitions.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/files/delete_file.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/files/edit_file.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/files/list_files.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/files/read_file.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/files/write_file.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/get_current_datetime.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/memory/save_episode.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/memory/save_memory.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/names.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/search/glob.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/search/grep.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/search/walk.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/send_message.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/settings.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/stop_agent.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/todo_write.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/web_fetch.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff/tools/web_search.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff.egg-info/dependency_links.txt +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff.egg-info/entry_points.txt +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff.egg-info/requires.txt +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/dostuff.egg-info/top_level.txt +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/setup.cfg +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_ask_user.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_bash_command.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_checkpoints_todos_caching.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_create_agent_type.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_file_mentions.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_hooks.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_jobs.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_mcp_e2e.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_mcp_oauth.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_opencode.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_pastes.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_settings_tools.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_setup_wizard.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_side_question_litellm.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_skill_command.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_slash_suggestion.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_subagent.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_subagents_background.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_subagents_types.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_terminal_signals.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_tool_schemas.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_tools_listing.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_web_fetch.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_web_search.py +0 -0
- {dostuff-0.2.9 → dostuff-0.2.11}/tests/test_worktree.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: dostuff
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.11
|
|
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,10 +85,11 @@ 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
|
- **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
|
|
87
87
|
- **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
|
|
88
|
+
- **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
|
|
88
89
|
- **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
|
|
89
90
|
- **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
|
|
90
91
|
- **Background jobs** — `bash_command(run_in_background=true)` starts dev servers, watchers and long test runs as jobs the agent reads with `bash_output` (`wait_for` a ready line) and stops with `kill_shell`; it hears when one ends. `Ctrl+B` moves a running command to the background, `/jobs` lists them, and none outlives the session. See [Background jobs](#background-jobs)
|
|
91
|
-
- **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
|
|
92
|
+
- **File sandbox** — file tools stay inside the project directory, plus read-only access to discovered skill folders, and never read `.env*` files or the rest of `~/.dostuff/`
|
|
92
93
|
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
|
|
93
94
|
- **Subagents** — the `agent` tool starts agents in parallel, in the foreground or the background, from built-in types (`explore`, `plan`, `general-purpose`), your own Markdown agent files (Claude Code's `.claude/agents/` work too) or a `fork` of the conversation; continue one with `send_message`, stop it with `stop_agent`, see them all in `/agents`. See [Subagents](#subagents)
|
|
94
95
|
- **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
|
|
@@ -244,11 +245,12 @@ In the TUI:
|
|
|
244
245
|
| `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
|
|
245
246
|
| `/copy` | Copy the model's last answer to the clipboard |
|
|
246
247
|
| `/btw <question>` | Ask a side question about the conversation, even while a turn runs: answered in a panel above the input, without tools, never added to the history. See [Side questions](#side-questions-btw) |
|
|
248
|
+
| `/steer <message>` | Send a correction to the running turn: the model reads it at the next tool boundary and carries on, without the turn ending. See [Mid-turn steering](#mid-turn-steering-steer) |
|
|
247
249
|
| `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
|
|
248
250
|
| `/model [<provider/model>] [--active]` | Pick a model: your saved ones (`models:` in config.yaml) first, then "More <provider> models…" for each provider's list (type to filter; Enter on no match uses what you typed). A model that isn't saved yet is added to `~/.dostuff/config.yaml`. A plain `/model` switch lasts only for this session; add `--active` (e.g. `/model --active`, or `/model anthropic/claude-sonnet-5-5 --active`) to make it the default that new sessions start with |
|
|
249
251
|
| `/config [mcp] [project]` | Edit a settings file right in the TUI: pick `config.yaml` or the MCP servers, user (`~/.dostuff`) or project (`./.dostuff`), or name one (`/config mcp project`). `Ctrl+S` checks the file, saves it and applies it without a restart (an invalid file stays open with the error); `Esc` closes, twice if there are unsaved changes. A new file starts with every option commented out. `.env` files aren't offered |
|
|
250
252
|
| `/status` | Session, directory, model, permission mode, tokens, context use, MCP servers |
|
|
251
|
-
| `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
|
|
253
|
+
| `/context` | What fills the context window: system prompt, turn context (the environment, recalled memories and hook context sent with each prompt), tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
|
|
252
254
|
| `/memory [project\|global]` | Edit `AGENTS.md` (this project's or `~/.dostuff/AGENTS.md`) in the same editor as `/config`; `Ctrl+S` saves and the agent follows it from the next message |
|
|
253
255
|
| `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
|
|
254
256
|
| `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then each connected MCP server's tools (reached through `call_mcp_tool`) |
|
|
@@ -271,6 +273,7 @@ In the TUI:
|
|
|
271
273
|
**Visual elements:**
|
|
272
274
|
|
|
273
275
|
- **Messages** — `>` for your prompts (on a grey band), `●` for agent replies and tool calls, `⎿` for tool results; the terminal background shows through
|
|
276
|
+
- **Sticky prompt** — once a prompt or `!command` scrolls off the top, it stays pinned there on one row while you are in its turn, as the answer streams or when you scroll back through an old one, until the next prompt reaches the top. Click it to go back to the start of the turn; `↓ Jump to bottom` returns you to the latest message
|
|
274
277
|
- **Approvals** — a selector (arrows, a number, or `y` = allow once, `a` = always this session, `n` = deny with an optional note); several calls in one response can be approved together
|
|
275
278
|
- **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
|
|
276
279
|
- **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
|
|
@@ -278,7 +281,8 @@ In the TUI:
|
|
|
278
281
|
- **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
|
|
279
282
|
- **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
|
|
280
283
|
- **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
|
|
281
|
-
- **Queued prompts** — prompts
|
|
284
|
+
- **Queued prompts** — prompts that have to wait for the turn sit above the input, one row each, and run in order: skill and custom commands in both modes, plain messages with `ui.mid_turn_messages: queue`. 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
|
|
285
|
+
- **Steering messages** — `/steer <message>` (and every plain message by default; `ui.mid_turn_messages: queue` makes them wait instead) waits for the next tool boundary instead of the end of the turn: the bar leads with `→ N for the agent · read at the next tool boundary`, `/queue` lists them first with Edit / Remove (and *Send now* turns a queued prompt into one), and `Esc` puts a pending one back in the input ahead of the queue. See [Mid-turn steering](#mid-turn-steering-steer)
|
|
282
286
|
- **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
|
|
283
287
|
- **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
|
|
284
288
|
|
|
@@ -330,7 +334,8 @@ API keys stay in `.env` files, which the agent can't read or change. Subagents d
|
|
|
330
334
|
|
|
331
335
|
> [!IMPORTANT]
|
|
332
336
|
> File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
|
|
333
|
-
> outside it are rejected,
|
|
337
|
+
> outside it are rejected, except that discovered skill folders can be read (never written), and `.env*` files and
|
|
338
|
+
> the rest of `~/.dostuff/` cannot be read. **The shell is not sandboxed**:
|
|
334
339
|
> `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
|
|
335
340
|
> The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
|
|
336
341
|
|
|
@@ -511,6 +516,90 @@ no `/btw` (only skills and custom commands run there), so `/btw` in a `-p` promp
|
|
|
511
516
|
|
|
512
517
|
---
|
|
513
518
|
|
|
519
|
+
## Mid-turn steering (`/steer`)
|
|
520
|
+
|
|
521
|
+
A message typed while a turn runs normally waits its turn: it joins the queue and runs as its own prompt when the
|
|
522
|
+
current one ends. `/steer <message>` sends a **correction** instead — the model reads it at the next tool boundary and
|
|
523
|
+
carries on with it, without the turn ending and without anything being interrupted:
|
|
524
|
+
|
|
525
|
+
```
|
|
526
|
+
> /steer actually target ./dostuff, not the repo root
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
It lands in the transcript as a user message right after the tool output it was reacting to — where the model read it
|
|
530
|
+
— and the next model call sees it as the newest user message. A final answer that arrives while a correction is still
|
|
531
|
+
waiting does not end the turn: the model reads it and redoes or extends the answer. That check runs before the `Stop`
|
|
532
|
+
hooks, so they see the answer that really ends the turn.
|
|
533
|
+
|
|
534
|
+
What the model reads is framed, not bare: the stored user step is your text wrapped in two fixed lines —
|
|
535
|
+
`The user sent a new message while you were working:` above it, `Address the message above, then continue the task
|
|
536
|
+
you were working on.` below. The loop has no notion of "the task", only the history, so without that instruction a
|
|
537
|
+
standalone question tends to be answered with a final response and the turn ends with the interrupted work left
|
|
538
|
+
mid-flight; Claude Code wraps mid-turn messages the same way. Everything you *see* stays raw — the transcript line,
|
|
539
|
+
Esc-to-restore, and what a leftover re-runs — the frame reaches only the model, plus the stored transcript that
|
|
540
|
+
`/resume` replays.
|
|
541
|
+
|
|
542
|
+
### Two modes
|
|
543
|
+
|
|
544
|
+
`ui.mid_turn_messages` in `config.yaml` decides what a **plain** message does while a turn runs (default `steer`):
|
|
545
|
+
|
|
546
|
+
| Submitted | `queue` | `steer` (default) |
|
|
547
|
+
|---|---|---|
|
|
548
|
+
| Plain message | waits in the queue, runs after the turn | steering: read at the next tool boundary |
|
|
549
|
+
| `/steer <message>` | steering | steering |
|
|
550
|
+
| `/<skill> args`, custom command | waits in the queue | waits in the queue |
|
|
551
|
+
| `/btw`, `/queue`, `/jobs`, … | run now | run now |
|
|
552
|
+
| `/clear`, `/resume`, `/model`, … | refused while a turn runs | refused while a turn runs |
|
|
553
|
+
| `!command` | refused while a turn runs | refused while a turn runs |
|
|
554
|
+
| `#note` (quick memory) | run now | run now |
|
|
555
|
+
|
|
556
|
+
`steer` is the default because it is Claude Code's behaviour: a correction is read now, at the next tool boundary,
|
|
557
|
+
instead of after the turn. `queue` stays one key away for anyone who prefers batching — three instructions typed in a
|
|
558
|
+
row run as three prompts while you are away, and a queued message is never read mid-task when you meant "next".
|
|
559
|
+
`/steer` works in both modes, and with no turn running it is
|
|
560
|
+
an ordinary prompt (it starts a turn), so the habit is never an error. Skills and custom commands stay in the queue in
|
|
561
|
+
both modes: a skill is a turn's prompt, not a correction.
|
|
562
|
+
|
|
563
|
+
### What you see
|
|
564
|
+
|
|
565
|
+
- **On submit** the input clears and the bar above it leads with the steering group, `→ 1 for the agent · read at the next tool boundary`, above the usual `N queued · click or /queue …` rows; the loader counts them separately, `· 1 steering · 2 queued`.
|
|
566
|
+
- **`/queue`** lists the steering messages first, each marked `→`, with *Edit* and *Remove* (once the loop has read
|
|
567
|
+
one, the picker says "That message was already read."), and every queued prompt gained *Send now (at the next tool
|
|
568
|
+
boundary)*, which turns it into a correction.
|
|
569
|
+
- **Attachments are prepared in order**: `@mentions` are expanded and pastes resolved right after you send, in the
|
|
570
|
+
order you sent them, so a message holding a big file never jumps ahead of the one after it. The `Attached …` lines
|
|
571
|
+
show as they finish, as for a prompt.
|
|
572
|
+
- **Hooks and the sandbox still apply**: `UserPromptSubmit` runs for each correction at the boundary, so a hook can
|
|
573
|
+
block it — it is shown like a blocked prompt and never reaches the model — or add context, written as a
|
|
574
|
+
note right before the correction (the system prompt never changes mid-turn, so the prompt cache holds); a preparation
|
|
575
|
+
failure is reported instead of half-delivered.
|
|
576
|
+
|
|
577
|
+
### Latency, and `Ctrl+B`
|
|
578
|
+
|
|
579
|
+
Delivery waits for the tool call in flight; nothing is interrupted to deliver sooner, so a two-minute `bash_command`
|
|
580
|
+
delays a correction two minutes. While a message waits behind a running command the bar says why —
|
|
581
|
+
`waiting for a running command · Ctrl+B to background it` — and `Ctrl+B` moves the command (or a foreground subagent)
|
|
582
|
+
to the background, which returns the call to the loop at once: the message is read at the next boundary while the
|
|
583
|
+
command keeps running. `Esc` remains the way to stop.
|
|
584
|
+
|
|
585
|
+
### Leftovers
|
|
586
|
+
|
|
587
|
+
A correction can outlive its turn — sent after the final answer's last check, still being prepared, the turn hit the
|
|
588
|
+
iteration cap, the model call failed, or you pressed `Esc`. Nothing is lost:
|
|
589
|
+
|
|
590
|
+
- **Cancelled** (`Esc`) — the raw text goes back into the input **ahead of** the queued prompts: stopping the work
|
|
591
|
+
includes the corrections to it.
|
|
592
|
+
- **Otherwise** — it runs next: `1 message arrived after the turn ended; running it next`, then it is re-prepared from
|
|
593
|
+
what you typed and runs as a normal turn.
|
|
594
|
+
|
|
595
|
+
Either way the text you typed is written to the history exactly once — whether the model read it mid-turn or it ran as
|
|
596
|
+
the next turn.
|
|
597
|
+
|
|
598
|
+
`dostuff -p` has no `/steer` (only skills and custom commands run there), so a `/steer` line in a `-p` prompt is
|
|
599
|
+
ordinary text for the model.
|
|
600
|
+
|
|
601
|
+
---
|
|
602
|
+
|
|
514
603
|
## Subagents
|
|
515
604
|
|
|
516
605
|
A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
|
|
@@ -631,7 +720,7 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
|
|
|
631
720
|
| Event | When | Matcher is matched against | What a hook can do |
|
|
632
721
|
|---|---|---|---|
|
|
633
722
|
| `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 |
|
|
634
|
-
| `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context
|
|
723
|
+
| `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context sent with it (hidden from the transcript, and stays in the model's history) |
|
|
635
724
|
| `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
|
|
636
725
|
| `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
|
|
637
726
|
| `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
|
|
@@ -853,6 +942,11 @@ permissions:
|
|
|
853
942
|
mode: ask # ask | allowlist | auto | plan
|
|
854
943
|
allow: []
|
|
855
944
|
|
|
945
|
+
ui:
|
|
946
|
+
mid_turn_messages: steer # steer (default): a plain message sent while a turn runs is read by the model at
|
|
947
|
+
# the next tool boundary, inside the running turn | queue: it waits and runs after
|
|
948
|
+
# the turn. /steer sends one either way (see Mid-turn steering)
|
|
949
|
+
|
|
856
950
|
agents: # see Subagents
|
|
857
951
|
max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
|
|
858
952
|
max_concurrent: 4
|
|
@@ -998,7 +1092,11 @@ Skills are directories containing a `SKILL.md` (frontmatter with `name` and `des
|
|
|
998
1092
|
4. `~/.agents/skills/`
|
|
999
1093
|
5. `<cwd>/skills/`
|
|
1000
1094
|
|
|
1001
|
-
**Conflict resolution:**
|
|
1095
|
+
**Conflict resolution:** Skills are deduplicated by name: if two share a name, the first one found (in the order above) wins and the other is dropped, from the system prompt and from the slash commands alike.
|
|
1096
|
+
|
|
1097
|
+
**How a skill reaches the model:** the system prompt lists each skill's `name`, `description` and `dir` (its absolute folder), and only those. When the model decides to use a skill it reads the `SKILL.md` in that dir with `read_file`, so a body costs nothing until it is needed. Frontmatter is parsed as YAML, so quoted and folded (`>`, `|`) descriptions arrive as plain text; a file with invalid YAML still loads, with its fields read line by line.
|
|
1098
|
+
|
|
1099
|
+
File tools can read a discovered skill's folder wherever it lives, including the files next to `SKILL.md` (`scripts/`, `reference/`), but never write there. `.env*` files stay unreadable inside a skill folder too, and of `~/.dostuff/` only discovered skills under `~/.dostuff/skills/` can be read.
|
|
1002
1100
|
|
|
1003
1101
|
**Example structure:**
|
|
1004
1102
|
|
|
@@ -37,10 +37,11 @@ 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
|
- **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
|
|
39
39
|
- **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
|
|
40
|
+
- **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
|
|
40
41
|
- **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
|
|
41
42
|
- **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
|
|
42
43
|
- **Background jobs** — `bash_command(run_in_background=true)` starts dev servers, watchers and long test runs as jobs the agent reads with `bash_output` (`wait_for` a ready line) and stops with `kill_shell`; it hears when one ends. `Ctrl+B` moves a running command to the background, `/jobs` lists them, and none outlives the session. See [Background jobs](#background-jobs)
|
|
43
|
-
- **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
|
|
44
|
+
- **File sandbox** — file tools stay inside the project directory, plus read-only access to discovered skill folders, and never read `.env*` files or the rest of `~/.dostuff/`
|
|
44
45
|
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
|
|
45
46
|
- **Subagents** — the `agent` tool starts agents in parallel, in the foreground or the background, from built-in types (`explore`, `plan`, `general-purpose`), your own Markdown agent files (Claude Code's `.claude/agents/` work too) or a `fork` of the conversation; continue one with `send_message`, stop it with `stop_agent`, see them all in `/agents`. See [Subagents](#subagents)
|
|
46
47
|
- **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
|
|
@@ -196,11 +197,12 @@ In the TUI:
|
|
|
196
197
|
| `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
|
|
197
198
|
| `/copy` | Copy the model's last answer to the clipboard |
|
|
198
199
|
| `/btw <question>` | Ask a side question about the conversation, even while a turn runs: answered in a panel above the input, without tools, never added to the history. See [Side questions](#side-questions-btw) |
|
|
200
|
+
| `/steer <message>` | Send a correction to the running turn: the model reads it at the next tool boundary and carries on, without the turn ending. See [Mid-turn steering](#mid-turn-steering-steer) |
|
|
199
201
|
| `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
|
|
200
202
|
| `/model [<provider/model>] [--active]` | Pick a model: your saved ones (`models:` in config.yaml) first, then "More <provider> models…" for each provider's list (type to filter; Enter on no match uses what you typed). A model that isn't saved yet is added to `~/.dostuff/config.yaml`. A plain `/model` switch lasts only for this session; add `--active` (e.g. `/model --active`, or `/model anthropic/claude-sonnet-5-5 --active`) to make it the default that new sessions start with |
|
|
201
203
|
| `/config [mcp] [project]` | Edit a settings file right in the TUI: pick `config.yaml` or the MCP servers, user (`~/.dostuff`) or project (`./.dostuff`), or name one (`/config mcp project`). `Ctrl+S` checks the file, saves it and applies it without a restart (an invalid file stays open with the error); `Esc` closes, twice if there are unsaved changes. A new file starts with every option commented out. `.env` files aren't offered |
|
|
202
204
|
| `/status` | Session, directory, model, permission mode, tokens, context use, MCP servers |
|
|
203
|
-
| `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
|
|
205
|
+
| `/context` | What fills the context window: system prompt, turn context (the environment, recalled memories and hook context sent with each prompt), tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
|
|
204
206
|
| `/memory [project\|global]` | Edit `AGENTS.md` (this project's or `~/.dostuff/AGENTS.md`) in the same editor as `/config`; `Ctrl+S` saves and the agent follows it from the next message |
|
|
205
207
|
| `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
|
|
206
208
|
| `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then each connected MCP server's tools (reached through `call_mcp_tool`) |
|
|
@@ -223,6 +225,7 @@ In the TUI:
|
|
|
223
225
|
**Visual elements:**
|
|
224
226
|
|
|
225
227
|
- **Messages** — `>` for your prompts (on a grey band), `●` for agent replies and tool calls, `⎿` for tool results; the terminal background shows through
|
|
228
|
+
- **Sticky prompt** — once a prompt or `!command` scrolls off the top, it stays pinned there on one row while you are in its turn, as the answer streams or when you scroll back through an old one, until the next prompt reaches the top. Click it to go back to the start of the turn; `↓ Jump to bottom` returns you to the latest message
|
|
226
229
|
- **Approvals** — a selector (arrows, a number, or `y` = allow once, `a` = always this session, `n` = deny with an optional note); several calls in one response can be approved together
|
|
227
230
|
- **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
|
|
228
231
|
- **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
|
|
@@ -230,7 +233,8 @@ In the TUI:
|
|
|
230
233
|
- **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
|
|
231
234
|
- **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
|
|
232
235
|
- **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
|
|
233
|
-
- **Queued prompts** — prompts
|
|
236
|
+
- **Queued prompts** — prompts that have to wait for the turn sit above the input, one row each, and run in order: skill and custom commands in both modes, plain messages with `ui.mid_turn_messages: queue`. 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
|
|
237
|
+
- **Steering messages** — `/steer <message>` (and every plain message by default; `ui.mid_turn_messages: queue` makes them wait instead) waits for the next tool boundary instead of the end of the turn: the bar leads with `→ N for the agent · read at the next tool boundary`, `/queue` lists them first with Edit / Remove (and *Send now* turns a queued prompt into one), and `Esc` puts a pending one back in the input ahead of the queue. See [Mid-turn steering](#mid-turn-steering-steer)
|
|
234
238
|
- **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
|
|
235
239
|
- **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
|
|
236
240
|
|
|
@@ -282,7 +286,8 @@ API keys stay in `.env` files, which the agent can't read or change. Subagents d
|
|
|
282
286
|
|
|
283
287
|
> [!IMPORTANT]
|
|
284
288
|
> File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
|
|
285
|
-
> outside it are rejected,
|
|
289
|
+
> outside it are rejected, except that discovered skill folders can be read (never written), and `.env*` files and
|
|
290
|
+
> the rest of `~/.dostuff/` cannot be read. **The shell is not sandboxed**:
|
|
286
291
|
> `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
|
|
287
292
|
> The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
|
|
288
293
|
|
|
@@ -463,6 +468,90 @@ no `/btw` (only skills and custom commands run there), so `/btw` in a `-p` promp
|
|
|
463
468
|
|
|
464
469
|
---
|
|
465
470
|
|
|
471
|
+
## Mid-turn steering (`/steer`)
|
|
472
|
+
|
|
473
|
+
A message typed while a turn runs normally waits its turn: it joins the queue and runs as its own prompt when the
|
|
474
|
+
current one ends. `/steer <message>` sends a **correction** instead — the model reads it at the next tool boundary and
|
|
475
|
+
carries on with it, without the turn ending and without anything being interrupted:
|
|
476
|
+
|
|
477
|
+
```
|
|
478
|
+
> /steer actually target ./dostuff, not the repo root
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
It lands in the transcript as a user message right after the tool output it was reacting to — where the model read it
|
|
482
|
+
— and the next model call sees it as the newest user message. A final answer that arrives while a correction is still
|
|
483
|
+
waiting does not end the turn: the model reads it and redoes or extends the answer. That check runs before the `Stop`
|
|
484
|
+
hooks, so they see the answer that really ends the turn.
|
|
485
|
+
|
|
486
|
+
What the model reads is framed, not bare: the stored user step is your text wrapped in two fixed lines —
|
|
487
|
+
`The user sent a new message while you were working:` above it, `Address the message above, then continue the task
|
|
488
|
+
you were working on.` below. The loop has no notion of "the task", only the history, so without that instruction a
|
|
489
|
+
standalone question tends to be answered with a final response and the turn ends with the interrupted work left
|
|
490
|
+
mid-flight; Claude Code wraps mid-turn messages the same way. Everything you *see* stays raw — the transcript line,
|
|
491
|
+
Esc-to-restore, and what a leftover re-runs — the frame reaches only the model, plus the stored transcript that
|
|
492
|
+
`/resume` replays.
|
|
493
|
+
|
|
494
|
+
### Two modes
|
|
495
|
+
|
|
496
|
+
`ui.mid_turn_messages` in `config.yaml` decides what a **plain** message does while a turn runs (default `steer`):
|
|
497
|
+
|
|
498
|
+
| Submitted | `queue` | `steer` (default) |
|
|
499
|
+
|---|---|---|
|
|
500
|
+
| Plain message | waits in the queue, runs after the turn | steering: read at the next tool boundary |
|
|
501
|
+
| `/steer <message>` | steering | steering |
|
|
502
|
+
| `/<skill> args`, custom command | waits in the queue | waits in the queue |
|
|
503
|
+
| `/btw`, `/queue`, `/jobs`, … | run now | run now |
|
|
504
|
+
| `/clear`, `/resume`, `/model`, … | refused while a turn runs | refused while a turn runs |
|
|
505
|
+
| `!command` | refused while a turn runs | refused while a turn runs |
|
|
506
|
+
| `#note` (quick memory) | run now | run now |
|
|
507
|
+
|
|
508
|
+
`steer` is the default because it is Claude Code's behaviour: a correction is read now, at the next tool boundary,
|
|
509
|
+
instead of after the turn. `queue` stays one key away for anyone who prefers batching — three instructions typed in a
|
|
510
|
+
row run as three prompts while you are away, and a queued message is never read mid-task when you meant "next".
|
|
511
|
+
`/steer` works in both modes, and with no turn running it is
|
|
512
|
+
an ordinary prompt (it starts a turn), so the habit is never an error. Skills and custom commands stay in the queue in
|
|
513
|
+
both modes: a skill is a turn's prompt, not a correction.
|
|
514
|
+
|
|
515
|
+
### What you see
|
|
516
|
+
|
|
517
|
+
- **On submit** the input clears and the bar above it leads with the steering group, `→ 1 for the agent · read at the next tool boundary`, above the usual `N queued · click or /queue …` rows; the loader counts them separately, `· 1 steering · 2 queued`.
|
|
518
|
+
- **`/queue`** lists the steering messages first, each marked `→`, with *Edit* and *Remove* (once the loop has read
|
|
519
|
+
one, the picker says "That message was already read."), and every queued prompt gained *Send now (at the next tool
|
|
520
|
+
boundary)*, which turns it into a correction.
|
|
521
|
+
- **Attachments are prepared in order**: `@mentions` are expanded and pastes resolved right after you send, in the
|
|
522
|
+
order you sent them, so a message holding a big file never jumps ahead of the one after it. The `Attached …` lines
|
|
523
|
+
show as they finish, as for a prompt.
|
|
524
|
+
- **Hooks and the sandbox still apply**: `UserPromptSubmit` runs for each correction at the boundary, so a hook can
|
|
525
|
+
block it — it is shown like a blocked prompt and never reaches the model — or add context, written as a
|
|
526
|
+
note right before the correction (the system prompt never changes mid-turn, so the prompt cache holds); a preparation
|
|
527
|
+
failure is reported instead of half-delivered.
|
|
528
|
+
|
|
529
|
+
### Latency, and `Ctrl+B`
|
|
530
|
+
|
|
531
|
+
Delivery waits for the tool call in flight; nothing is interrupted to deliver sooner, so a two-minute `bash_command`
|
|
532
|
+
delays a correction two minutes. While a message waits behind a running command the bar says why —
|
|
533
|
+
`waiting for a running command · Ctrl+B to background it` — and `Ctrl+B` moves the command (or a foreground subagent)
|
|
534
|
+
to the background, which returns the call to the loop at once: the message is read at the next boundary while the
|
|
535
|
+
command keeps running. `Esc` remains the way to stop.
|
|
536
|
+
|
|
537
|
+
### Leftovers
|
|
538
|
+
|
|
539
|
+
A correction can outlive its turn — sent after the final answer's last check, still being prepared, the turn hit the
|
|
540
|
+
iteration cap, the model call failed, or you pressed `Esc`. Nothing is lost:
|
|
541
|
+
|
|
542
|
+
- **Cancelled** (`Esc`) — the raw text goes back into the input **ahead of** the queued prompts: stopping the work
|
|
543
|
+
includes the corrections to it.
|
|
544
|
+
- **Otherwise** — it runs next: `1 message arrived after the turn ended; running it next`, then it is re-prepared from
|
|
545
|
+
what you typed and runs as a normal turn.
|
|
546
|
+
|
|
547
|
+
Either way the text you typed is written to the history exactly once — whether the model read it mid-turn or it ran as
|
|
548
|
+
the next turn.
|
|
549
|
+
|
|
550
|
+
`dostuff -p` has no `/steer` (only skills and custom commands run there), so a `/steer` line in a `-p` prompt is
|
|
551
|
+
ordinary text for the model.
|
|
552
|
+
|
|
553
|
+
---
|
|
554
|
+
|
|
466
555
|
## Subagents
|
|
467
556
|
|
|
468
557
|
A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
|
|
@@ -583,7 +672,7 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
|
|
|
583
672
|
| Event | When | Matcher is matched against | What a hook can do |
|
|
584
673
|
|---|---|---|---|
|
|
585
674
|
| `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 |
|
|
586
|
-
| `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context
|
|
675
|
+
| `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context sent with it (hidden from the transcript, and stays in the model's history) |
|
|
587
676
|
| `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
|
|
588
677
|
| `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
|
|
589
678
|
| `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
|
|
@@ -805,6 +894,11 @@ permissions:
|
|
|
805
894
|
mode: ask # ask | allowlist | auto | plan
|
|
806
895
|
allow: []
|
|
807
896
|
|
|
897
|
+
ui:
|
|
898
|
+
mid_turn_messages: steer # steer (default): a plain message sent while a turn runs is read by the model at
|
|
899
|
+
# the next tool boundary, inside the running turn | queue: it waits and runs after
|
|
900
|
+
# the turn. /steer sends one either way (see Mid-turn steering)
|
|
901
|
+
|
|
808
902
|
agents: # see Subagents
|
|
809
903
|
max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
|
|
810
904
|
max_concurrent: 4
|
|
@@ -950,7 +1044,11 @@ Skills are directories containing a `SKILL.md` (frontmatter with `name` and `des
|
|
|
950
1044
|
4. `~/.agents/skills/`
|
|
951
1045
|
5. `<cwd>/skills/`
|
|
952
1046
|
|
|
953
|
-
**Conflict resolution:**
|
|
1047
|
+
**Conflict resolution:** Skills are deduplicated by name: if two share a name, the first one found (in the order above) wins and the other is dropped, from the system prompt and from the slash commands alike.
|
|
1048
|
+
|
|
1049
|
+
**How a skill reaches the model:** the system prompt lists each skill's `name`, `description` and `dir` (its absolute folder), and only those. When the model decides to use a skill it reads the `SKILL.md` in that dir with `read_file`, so a body costs nothing until it is needed. Frontmatter is parsed as YAML, so quoted and folded (`>`, `|`) descriptions arrive as plain text; a file with invalid YAML still loads, with its fields read line by line.
|
|
1050
|
+
|
|
1051
|
+
File tools can read a discovered skill's folder wherever it lives, including the files next to `SKILL.md` (`scripts/`, `reference/`), but never write there. `.env*` files stay unreadable inside a skill folder too, and of `~/.dostuff/` only discovered skills under `~/.dostuff/skills/` can be read.
|
|
954
1052
|
|
|
955
1053
|
**Example structure:**
|
|
956
1054
|
|
|
@@ -8,7 +8,7 @@ from dostuff.lib.tracing import content_attr, tracer
|
|
|
8
8
|
from opentelemetry.trace import Status, StatusCode
|
|
9
9
|
|
|
10
10
|
|
|
11
|
-
# Two breakpoints: the system prompt (tools + instructions, stable
|
|
11
|
+
# Two breakpoints: the system prompt (tools + instructions, stable across turns) and the last
|
|
12
12
|
# message, which moves each call, so the next call reads everything before it from the cache.
|
|
13
13
|
CACHE_BREAKPOINTS: list[dict[str, Any]] = [
|
|
14
14
|
{"location": "message", "role": "system"},
|
|
@@ -39,11 +39,41 @@ def build_request_kwargs(stream: bool) -> dict[str, Any]:
|
|
|
39
39
|
return kwargs
|
|
40
40
|
|
|
41
41
|
|
|
42
|
+
def _as_blocks(content: Any) -> list[Any]:
|
|
43
|
+
if isinstance(content, list):
|
|
44
|
+
return content
|
|
45
|
+
return [{"type": "text", "text": content}] if content else []
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _join_user_content(first: Any, second: Any) -> Any:
|
|
49
|
+
if isinstance(first, list) or isinstance(second, list):
|
|
50
|
+
return _as_blocks(first) + _as_blocks(second) # an image block must survive, so no flattening to text
|
|
51
|
+
return "\n\n".join(text for text in (first, second) if text)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def provider_messages(steps: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
|
55
|
+
"""The history as a provider may see it. The steps themselves are left alone: the store and every reader need
|
|
56
|
+
them apart, while a request needs valid turns.
|
|
57
|
+
|
|
58
|
+
`meta` is dostuff's own (the turn-context marker), so it is dropped. Adjacent user steps become one message,
|
|
59
|
+
because Perplexity and strict chat templates (vLLM's Gemma, Mistral) reject two in a row, and a turn's context
|
|
60
|
+
step always sits right before its prompt. Same history, same result, so the cached prefix holds.
|
|
61
|
+
"""
|
|
62
|
+
messages: list[dict[str, Any]] = []
|
|
63
|
+
for step in steps:
|
|
64
|
+
message = {k: v for k, v in step.items() if k != "meta"} if "meta" in step else step
|
|
65
|
+
if messages and message.get("role") == "user" and messages[-1].get("role") == "user":
|
|
66
|
+
messages[-1] = {**messages[-1], "content": _join_user_content(messages[-1].get("content"), message.get("content"))}
|
|
67
|
+
else:
|
|
68
|
+
messages.append(message)
|
|
69
|
+
return messages
|
|
70
|
+
|
|
71
|
+
|
|
42
72
|
async def call_agent(steps_history: list, system_instruction: str, tool_names: list[str] | None = None, stream: bool = False):
|
|
43
73
|
if tool_names is None:
|
|
44
74
|
tool_names = default_tool_names()
|
|
45
75
|
active_schemas = [TOOL_SCHEMAS[name] for name in tool_names if name in TOOL_SCHEMAS]
|
|
46
|
-
messages = [{"role": "system", "content": system_instruction}] + steps_history
|
|
76
|
+
messages = [{"role": "system", "content": system_instruction}] + provider_messages(steps_history)
|
|
47
77
|
request = build_request_kwargs(stream)
|
|
48
78
|
|
|
49
79
|
span = tracer.start_span("model_call")
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""The system prompt and the per-turn context, shared by the TUI and `dostuff -p` (headless)."""
|
|
2
2
|
import asyncio
|
|
3
3
|
from pathlib import Path
|
|
4
4
|
from typing import Any
|
|
@@ -10,6 +10,7 @@ from dostuff.helpers.agent.constants import (
|
|
|
10
10
|
from dostuff.helpers.agent.environment_context import build_environment_block
|
|
11
11
|
from dostuff.helpers.agent.load_identity import load_identity
|
|
12
12
|
from dostuff.helpers.agent.load_project_instructions import load_project_instructions
|
|
13
|
+
from dostuff.helpers.agent.turn_context import compose_turn_context
|
|
13
14
|
from dostuff.helpers.skills.discover_skills import discover_skills
|
|
14
15
|
from dostuff.helpers.ui.emit import emit
|
|
15
16
|
from dostuff.lib.memory import chroma
|
|
@@ -26,7 +27,7 @@ def _background_wait(interactive: bool) -> str:
|
|
|
26
27
|
def skills_summary(skills: list[dict[str, Any]]) -> str:
|
|
27
28
|
"""The skills list as the system prompt shows it."""
|
|
28
29
|
summary = "\n\n".join(
|
|
29
|
-
f"- name: {s['name']}\n description: {s['description']}\n
|
|
30
|
+
f"- name: {s['name']}\n description: {s['description']}\n dir: {s['dir']}"
|
|
30
31
|
for s in skills
|
|
31
32
|
)
|
|
32
33
|
return summary or "(none available)"
|
|
@@ -67,8 +68,16 @@ def build_base_instructions(interactive: bool = False) -> tuple[str, list[dict[s
|
|
|
67
68
|
return instructions, skills
|
|
68
69
|
|
|
69
70
|
|
|
70
|
-
|
|
71
|
-
"""
|
|
71
|
+
def build_system_instructions(base: str) -> str:
|
|
72
|
+
"""The system prompt of every turn: `base`, byte for byte. Anything that changes per turn goes in
|
|
73
|
+
`build_turn_context` instead: one differing byte here invalidates the provider's whole cached prefix."""
|
|
74
|
+
return base
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
async def build_turn_context(user_text: str, *, memory_store: Any, episodic_store: Any, user_id: str,
|
|
78
|
+
prompt_context: str = "") -> str:
|
|
79
|
+
"""The turn's hidden context step: the environment block, memories and past episodes relevant to user_text,
|
|
80
|
+
and UserPromptSubmit context.
|
|
72
81
|
|
|
73
82
|
The stores are None when long-term memory is off (chromadb not installed): no recall then.
|
|
74
83
|
"""
|
|
@@ -98,9 +107,5 @@ async def build_turn_instructions(base: str, user_text: str, memory_store: Any,
|
|
|
98
107
|
for ep in episodes
|
|
99
108
|
)
|
|
100
109
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
instructions += f"\n\n<relevant_user_facts>\n{memory_text}\n</relevant_user_facts>"
|
|
104
|
-
if episodic_text:
|
|
105
|
-
instructions += f"\n\n<past_episodes>\n{episodic_text}\n</past_episodes>"
|
|
106
|
-
return instructions
|
|
110
|
+
environment = await asyncio.to_thread(build_environment_block)
|
|
111
|
+
return compose_turn_context(environment, memory_text, episodic_text, prompt_context)
|