@wardby/cli 0.7.0 → 0.9.0

package/dist/wardby-bin.js

@@ -52,6 +52,11 @@ async function main() {
         const { resumeToolsCommand } = await import("./coding/transcript/resume/stand-in.js");
         await resumeToolsCommand(process.argv.slice(3));
     }
+    else if (command === "claude-plugin") {
+        // Sets up the Claude Code plugin on this machine: no environment, database, or server runtime.
+        const { claudePluginCommand } = await import("./claude-plugin/command.js");
+        process.exitCode = await claudePluginCommand(process.argv.slice(3));
+    }
     else if (command === "knowledge") {
         // Offline bundle validation: no environment, database, or HTTP runtime.
         const { knowledgeCommand } = await import("./knowledge/cli.js");

package/docs/README.md

@@ -13,16 +13,26 @@
   runs are billed.
 - [Agent recipes](agent-recipes.md) gives two copyable setups, an architecture
   keeper and a per-language builder, with the prerequisites each needs.
+- [Debugging an agent run](debugging-agent-runs.md) triages a run that failed,
+  opened no pull request, or missed what you expected.
 - [Coding-agent setup](coding-agent-setup.md) configures the local trusted proxy
   and isolated Codex or Claude Code workers.
+- [Claude Code plugin](claude-code-plugin.md) (0.8.0+) installs the `wardby-runs`
+  pane: your runs beside the chat, grouped by pull request, with run details and
+  Continue locally.
 - [Architecture knowledge bundles](knowledge.md) covers `docs/knowledge/`: the
   concept format, how coding runs and reviewers use it, `wardby knowledge check`,
   and the scheduled architecture agent.
-- [Native sandbox](native-sandbox.md) (0.5.4+) runs a native agent's turn loop and user
+- [Native sandbox](native-sandbox.md) (0.6.0+) runs a native agent's turn loop and user
   tools in a single-use, credential-free container behind a native gateway.
 - [Secrets and tools](tool-secrets.md) covers readable and brokered secrets
   (brokered secrets require 0.6.0+):
   attaching secrets to tools, `set_secret_broker`, placements, and errors.
+- [Remote MCP servers](mcp-servers.md) (0.8.0+) registers a remote MCP server and
+  attaches an allowlist of its tools to a native agent.
+- [Host providers](host-providers.md) (0.8.0+) covers adding a code host with
+  your own custom tools: registering, approving, testing and removing a
+  provider.
 - [Coding-worker isolation](coding-worker-isolation.md) documents the threat
   model and enforced worker boundary.
 - [Bring-your-own worker images](coding-worker-byo-images.md) explains how to

package/docs/agent-recipes.md

@@ -383,8 +383,9 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
 { "id": "<lead agent id>", "maxDelegationsPerRun": 6 }
 ```
 
-- Each `delegate_to_<name>` call still goes to a different sub-agent; a second
-  call to the same one in the same run is refused with `already_dispatched`.
+- A run delegates to each sub-agent and repository at most once: a second call
+  to the same sub-agent in the same run (for a coding sub-agent with a list of
+  repositories, in the same repository) is refused with `already_dispatched`.
   A delegation waiting for budget (see below) also holds its place against
   `maxDelegationsPerRun`: a call beyond the limit is refused with
   `already_dispatched` and a message naming both counts, e.g. "This run
@@ -507,6 +508,37 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
   repositories, keep that work in separate requests (separate Jira issues, or
   separate lead agents).
 
+#### One coding agent, several repositories
+
+Instead of one builder per repository, give one coding builder a list: its default in
+`codingProfile.repository`, and each other repository with `link_repository`
+(`access: "write"`, no triggers). The lead then names the repository on each
+call, and may delegate to the same builder once per repository:
+
+```json
+{ "task": "Add the /quotes endpoint the client will call.", "repository": "your-org/api", "mergeOrder": 1 }
+```
+
+```json
+{ "task": "Add the quotes page that calls /quotes.", "repository": "your-org/web", "mergeOrder": 2 }
+```
+
+Set `maxDelegationsPerRun` (up to 20) for the number of calls, and use
+`mergeOrder` where the pull requests must land in order. A call without
+`repository` is refused with `repository_required` when the builder has extra
+repositories (unless it continues a prior run with `continuePriorRun`), and a
+repository not on the list with `repository_not_listed`. A native sub-agent
+refuses `repository` with `repository_requires_coding_agent`. The lead sees the
+list in the tool definition only when it has the same owner as the builder, or
+another owner with execute access to a builder that sets
+`allowWebhookTaskOverride`. All repositories share the builder's toolchain,
+budget and prompt.
+
+Being on the list lets a run work in a repository; it starts nothing there. Link
+the lead and the reviewer on each listed GitHub repository with the triggers
+they need, or a pull request opened there gets no review, mention follow-up, fix
+round or mark-ready.
+
 #### Follow-ups across the set
 
 A human-triggered follow-up task (an `@<app-slug>` mention, or a Jira issue
@@ -520,8 +552,9 @@ too:
     repository that already has an open sibling for this request.
 
 The usual delegation rails still apply on top of this: `maxDelegationsPerRun`
-caps calls per run; a second `delegate_to_<name>` call to the same sub-agent
-in one run is refused with `already_dispatched`; dispatch re-checks every
+caps calls per run; a run delegates to each sub-agent and repository at most
+once, and a second such call is refused with `already_dispatched`; dispatch
+re-checks every
 `continuePriorRun` id (refusing with `continuation_refused` when this
 deployment can't continue the run it names — for example it belongs to a
 different owner's agent); every push to a sibling pull request still gets its

package/docs/architecture-runtime.md

@@ -95,7 +95,7 @@ and GKE Autopilot overlays.
 
 ### Native agents in a sandbox
 
-Native sandbox requires Wardby 0.5.4 or later.
+Native sandbox requires Wardby 0.6.0 or later.
 
 Native agents run in the server process by default. A native agent set to
 `nativeExecutionMode=sandbox` instead runs its turn loop and user tools in a

package/docs/claude-code-plugin.md

@@ -0,0 +1,208 @@
+# Claude Code plugin: the wardby runs pane
+
+From Wardby 0.8.0, the `wardby-runs` Claude Code plugin shows your wardby agent
+runs in a pane beside the chat. It lists runs grouped by pull request, shows a
+run's request, outcomes, services, errors and final answer, and can continue a
+finished Claude Code run in your own terminal.
+
+The plugin lives in this repository under `plugins/claude-code/`, and the
+repository is its marketplace (`.claude-plugin/marketplace.json`). It talks only
+to the wardby MCP server your Claude Code session already has, through
+`list_runs`, `list_agents`, `get_run`, `get_run_steps` and `get_run_transcript`,
+so it shows exactly what those tools show you and needs no token of its own.
+
+## Install
+
+### With the wardby CLI
+
+```sh
+npx @wardby/cli@latest claude-plugin install
+```
+
+This installs the plugin from `wardby/wardby` and offers to allow the pane's
+read-only tools for auto mode (see [Permissions](#permissions)). Options:
+
+| Option                 | What it does                                                                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--server-url <url>`   | Registers the wardby MCP server at this `https` URL (for example `https://wardby.example.com/mcp`) when Claude Code has none named `wardby`             |
+| `--server-name <name>` | The MCP server the pane uses, as `/mcp` lists it (default `wardby`); the allow rules it adds follow the name, for example `mcp__wardby-prod__list_runs` |
+| `--marketplace <src>`  | Installs from another marketplace: an operator's own repository (`your-org/claude-plugins`) or a local folder                                           |
+| `--allow-tools`        | Allows the pane's read-only tools without asking; `--no-allow-tools` leaves permission rules alone                                                      |
+| `--fullscreen`         | Also switches Claude Code's terminal to its fullscreen view (see [Terminal](#in-the-terminal)); it applies to every session                             |
+| `--yes`                | Answers yes to every question                                                                                                                           |
+
+`wardby quickstart` offers the same install once it has connected Claude Code
+(`--claude-plugin` installs it without asking, `--no-claude-plugin` skips it),
+and `wardby doctor` lists the plugin, the MCP server and the allow rules
+alongside its other checks, without failing when the optional pane is missing.
+
+`wardby claude-plugin status` reports whether the plugin, the MCP server and
+the allow rules are in place. `wardby claude-plugin uninstall` removes the
+plugin and only the settings install added: the rules it added and the
+fullscreen view if it switched it on. It leaves the MCP server in place.
+
+The CLI writes to the settings file of the Claude Code it finds:
+`$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`. It refuses a
+settings file that isn't valid JSON instead of overwriting it.
+
+### In Claude Code
+
+At the prompt of a terminal session:
+
+```
+/plugin install wardby-runs --marketplace wardby/wardby
+```
+
+In the desktop app, where `/plugin` doesn't run: click **+** next to the prompt
+box, then **Plugins**, **Add marketplace** with `wardby/wardby`, then **Add
+plugin**. A plugin installed from a terminal at user scope also loads in the
+desktop app's local Code sessions that read the same Claude Code configuration.
+
+Open the pane with `/wardby-runs`; `/wardby-runs close` closes it and
+`/wardby-runs clear` clears its filters.
+
+### The MCP server
+
+The pane needs an MCP server named `wardby` in Claude Code. `wardby quickstart`
+registers one; for a deployed instance, add it with `--server-url` above or:
+
+```sh
+claude mcp add --transport http --scope user wardby https://wardby.example.com/mcp
+```
+
+then sign in with `/mcp`. Another name works too: set the plugin's **wardby MCP
+server** option to it. A server added through the Claude apps' **Connectors**
+settings is not a Claude Code MCP server and the pane doesn't use it. With another
+name, install with `--server-name <name>` so the allow rules match it, and the
+pane's own hints name it too.
+
+## Permissions
+
+The pane reads only, with the caller's own access:
+
+| Pane feature         | MCP tool             | Scope         | What you see                                                                   |
+| -------------------- | -------------------- | ------------- | ------------------------------------------------------------------------------ |
+| Run list             | `list_runs`          | `agents:read` | All runs of agents you own, and the runs you started on agents shared with you |
+| Agent names, budgets | `list_agents`        | `agents:read` | Agents you can see (the pane asks for `summary: true`)                         |
+| Run detail           | `get_run`            | `agents:read` | Runs you started, or of agents you own                                         |
+| Recent steps, Steps  | `get_run_steps`      | `agents:read` | Same as `get_run`                                                              |
+| Continue locally     | `get_run_transcript` | `agents:read` | Same as `get_run`                                                              |
+
+Under Claude Code's auto mode, a plugin's MCP calls go through the same safety
+check as any other, and calls the pane makes on its own timer are refused
+unless allowed. Allow these in `/permissions` (or let `wardby claude-plugin
+install` add them): `mcp__wardby__list_runs`, `mcp__wardby__list_agents`,
+`mcp__wardby__get_run`, `mcp__wardby__get_run_transcript` and
+`mcp__wardby__get_run_steps`. The pane never calls `stop_run` or any other tool
+that changes something. When a call is refused, the pane says which rules to
+add.
+
+Plugins are not sandboxed: they run as you. **Continue locally** runs
+`npx @wardby/cli@latest resume - --print` in the folder you give it, passing the
+transcript's download link on standard input; the link is never drawn, stored
+or logged. The import writes only under `~/.wardby/` and the new worktree.
+
+## Using the pane
+
+- **Ledger** (desktop): runs grouped by pull request (or Jira issue), each group
+  one row with its state and total cost, folded once every run in it finished.
+  A pull request with one run is one line. Runs that touch no pull request are
+  under **Other**. The newest run comes first: groups (Other too) are ordered by
+  their newest run, and so are the runs in a group. Each line names its step (opened, review, fix 1, …), with
+  sub-agent runs under their lead, and shows the run's status as a coloured
+  pill, its spend as "$x of $y", what started it, its task and how long it
+  ran, over a thin budget bar.
+- **Strips** (desktop): one card per pull request, its steps drawn as a row of
+  dots; click a step's name to see it.
+- **Filters**: show all, active, failed or finished runs, or type to match an
+  agent, status, trigger or task.
+- **Run detail**: a header with the run's status, short id, repository, model,
+  duration and budget bar, then a card each for what started the run (with its
+  request), what it produced, the run tree, services (ready, starting or
+  failed), steps, the final answer and **Continue locally** for finished Claude
+  Code runs with `sessionResume` on (see [Resume Claude Code runs locally](coding-agent-setup.md#resume-a-run-locally)).
+  Each kind of card has its own colour, the same on every run: a thin bar
+  along its top on the desktop, its rounded border in the terminal.
+  The request and final answer show about three lines, as markdown, then how
+  many more; **Show full text** shows all of it. The pull request link and the
+  other actions sit at the bottom.
+- **Copy**: on the desktop, each card (and an error, and an open step's detail)
+  has a **Copy** button that copies its full text as the server sent it. In the
+  terminal, **Copy section** (`y`) copies the open step's detail; **Copy run
+  id** is on both.
+- **Recent steps** (a running run's detail): its last 8 steps, refreshed with
+  the run. A tool step is one row: its result at the left (✓ when it passed,
+  the exit code of a failed command, or ! for an error), then the tool and its
+  command or file; on the desktop a long command is cut with "…". What the
+  model said wraps to about two lines.
+- **Steps** (a finished run's detail): every recorded step, 200 at a time;
+  **More steps** loads the next 200.
+- **Step detail**: From 0.9.0, a step with detail, or a longer message, has a
+  ▸ at its right that opens it (▾ closes it); in the terminal, `j`/`k` also
+  move between such steps and `e` shows or hides one. One step is open at a
+  time. An open command shows "$ command", its exit status and its output;
+  Codex's framing lines (chunk id, wall time, token count) are left out, and
+  **Copy** still copies the detail exactly as stored. Detail appears only for
+  the agent's owner and the run's starter (and the stdio operator), on a
+  server at the detail level. An open detail shows its last 40 lines, with a
+  count of the lines above them.
+- **Last step**: in the list, a running or failed run shows its newest step
+  under the agent's name.
+
+Steps come from the server's run steps (see
+[Run steps](debugging-agent-runs.md#run-steps)): they need a server that has
+`get_run_steps` and records steps (Wardby 0.9.0 or later). Against an older
+server the pane shows no steps and checks again every few refreshes. When the
+server has steps off (`WARDBY_RUN_STEPS=off`) the detail says "Steps are off on
+this server." A run with no recorded steps shows none. If you installed the pane
+before run steps, run `wardby claude-plugin install` again (or allow
+`mcp__wardby__get_run_steps` in `/permissions`): under auto mode the pane
+otherwise shows which rule to add in place of the steps. `wardby claude-plugin
+status` and `wardby doctor` name the missing rule.
+
+The pane refreshes every 10 seconds while a run is active and every 60 seconds
+otherwise (the plugin's **pollSeconds** and **idleSeconds** options), asks only
+for what changed since its last refresh, backs off when the server fails, and
+polls only while it is open.
+
+### In the terminal
+
+Claude Code's classic terminal view draws a plugin pane as a band above the
+prompt and doesn't pass mouse clicks to plugins: use the keyboard (ctrl+x tab
+focuses the pane, then `1`–`9` open a run, `r` refreshes, `b` goes back, `m`
+shows full text, `y` copies an open step's detail, `x` or Escape closes). In the fullscreen view the pane is a side bar beside the chat
+and takes clicks. Turn it on with `"tui": "fullscreen"` in your Claude Code
+settings (or `--fullscreen` above, or `CLAUDE_CODE_NO_FLICKER=1`), then restart
+Claude Code. The desktop app needs none of this.
+
+## Add it to your own marketplace
+
+The plugin keeps everything it needs in `plugins/claude-code/` and has no
+instance-specific values, so an operator can list it in their organization's
+marketplace. Point an entry at this repository's subfolder, pinned to a
+release:
+
+```json
+{
+  "name": "wardby-runs",
+  "source": {
+    "source": "git-subdir",
+    "url": "wardby/wardby",
+    "path": "plugins/claude-code",
+    "ref": "v0.8.0"
+  }
+}
+```
+
+Preset its options for your users in managed settings under
+`pluginConfigs["wardby-runs@<your marketplace>"].options` (for example the MCP
+server's name), and ship the allow rules above in the same managed settings.
+When managed settings set `allowManagedHooksOnly`, a plugin a user installs
+loads no hooks: install it through managed settings instead.
+
+## Limits
+
+- Plugins draw in the Claude Code terminal, the desktop app's Code tab and VS
+  Code; not in claude.ai/code, `claude -p`, the Agent SDK or WSL.
+- The pane polls; there is no push.
+- A run's live steps and a readable transcript are not shown yet.

package/docs/code-review-agents.md

@@ -574,6 +574,12 @@ requires more than owning the agent:
 - **A repository is the owner's binding.** Principals the agent is shared
   with (`grant_access`) can't link, unlink or change its repository, even at
   `write`.
+- **A coding agent's extra repositories follow the same rules.** A
+  `link_repository` call with `access: "write"` and no triggers on a coding
+  agent adds a repository its runs may work in; it needs the same GitHub write
+  access or admin approval as the default repository. Unlinking it
+  refuses queued runs for that repository when they start, and a run already under way is refused at
+  its final push check (`repo_access`), so nothing is pushed.
 
 The authorization is stamped on the link (`authorizedVia`: `host_permission`,
 `admin`, or `grandfathered`) and **checked again every time it is used**: on

package/docs/coding-agent-setup.md

@@ -69,6 +69,81 @@ request currently targets, and the agent resolves any conflicts — see
 Over stdio, the local operator holds every role, so `repositoryAdminOverride`
 is the way to approve a repository there.
 
+## A coding agent's repositories
+
+A coding agent works in one repository per run, chosen from its list:
+
+- `codingProfile.repository` is the **default** repository.
+- `link_repository` adds more. A link on a coding agent takes
+  `access: "write"`, no triggers, no `checkName` and an optional `baseRef`
+  (the base branch for runs in that repository; default: the profile's
+  `baseRef`). The repository must be on GitHub or a `local:` path. Linking the
+  default repository again is refused.
+- `unlink_repository` removes one.
+
+```json
+{ "agentId": "<agent id>", "repository": "your-org/other-repo", "access": "write", "baseRef": "main" }
+```
+
+Only the agent's owner (or an admin approving explicitly with `adminOverride`)
+can add a repository, and the same authorization applies as for the default;
+see [Repository authorization](#repository-authorization).
+
+The repository is chosen when the run starts and never changes during it:
+
+- `trigger_agent` takes an optional `repository`. Leave it out and the run uses
+  the default repository. Name one that is not on the list and the call is
+  refused with `repository_not_listed`. Only the agent's owner can pass
+  `repository`, unless `codingProfile.allowWebhookTaskOverride` is on; anyone
+  else is refused with a 403.
+- A webhook body can carry `wardbyRepository` the same way (not `repository`,
+  which forwarded payloads already use). A refused value is a 400
+  `{ "error": "invalid_repository" }`. A webhook can carry `wardbyRepository`
+  only when `codingProfile.allowWebhookTaskOverride` is on, whoever created
+  the webhook. With the flag off a well-formed value is refused with 403
+  `{ "error": "disabled" }`, before it is compared with the list; a malformed
+  one (not a string, empty, or over 300 characters) is a 400 either way.
+- A lead's `delegate_to_<name>` call takes `repository`. When the sub-agent has
+  more than its default repository the call must name one, unless
+  `continuePriorRun` is given: a follow-up works in the repository of the run
+  it continues. Without a choice the call is refused with
+  `repository_required`.
+
+Everything else about the agent is shared across its repositories: toolchain,
+worker image, services, system prompt, budget, protected paths and the package
+allowlist. If two repositories need different ones, use two agents.
+
+Being on the list lets a run work in a repository; it starts nothing there.
+Reviews, mention follow-ups, fix rounds and mark-ready route by repository and
+trigger, so a pull request opened in a linked repository gets none of them by
+itself. For follow-ups, link the lead and the reviewer on each listed GitHub
+repository with the triggers they need.
+
+An agent with no repository links works only in its default repository.
+Changing an agent's `kind` is refused while it has write links without
+triggers; unlink them first.
+
+Every write link without triggers on a coding agent is on its list, whenever it
+was made. An agent converted from native to coding can hold such links from its
+native configuration: run `list_repositories` on converted agents and unlink any
+repository their runs should not work in.
+
+For the refusals, see [Repository required](../help/errors/repository-required.md)
+and [Repository not on the agent's list](../help/errors/repository-not-listed.md).
+
+## See what a run was asked to do
+
+`get_run` returns a coding run's `request`: the task it received from
+`trigger_agent`, a webhook or a lead, or the agent's default task. It leaves out
+the agent's standing instructions. On a delegated run, this shows what the lead
+told the coding agent, so you can tell a vague task from a run that missed a
+clear one.
+
+The value is masked when it's read: the values of the agent's attached secrets
+and token-shaped values are replaced. If the agent's secrets can't be read,
+`get_run` returns `requestUnavailable: true` instead of the text. Runs from
+before this field have no `request`.
+
 ## Local repositories
 
 A coding agent (or a review agent) can work on a git repository on the same
@@ -313,7 +388,8 @@ agents.
 - **`false`.** Bare mode is off. Claude Code loads `CLAUDE.md` and skills
   itself, through its native Skill tool, instead of reading them from the
   system prompt. Repository settings, hooks, MCP configuration, agents, and
-  commands are still never loaded in either mode; native loading also locks
+  commands are still never loaded in either mode (the only MCP tools a coding
+  run has are those of [attached MCP servers](mcp-servers.md#coding-agents)); native loading also locks
   Claude Code's own hooks to wardby's managed set.
 
 If the worker can't write the native-mode context to disk for a run, that
@@ -911,6 +987,23 @@ run's repository and refs, as base64url JSON). A refused download returns
 JSON `{ "error": "<code>" }`; `wardby resume` explains each code (see the
 `errors/run-transcript-download` help article).
 
+## Run steps
+
+Claude Code and Codex runs record their steps (each command with its status, and
+what the model said, one short line each) when the server's run-steps listener is
+set up: `WARDBY_RUN_STEPS_LISTEN` on `wardby serve` and `WARDBY_RUN_STEPS_URL` on
+the coding proxy. Without them, coding runs record no steps. Read the steps with
+`get_run_steps`. The Docker quickstart registers the stdio `wardby mcp` server,
+which never runs the listener, so setting `WARDBY_RUN_STEPS_URL` on its proxy
+alone does nothing: coding runs' steps need a `wardby serve` with
+`WARDBY_RUN_STEPS_LISTEN`. The proxy takes `WARDBY_RUN_STEPS_URL` from the
+environment (for example `http://host.docker.internal:8792`); see
+[Run steps](debugging-agent-runs.md#run-steps) and, for binding the listener
+safely, [Run steps in Security deployment](security-deployment.md#run-steps).
+For a coding agent whose owner sets `runSteps` to `detail`, also set
+`WARDBY_RUN_STEPS=detail` on the proxy, or no tool output is sent; see
+[Run steps](debugging-agent-runs.md#run-steps).
+
 ## Stop the setup
 
 ```sh

package/docs/coding-worker-byo-images.md

@@ -95,8 +95,10 @@ the exact command.
 On a local quickstart install with the Docker launcher, `workerImageRef` can be
 the local image ID (`docker image inspect --format '{{.Id}}' <your-tag>`).
 Otherwise, build it, push it to your own registry, and note the resulting digest —
-`docker inspect --format '{{index .RepoDigests 0}}' <your-tag>` after a push,
-or read it straight from `docker buildx build --push`'s output.
+`docker inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' <your-tag>`
+after a push lists one digest per registry the image is in: take the one in
+the registry your cluster pulls from, not simply the first. Or read it straight
+from `docker buildx build --push`'s output.
 
 ## Pointing an agent at it
 

package/docs/coding-worker-isolation.md

@@ -143,7 +143,8 @@ deeply to process is refused with `request_nesting_too_deep`.
 
 - **Anthropic Messages** (`parseAnthropicRequest`): a fixed set of keys,
   text/`tool_use`/`tool_result`/thinking blocks, exactly the two Wardby tool
-  names, the reviewed beta values, the thinking mode the run's model catalog
+  names plus the run's own MCP tool names (see
+  [Remote MCP tools](#remote-mcp-tools)), the reviewed beta values, the thinking mode the run's model catalog
   entry names, and only effort levels that entry lists in `efforts` (top-level,
   or on an effort-only system message for models that change effort per turn).
 - **OpenAI Responses** (`parseOpenAiRequest`), built from what the pinned
@@ -157,8 +158,15 @@ deeply to process is refused with `request_nesting_too_deep`.
     `previous_response_id`, `conversation` and `metadata`, is refused with
     `openai_request_key_not_allowed:<key>`.
   - Tools: `function` and `custom` definitions, and `namespace` groups of
-    them, either in `tools` or in Codex's `additional_tools` input item. Every
-    other tool type, including all hosted tools (`web_search`, `mcp`,
+    them, either in `tools` or in Codex's `additional_tools` input item. A
+    `tool_search` tool is accepted only in the top-level `tools`, only with
+    `execution: "client"` (Codex runs the search over its own tools) and only
+    with `type`, `execution`, `description` and `parameters`; a
+    server-executed search is refused with
+    `openai_tool_not_allowed:tool_search`. Each tool list holds at most 512
+    tools, and a request at most 512 distinct tools in all; a definition
+    repeated in replayed tool search results counts once. Every other tool
+    type, including all hosted tools (`web_search`, `mcp`,
     `code_interpreter`, `image_generation`, `file_search`, `local_shell`, and
     so on), is refused with `openai_tool_not_allowed:<type>`. Tool names are
     checked for shape (`[A-Za-z0-9_-]{1,128}`) but not against a fixed list:
@@ -169,10 +177,17 @@ deeply to process is refused with `request_nesting_too_deep`.
   - Input items: `message` (`input_text`/`input_image` for user, developer
     and system; `output_text` for assistant), `reasoning`, `function_call`,
     `function_call_output`, `custom_tool_call`, `custom_tool_call_output`,
-    `agent_message` and `additional_tools`, each with only the keys Codex
-    sends. Anything else (`input_file`, `input_audio`, `item_reference`,
-    replayed hosted-tool calls, `compaction`, `local_shell_call`) is refused
-    with `openai_input_not_allowed:<type>`. An `input_image` must be an inline
+    `agent_message`, `additional_tools`, `tool_search_call` and
+    `tool_search_output`, each with only the keys Codex sends. The two tool
+    search items must say `execution: "client"`. A `tool_search_call` may
+    carry only a string `query` and a positive integer `limit` as its
+    arguments. Every tool a `tool_search_output` brings into the conversation
+    passes the same checks as a top-level tool, except another `tool_search`;
+    a `function` there may also carry `defer_loading: true`, which Codex sets
+    on the tools it loads through tool search, and nowhere else. Anything
+    else (`input_file`, `input_audio`, `item_reference`, replayed hosted-tool
+    calls, `compaction`, `local_shell_call`) is refused with
+    `openai_input_not_allowed:<type>`. An `input_image` must be an inline
     `data:image/{png,jpeg,gif,webp};base64,` URL, as Codex's `view_image`
     produces; a remote URL or a `file_id` is refused with
     `openai_remote_input_not_allowed`.
@@ -218,6 +233,62 @@ rather than silently widening what reaches OpenAI. Upgrading the pinned
    then widen `parseOpenAiRequest` only for what that review accepts, and
    document it in the list above.
 
+### Remote MCP tools
+
+A coding agent can have [remote MCP server](mcp-servers.md#coding-agents) tools
+attached. The worker still reaches only the proxy:
+
+1. When a run has MCP tools, the control plane mints a per-run MCP token
+   (`rmt_` plus 32 random bytes, base64url). Only its SHA-256 hash is stored
+   with the run's proxy session; the token reaches the worker only as
+   `WARDBY_MCP_TOKEN`, and is never logged. It is valid only on the proxy's
+   `/mcp` route, and only while the session is active and before its deadline.
+   It is not the run capability, and it is not accepted by the model routes.
+2. The worker (Claude Code or Codex, over HTTP) calls `POST /mcp` on the proxy
+   with `Authorization: Bearer <token>`. The proxy checks the token and
+   forwards the request to the native gateway's `/coding-mcp` route
+   (`WARDBY_MCP_GATEWAY_URL`). The proxy never sees an MCP server's URL or
+   secrets. Without `WARDBY_MCP_GATEWAY_URL`, `/mcp` answers `503`
+   `mcp_unavailable`. A bad or expired token gets a `401` without a
+   `WWW-Authenticate` header, so a client doesn't start OAuth discovery.
+3. The gateway checks the token again (the proxy is not trusted), checks the
+   live attachment on every call, counts the call against the run's limit
+   (`WARDBY_MCP_MAX_CALLS_PER_RUN`, default 100; failed calls count), runs it,
+   and removes the server's secret values from the result before it leaves.
+   Logs for the route carry the method, status and session id, never bodies,
+   arguments, results or the token.
+
+The proxy can reach the gateway's HTTP port. It holds no gateway credentials,
+and each route authenticates separately. The Anthropic allowlist accepts the
+run's own MCP tools as plain client tools named
+`mcp__wardby_mcp__<server>__<tool>`, and only those the run pinned.
+
+Where the token is exposed:
+
+- **Claude Code.** The agent container receives the MCP configuration, its
+  bearer header included, on Claude Code's command line. That container runs no
+  model commands and shares no PID namespace with the tool runner, so commands
+  the model runs can't read it.
+- **Codex.** Shell commands run in the same container as Codex, and can read
+  the token through `/proc`. For that reason a Codex agent may use only tools
+  the server marks `readOnlyHint: true`: Wardby refuses any other tool when you
+  attach, when a run loads its tools, and on every call. `readOnlyHint` is the
+  server's own claim, which Wardby can't verify, so the allowlist remains the
+  owner's control. A leaked token is limited to this run's allowed tools, the
+  call limit and the run's deadline.
+
+A repository's own MCP configuration is never loaded. MCP tools need this
+release's Claude worker image and a new Codex driver image; an older image
+ignores the token and gets no MCP tools, and the run does not fail. Codex
+models that use tool search get their MCP tools through `tool_search_output`
+items; the proxy checks every tool in them like a top-level tool (see
+[Model request allowlist](#model-request-allowlist)).
+
+The read-only rule follows the provider a run was started with
+(`CodingRun.provider`), at pin time and on every call, not the agent's current
+profile. At attach, a coding agent counts as Codex unless its provider is
+exactly `claude-code`, so an agent without a profile is held to the rule too.
+
 The proxy also binds a second listener, the **deny port** (`8788`,
 `CODING_PROXY_DENY_PORT`), which serves nothing: it accepts a connection,
 sends no bytes and closes it immediately
@@ -233,6 +304,22 @@ port-level policy — that is harmless, because the listener accepts the
 connection, sends nothing and closes it. It is not a leak; it is a fact about
 reachability that the Kubernetes launcher turns into evidence.
 
+### Run steps
+
+The worker is not involved: after relaying each model reply unchanged, the proxy
+reads it (and the newest tool results of the request) and makes one short line
+per tool call or model message. It posts the lines to the control plane's
+run-steps listener (`WARDBY_RUN_STEPS_URL`), authenticated by the run capability;
+the control plane removes the agent's secret values before storing them. Reading
+a reply for steps never delays or fails the relay: a frame the proxy can't read
+gives no step, and a full queue or an unreachable server drops steps.
+
+The worker holds the same capability, so the network keeps it off the listener:
+on Kubernetes, ingress to port 8792 only from proxy pods; on Docker, the run's
+isolated network. The worker's own egress is unchanged: it reaches only the
+proxy. See [Run steps](security-deployment.md#run-steps) and
+[Run steps](debugging-agent-runs.md#run-steps).
+
 ## Debug trace
 
 When a fixed code is not enough to tell why a coding agent's runs fail, an