Skip to content

docs: update docs for --lean TUI, --session new-id, and hook agent_name #3136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dgageot merged 4 commits into from
Jun 16, 2026
+12 −5
Merged

docs: update docs for --lean TUI, --session new-id, and hook agent_name #3136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d48c94d
docs(cli): document --session new-id behaviour
aheritier Jun 16, 2026
768692d
docs(cli): expand --lean flag description
aheritier Jun 16, 2026
bf270f9
docs(hooks): add agent_name to pre/post_tool_use event fields
aheritier Jun 16, 2026
d659017
docs(hooks): extend agent_name note to cover permission_request
aheritier Jun 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/configuration/hooks/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,10 +252,10 @@ In addition to the common fields, each event ships its own payload:

| Event | Extra fields |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `pre_tool_use` | `tool_name`, `tool_use_id`, `tool_input` |
| `pre_tool_use` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input` |
| `tool_response_transform` | `tool_name`, `tool_use_id`, `tool_input`, `tool_response` |
| `post_tool_use` | `tool_name`, `tool_use_id`, `tool_input`, `tool_response`, `tool_error` |
| `permission_request` | `tool_name`, `tool_use_id`, `tool_input` |
| `post_tool_use` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input`, `tool_response`, `tool_error` |
| `permission_request` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input` |
| `session_start` | `source` — one of `startup`, `resume`, `clear`, `compact` |
| `user_prompt_submit` | `prompt` — the text the user just submitted |
| `user_steering_messages_submit` | `steering_messages` — the drained steering messages, in submission order |
Expand All @@ -282,6 +282,7 @@ In addition to the common fields, each event ships its own payload:
Notes:

- `tool_response` for `post_tool_use` carries the tool's result; `tool_error` is `true` when the tool failed (the failure detail is surfaced inside `tool_response`).
- `agent_name` on `pre_tool_use`, `post_tool_use`, and `permission_request` identifies the agent that issued the tool call — in multi-agent setups this follows the active sub-agent, not always the root agent.
- `prompt` is only populated for `user_prompt_submit`. Sub-sessions (transferred tasks, background agents, skills) do **not** fire this event because their kick-off message is synthesised by the runtime, not authored by the user.
- `steering_messages` is only populated for `user_steering_messages_submit`. It carries the user messages the runtime just drained from the steering queue — messages submitted while the agent was already working (mid-turn, after the model stopped, or while idle before the first model call).
- `prompt` is also populated for `user_followup_submit`, carrying the text of the dequeued follow-up message (a user message queued for end-of-turn processing via the FollowUp API / queue, as opposed to mid-turn steering).
Expand Down
10 changes: 8 additions & 2 deletions docs/features/cli/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,15 @@ $ docker agent run [config] [message...] [flags]
| `-a, --agent <name>` | Run a specific agent from the config |
| `--yolo` | Auto-approve all tool calls |
| `--model <ref>` | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. |
| `--session <id>` | Resume a previous session. Supports relative refs (`-1` = last, `-2` = second to last) |
| `--session <id>` | Resume a previous session. Supports relative refs (`-1` = last, `-2` = second to last). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. |
| `-s, --session-db <path>` | Path to the SQLite session database (default: `~/.cagent/session.db`) |
| `--session-read-only` | Open the TUI in read-only mode: conversation history is displayed but no new messages can be sent to the LLM. Cannot be used with `--exec`. |
| `--prompt-file <path>` | Include file contents as additional system context (repeatable) |
| `--attach <path>` | Attach an image file to the initial message |
| `--dry-run` | Initialize the agent without executing anything (useful for validating a config) |
| `--remote <addr>` | Use a remote runtime at the given address instead of running the agent locally |
| `--listen <addr>` | Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. See the [API Server]({{ '/features/api-server/' | relative_url }}#listen). |
| `--lean` | Use a simplified TUI with minimal chrome |
| `--lean` | Use a simplified, non-alternate-screen TUI. Unlike the default full-screen TUI, this renders inline in the normal terminal buffer — useful in environments where an alternate screen is unwanted (e.g. inside tmux panes, CI with a tty, or log-friendly pipelines). |
| `--app-name <name>` | Override the application name label shown in the TUI (status bar, window title, "/exit" notifications). |
| `--sidebar` | Control sidebar visibility. Set to `--sidebar=false` to hide the sidebar and disable the Ctrl+B toggle (default: `true`). |
| `--disable-commands <list>` | Hide and disable specific slash commands in the TUI. Accepts a comma-separated list of command names (leading slash optional, case-insensitive). E.g. `--disable-commands="/cost,/eval,/model"`. |
Expand Down Expand Up @@ -100,6 +100,12 @@ $ docker agent run --agent-picker
$ docker agent run --agent-picker=agentcatalog/coder,agentcatalog/researcher
```

<div class="callout callout-tip" markdown="1">
<div class="callout-title">Lean, inline TUI
</div>
<p>Pass <code>--lean</code> to get a lightweight TUI that renders inline in your terminal (no alternate screen). It supports the same slash commands and streaming output as the full TUI, making it handy inside tmux, scripts, or any context where a full-screen takeover is unwanted.</p>
</div>

<div class="callout callout-tip" markdown="1">
<div class="callout-title">Isolate a run in a git worktree
</div>
Expand Down
Loading