From d48c94d442dffd1eb1881f1f61db619bec2da77b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 16 Jun 2026 04:03:07 +0000 Subject: [PATCH 1/4] docs(cli): document --session new-id behaviour An explicit --session ID that doesn't exist creates a new session with that ID (refs #3119). Update the --session flag description to reflect this. --- docs/features/cli/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/cli/index.md b/docs/features/cli/index.md index a970c65a3..633542694 100644 --- a/docs/features/cli/index.md +++ b/docs/features/cli/index.md @@ -30,7 +30,7 @@ $ docker agent run [config] [message...] [flags] | `-a, --agent ` | Run a specific agent from the config | | `--yolo` | Auto-approve all tool calls | | `--model ` | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. | -| `--session ` | Resume a previous session. Supports relative refs (`-1` = last, `-2` = second to last) | +| `--session ` | 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 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 ` | Include file contents as additional system context (repeatable) | From 768692de133a125575089c4fe117ddb31c5ac045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 16 Jun 2026 04:03:28 +0000 Subject: [PATCH 2/4] docs(cli): expand --lean flag description Clarify that --lean uses a non-alternate-screen render and when it's useful. Add a callout tip in the cli reference (refs #3127). --- docs/features/cli/index.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/features/cli/index.md b/docs/features/cli/index.md index 633542694..4620b4ef6 100644 --- a/docs/features/cli/index.md +++ b/docs/features/cli/index.md @@ -38,7 +38,7 @@ $ docker agent run [config] [message...] [flags] | `--dry-run` | Initialize the agent without executing anything (useful for validating a config) | | `--remote ` | Use a remote runtime at the given address instead of running the agent locally | | `--listen ` | 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 ` | 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 ` | 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"`. | @@ -100,6 +100,12 @@ $ docker agent run --agent-picker $ docker agent run --agent-picker=agentcatalog/coder,agentcatalog/researcher ``` +
+
Lean, inline TUI +
+

Pass --lean 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.

+
+
Isolate a run in a git worktree
From bf270f969cd4b54178fc5443c5281bc179335a05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 16 Jun 2026 04:03:47 +0000 Subject: [PATCH 3/4] docs(hooks): add agent_name to pre/post_tool_use event fields pre_tool_use and post_tool_use now populate agent_name in the hook Input, matching every other event type. Update the event extra-fields table and add a note explaining what agent_name refers to in multi-agent setups (refs #3110). --- docs/configuration/hooks/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/configuration/hooks/index.md b/docs/configuration/hooks/index.md index 25986c506..65e538259 100644 --- a/docs/configuration/hooks/index.md +++ b/docs/configuration/hooks/index.md @@ -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 | @@ -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` and `post_tool_use` 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). From d659017dc8ed41d23f00d2fa88d2fff654c65c0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 16 Jun 2026 04:07:40 +0000 Subject: [PATCH 4/4] docs(hooks): extend agent_name note to cover permission_request The note added in the PR omitted permission_request even though the table above it already lists agent_name for that event. Extend the note to cover all three (refs #3110). --- docs/configuration/hooks/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/hooks/index.md b/docs/configuration/hooks/index.md index 65e538259..37ef7f2bc 100644 --- a/docs/configuration/hooks/index.md +++ b/docs/configuration/hooks/index.md @@ -282,7 +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` and `post_tool_use` identifies the agent that issued the tool call — in multi-agent setups this follows the active sub-agent, not always the root agent. +- `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).