Skip to content

docs: sync documentation with recent code changes #2923

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

Closed
aheritier wants to merge 2 commits into from
Closed

docs: sync documentation with recent code changes #2923

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
417318c
docs: sync documentation with recent code changes
aheritier May 29, 2026
63d93a3
docs: clarify --sidebar default value in CLI reference
aheritier May 29, 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
4 changes: 2 additions & 2 deletions docs/configuration/hooks/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,7 @@ In addition to the common fields, each event ships its own payload:
| `turn_start` | _none_ (just the common fields) |
| `turn_end` | `agent_name`, `reason` — one of `normal`, `continue`, `steered`, `error`, `canceled`, `hook_blocked`, `loop_detected` |
| `before_llm_call` | `iteration` — 1-based run-loop iteration counter (the model call this hook is gating) |
| `after_llm_call` | `agent_name`, `stop_response`, `last_user_message` |
| `after_llm_call` | `agent_name`, `model_id`, `stop_response`, `last_user_message` |
| `session_end` | `reason` — one of `clear`, `logout`, `prompt_input_exit`, `other` |
| `pre_compact` | `source` — one of `manual`, `auto`, `overflow`, `tool_overflow` |
| `before_compaction` | `input_tokens`, `output_tokens`, `context_limit`, `compaction_reason` (one of `threshold`/`overflow`/`manual`) |
Expand Down Expand Up @@ -547,7 +547,7 @@ The `reason` field classifies the exit:

`before_llm_call` fires immediately before every model call (after `turn_start` has assembled the messages). It cannot contribute context — use `turn_start` for that — but it can **stop the run** by returning `decision: block` (or exit code 2). The built-in `max_iterations` hook implements a hard cap on top of this event.

`after_llm_call` fires immediately after each successful model call, before the response is recorded into the session and tool calls are dispatched. The assistant text is in `stop_response`. Use it for response auditing, redaction logging, or quality metrics. Failed model calls fire `on_error` instead.
`after_llm_call` fires immediately after each successful model call, before the response is recorded into the session and tool calls are dispatched. The assistant text is in `stop_response`. The model used for the call is in `model_id` (e.g. `anthropic/claude-sonnet-4-5`). Use it for response auditing, redaction logging, or quality metrics. Failed model calls fire `on_error` instead.

### Before/After-Compaction: structured compaction control

Expand Down
3 changes: 3 additions & 0 deletions docs/features/cli/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ $ docker agent run [config] [message...] [flags]
| `--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 |
| `--lean` | Use a simplified TUI with minimal chrome |
| `--app-name <name>` | Application name shown in the TUI in place of "docker agent" |
| `--sidebar` | Show the sidebar in the TUI; enabled by default (pass `--sidebar=false` to hide it) |
| `--disable-commands <list>` | Comma-separated list of slash commands to hide and disable in the TUI (e.g. `/cost,/eval,/model`) |
| `--json` | Output results as newline-delimited JSON (use with `--exec`) |
| `--hide-tool-calls` | Hide tool calls in the output |
| `--hide-tool-results` | Hide tool call results in the output |
Expand Down
12 changes: 6 additions & 6 deletions docs/features/remote-mcp/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,19 +114,19 @@ When running `docker-agent serve api` (no local browser, no callback server), th

| Key | Value |
| ---------------------------- | ---------------------------------------------------------------- |
| `cagent/type` | `"oauth_flow"` |
| `cagent/server_url` | The MCP server URL (for display / favicon) |
| `cagent/authorize_url` | The full URL the client should open in the user's browser |
| `cagent/state` | The `state` value the client must echo back when replying |
| `docker-agent/type` | `"oauth_flow"` |
| `docker-agent/server_url` | The MCP server URL (for display / favicon) |
| `docker-agent/authorize_url` | The full URL the client should open in the user's browser |
| `docker-agent/state` | The `state` value the client must echo back when replying |
| `auth_server` | Issuer of the authorization server |
| `auth_server_metadata` | RFC 8414 authorization-server metadata document |
| `resource_metadata` | RFC 9728 protected-resource metadata document |

The client opens the browser at `cagent/authorize_url`, receives the OAuth callback at whatever endpoint the configured `redirect_uri` resolves to (typically a host-controlled bouncer that 302s into a deeplink), and replies to the elicitation with `accept` and `Content = {"code": "...", "state": "..."}`. The runtime verifies the `state`, exchanges the `code` at the token endpoint (using the same `redirect_uri` for RFC 6749 §4.1.3 binding), stores the token, and replays the original MCP request with `Authorization: Bearer ...`.
The client opens the browser at `docker-agent/authorize_url`, receives the OAuth callback at whatever endpoint the configured `redirect_uri` resolves to (typically a host-controlled bouncer that 302s into a deeplink), and replies to the elicitation with `accept` and `Content = {"code": "...", "state": "..."}`. The runtime verifies the `state`, exchanges the `code` at the token endpoint (using the same `redirect_uri` for RFC 6749 §4.1.3 binding), stores the token, and replays the original MCP request with `Authorization: Bearer ...`.

- **Flag not set** (legacy): the runtime emits only `auth_server_metadata` + `resource_metadata`; the client is expected to drive the OAuth flow itself (PKCE, DCR, token exchange) and reply with `Content = {"access_token": "...", "refresh_token": "...", ...}`.

The legacy `{access_token, ...}` reply shape is still accepted on the `--mcp-oauth-redirect-uri` path too: a client that prefers to do the exchange itself can ignore the `cagent/authorize_url`/`cagent/state` keys.
The legacy `{access_token, ...}` reply shape is still accepted on the `--mcp-oauth-redirect-uri` path too: a client that prefers to do the exchange itself can ignore the `docker-agent/authorize_url`/`docker-agent/state` keys.

A per-toolset `callbackRedirectURL` (in the YAML) overrides the runtime-wide `--mcp-oauth-redirect-uri` for that toolset.

Expand Down
Loading