@wardby/cli 0.7.0 → 0.8.0

package/docs/getting-started-gke.md

@@ -401,9 +401,10 @@ server answers `415`, because it checks the content type before the token.
 Create the first self-hosted login credential. It is printed once.
 `--role admin` makes this operator account an admin. Only admins can use all
 the privileged operations: `make_owner`, BYO `workerImageRef`, package
-approval, service catalog changes, and model catalog changes. A
-`package-approver` can approve packages only, a `service-manager` can change
-the service catalog only, and a `model-manager` can change the model catalog
+approval, service catalog changes, model catalog changes, and host providers
+(`hosts:admin`). A `package-approver` can approve packages only, a
+`service-manager` can change the service catalog only, a `model-manager` can
+change the model catalog only, and a `host-manager` can manage host providers
 only. Users created without `--role` have no roles. See
 [roles and privileged operations](security-deployment.md#roles-and-privileged-operations).
 
@@ -585,7 +586,7 @@ delete the class and re-run `up.sh` to change them.
 
 ### Native sandbox
 
-Native sandbox requires Wardby 0.5.4 or later.
+Native sandbox requires Wardby 0.6.0 or later.
 
 `up.sh` deploys everything the [native sandbox](native-sandbox.md) needs on
 this cluster. It builds and pushes the `native-worker` image, checks it (Node is

package/docs/getting-started-identity-provider.md

@@ -54,26 +54,27 @@ access tokens for that audience.
 
 Create these scopes in the provider:
 
-| Scope                 | Capability                                                         |
-| --------------------- | ------------------------------------------------------------------ |
-| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.      |
-| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships.  |
-| `runs:trigger`        | Start agent runs.                                                  |
-| `tools:write`         | Create, attach, and manage tools.                                  |
-| `datastore:write`     | Create, attach, query, and modify datastores.                      |
-| `secrets:write`       | Create, attach, rotate, and remove secret bindings.                |
-| `webhooks:write`      | Create and manage webhook triggers.                                |
-| `budget_groups:write` | Create and manage shared budget groups.                            |
-| `packages:approve`    | Approve coding agents' package allowlists.                         |
-| `services:manage`     | Create, update and delete coding-run service catalog entries.      |
-| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.          |
-| `memory:write`        | Set and delete agent memory entries.                               |
-| `admin:view`          | Read every owner's runs through the admin viewer API; admins only. |
-| `models:admin`        | Add, override, disable and reset model catalog entries.            |
-| `power:manage`        | Read low-power state and sleep the proxy/gateway now; admins only. |
+| Scope                 | Capability                                                                      |
+| --------------------- | ------------------------------------------------------------------------------- |
+| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.                   |
+| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships.               |
+| `runs:trigger`        | Start agent runs.                                                               |
+| `tools:write`         | Create, attach, and manage tools.                                               |
+| `datastore:write`     | Create, attach, query, and modify datastores.                                   |
+| `secrets:write`       | Create, attach, rotate, and remove secret bindings.                             |
+| `webhooks:write`      | Create and manage webhook triggers.                                             |
+| `budget_groups:write` | Create and manage shared budget groups.                                         |
+| `packages:approve`    | Approve coding agents' package allowlists.                                      |
+| `services:manage`     | Create, update and delete coding-run service catalog entries.                   |
+| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.                       |
+| `memory:write`        | Set and delete agent memory entries.                                            |
+| `admin:view`          | Read every owner's runs through the admin viewer API; admins only.              |
+| `models:admin`        | Add, override, disable and reset model catalog entries.                         |
+| `power:manage`        | Read low-power state and sleep the proxy/gateway now; admins only.              |
+| `hosts:admin`         | Register host providers and approve their tools; admins and host managers only. |
 
 MCP clients discover this list from Wardby's protected-resource metadata and
-may request every advertised scope. Define all fifteen in the provider even when
+may request every advertised scope. Define all sixteen in the provider even when
 policy grants a particular client or user only a subset. Ensure granted scopes
 are emitted in the access token's `scope` or `scp` claim; defining them only in
 the provider UI is not sufficient.
@@ -97,24 +98,29 @@ every advertised scope fail with `invalid_scope`.
 deployment, define it in the provider too and map it like `agents:admin`;
 otherwise clients that request every advertised scope fail with `invalid_scope`.
 
+`hosts:admin` was added after `power:manage`. When you upgrade an existing
+deployment, define it in the provider too and map it like `agents:admin`;
+otherwise clients that request every advertised scope fail with `invalid_scope`.
+
 ### Wardby roles
 
 A scope only delegates. `agents:admin`, `packages:approve`, `services:manage`,
-`admin:view`, `models:admin` and `power:manage` take effect only for a caller who also holds a Wardby role that grants them:
+`admin:view`, `models:admin`, `power:manage` and `hosts:admin` take effect only for a caller who also holds a Wardby role that grants them:
 
-| Wardby role        | Grants                                                                                                                                                                                                                                                                                                                         |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)), `models:admin` (model catalog) and `power:manage` (`power_status`, `power_sleep`; see [getting-started-gke.md](getting-started-gke.md#low-power-mode)) |
-| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                                                                                                                                     |
-| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                                                                                                                                         |
-| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                                                                                                                                                |
+| Wardby role        | Grants                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)), `models:admin` (model catalog), `hosts:admin` (host providers) and `power:manage` (`power_status`, `power_sleep`; see [getting-started-gke.md](getting-started-gke.md#low-power-mode)) |
+| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                                                                                                                                                                     |
+| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                                                                                                                                                                         |
+| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                                                                                                                                                                                |
+| `host-manager`     | `hosts:admin` (`register_host_provider`, `approve_host_provider_tools`, `test_host_provider`; see [host-providers.md](host-providers.md))                                                                                                                                                                                                                      |
 
 The roles come from a claim in the caller's **access token**, which you map to
 Wardby roles:
 
 ```dotenv
 AUTH_ROLE_CLAIM=groups   # claim name or dotted path
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager
 ```
 
 Wardby looks up `AUTH_ROLE_CLAIM` in two steps:
@@ -162,20 +168,20 @@ their next token.
 
 Provider examples:
 
-- **Okta** (custom authorization server): create four groups, `wardby-admin`,
-  `wardby-packages`, `wardby-services` and `wardby-models`. Add a `groups` claim
+- **Okta** (custom authorization server): create five groups, `wardby-admin`,
+  `wardby-packages`, `wardby-services`, `wardby-models` and `wardby-hosts`. Add a `groups` claim
   to the access token, filtered to those groups. Set `AUTH_ROLE_CLAIM=groups` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager`.
   Optionally, add access policy rules so only those groups can obtain
-  `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage`.
-- **FusionAuth:** create four application roles, `admin`,
-  `package-approver`, `service-manager` and `model-manager`. They appear in the
+  `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin`, `power:manage` and `hosts:admin`.
+- **FusionAuth:** create five application roles, `admin`,
+  `package-approver`, `service-manager`, `model-manager` and `host-manager`. They appear in the
   access token's top-level `roles` claim. Set `AUTH_ROLE_CLAIM=roles` and
-  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager,model-manager=model-manager`.
+  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager,model-manager=model-manager,host-manager=host-manager`.
 - **Keycloak:** create realm roles such as `wardby-admin`, `wardby-packages`,
-  `wardby-services` and `wardby-models`. Realm roles appear under
+  `wardby-services`, `wardby-models` and `wardby-hosts`. Realm roles appear under
   `realm_access.roles`. Set `AUTH_ROLE_CLAIM=realm_access.roles` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager`.
   For client roles, use `resource_access.<client-id>.roles`. The
   [local Keycloak harness](../deploy/keycloak-test/README.md) sets this up.
 - **Auth0:** add the user's roles to the access token as a namespaced custom
@@ -236,7 +242,7 @@ AUTH_JWKS_URI=https://identity.example.com/your-tenant/.well-known/jwks.json
 AUTH_AUDIENCE=https://wardby.example.com/mcp
 # Optional: Wardby roles (see "Wardby roles" above).
 AUTH_ROLE_CLAIM=groups
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager
 ```
 
 Copy `AUTH_ISSUER` exactly from the token's `iss` claim or the provider's
@@ -272,7 +278,7 @@ Confirm that:
 
 - `resource` is the canonical MCP URI;
 - `authorization_servers` contains the external issuer; and
-- `scopes_supported` contains all fifteen Wardby scopes.
+- `scopes_supported` contains all sixteen Wardby scopes.
 
 An unauthenticated MCP request must return `401` with a `WWW-Authenticate`
 challenge pointing back to that metadata document.

package/docs/getting-started.md

@@ -238,6 +238,13 @@ After connecting, try:
 > List my Wardby agents, show the latest run and its actual cost, then create a
 > new agent with a maximum budget of $0.50. Do not run it yet.
 
+From Wardby 0.8.0, Claude Code can also show your runs in a pane beside the
+chat. With `--client claude` or `both`, quickstart offers to install it
+(`--claude-plugin` installs it unattended, `--no-claude-plugin` skips the
+question); otherwise run `npx @wardby/cli@latest claude-plugin install`, then
+`/wardby-runs`. `wardby doctor` reports whether it is set up. See the
+[Claude Code plugin](claude-code-plugin.md) guide.
+
 ### Reasoning effort
 
 A native agent can set `effort` (`low`, `medium`, `high`, `xhigh`, or `max`)
@@ -464,6 +471,7 @@ help article.
 ## Next steps
 
 - [Agent recipes](agent-recipes.md)
+- [Claude Code plugin](claude-code-plugin.md): your runs beside the chat (0.8.0+)
 - [Runtime architecture](architecture-runtime.md)
 - [Coding-agent setup](coding-agent-setup.md) and its
   [local repositories](coding-agent-setup.md#local-repositories) section

package/docs/host-providers.md

@@ -0,0 +1,294 @@
+# Host providers
+
+A host provider adds a code host to Wardby using your own custom tools. You can add
+a host, or fix one, without a Wardby release.
+
+Host providers are being added in stages. **This release (0.8.0) lets you register a
+provider, approve its tools and test them. Agents can't use a registered provider yet**,
+and `link_repository` still refuses its repositories.
+
+## Who can manage one
+
+Every host provider tool (`register_host_provider`, `approve_host_provider_tools`,
+`get_host_provider`, `test_host_provider`, `delete_host_provider`) needs the
+`hosts:admin` scope and a role that grants it (`admin` or `host-manager`), or the local
+stdio operator. Bound tools decide who has permission and who wrote a comment, so treat
+this like `agents:admin`. See
+[getting-started-identity-provider.md](getting-started-identity-provider.md#wardby-roles)
+for defining the scope and mapping the role.
+
+Providers are shared by every host manager: any host manager can read and re-register any
+provider, including its tool code, whoever owns the tools it names.
+
+## Register a provider
+
+1. Create a tool for each operation with `create_tool`. Each does one host call. See
+   [Tool contract](#tool-contract).
+2. Store each credential with `create_secret`, and broker it with `set_secret_broker`
+   ([tool-secrets.md](tool-secrets.md)). Allow every API host and place it in a header or
+   query parameter. Repository credentials also allow the git host; the permission
+   credential needs only the API hosts.
+3. Store a webhook secret of at least 16 characters. Don't attach it to any agent.
+4. Call `register_host_provider`:
+
+   ```json
+   {
+     "provider": "your-host",
+     "gitHost": "git.example.com",
+     "apiHosts": ["api.example.com"],
+     "gitUsername": "x-token-auth",
+     "pullRequestUrlTemplate": "https://git.example.com/{repository}/pull/{number}",
+     "repositoryApiPath": "/2.0/repositories/{repository}",
+     "webhook": {
+       "header": "X-Hub-Signature",
+       "algorithm": "sha256",
+       "deliveryHeader": "X-Request-UUID",
+       "eventHeader": "X-Event-Key",
+       "secret": "your-webhook-secret"
+     },
+     "credentials": [{ "repositories": "your-workspace/*", "secret": "your-token" }],
+     "trustedAccounts": ["<account id>"],
+     "tools": { "getPullRequest": "your_get_pr_tool" }
+   }
+   ```
+
+   Bind every required operation in `tools` (names here are placeholders), and any optional
+   ones you want. For example:
+
+   ```json
+   "tools": {
+     "getPullRequest": "your_get_pr", "listPullRequestFiles": "your_list_files",
+     "getDiff": "your_get_diff", "readFile": "your_read_file", "listFiles": "your_list_dir",
+     "listComments": "your_list_comments", "createComment": "your_create_comment",
+     "submitVerdict": "your_submit_verdict", "findPullRequest": "your_find_pr",
+     "openPullRequest": "your_open_pr", "updatePullRequest": "your_update_pr"
+   }
+   ```
+
+5. No restart is needed in this release, because agents can't use a provider yet. Once they
+   can, a new provider will need a server restart; approvals won't.
+
+The tools and secrets you name must be yours. Secret rules, each refused with a named code:
+
+- Credentials and `permissionCredential` must be brokered, placed in a header or query
+  parameter, and allowed on the API hosts (credentials also on the git host; the permission credential needs only the API hosts).
+- `permissionCredential` can't also be listed in `credentials`
+  (`host_provider_permission_secret_shared`), so no other operation can reach it.
+- The webhook secret can't be a credential or permission secret of any provider, and can't
+  be attached to an agent (`host_provider_webhook_secret_shared`). `attach_secret` refuses
+  it too.
+- The webhook secret needs at least 16 characters (`host_provider_webhook_secret_short`).
+- A permission secret can't be a credential or permission secret of any other provider, and a
+  credential can't be another provider's permission secret
+  (`host_provider_permission_secret_shared`).
+- `gitUsername` can't be a credential's value and can't contain "username".
+- `pullRequestUrlTemplate` is an https URL on `gitHost`, with no username, password or port.
+
+Keep provider credentials unattached. A brokered credential attached to one of its owner's agents
+can be used by that agent's tools without the host provider path guard, which only applies to a
+provider's bound tools.
+
+See [the refusal codes](../help/errors/host-provider-error.md) for what each one means.
+
+These provider names can't be used: `github`, `local`, `http`, `https`, `ssh`, `git`,
+`file` and `constructor`. Names match `^[a-z][a-z0-9-]{1,30}$`.
+
+These operations are required: `getPullRequest`, `listPullRequestFiles`, `getDiff`,
+`readFile`, `listFiles`, `listComments`, `createComment`, `submitVerdict`,
+`findPullRequest`, `openPullRequest` and `updatePullRequest`. These are optional:
+`editComment`, `resolveThread`, `listCommitStatuses`, `setCommitStatus`,
+`getRepositoryPermission` and `normalizeEvent`. `getRepositoryPermission` becomes required
+when you set `permissionCredential`.
+
+## Who may start a run
+
+This is how it will work once agents can use a provider. Registering records your choice
+now; nothing enforces it in this release.
+
+| Setup                     | Situation                                | Result                            |
+| ------------------------- | ---------------------------------------- | --------------------------------- |
+| `permissionCredential`    | The host says the user has enough access | Run starts                        |
+| `permissionCredential`    | The host says they don't                 | Refused, even if in the allowlist |
+| `permissionCredential`    | The lookup fails                         | Refused, with no fallback         |
+| No `permissionCredential` | The user is in `trustedAccounts`         | Run starts, at `write` level      |
+| No `permissionCredential` | The user isn't in `trustedAccounts`      | Refused                           |
+
+`permissionCredential` needs `permissionApiPath` (with `{workspace}` and `{repo}`) and a
+bound `getRepositoryPermission`.
+
+## Change a tool
+
+Registering copies each tool's code, schema and `timeoutMs` (its time limit), and only that
+copy ever runs.
+`update_tool` changes nothing until you approve it, so the last approved version keeps
+working in the meantime.
+
+1. Call `update_tool`.
+2. Call `get_host_provider` with `includeCode: true`. Changed tools show `status: "changed"`.
+   Each operation has `approvedCode` and `approvedParamsZod`, and a changed one also has
+   `currentCode` and `currentParamsZod`, because a change can be to the schema alone. Every
+   operation also shows `approvedTimeoutMs` and `currentTimeoutMs` (`null` is the default
+   10 seconds), since a change can be to the time limit alone.
+3. Read the change, then call `approve_host_provider_tools` with the operation names. It
+   applies from the next call.
+
+Deleting a tool keeps its snapshot running, with `status: "tool_deleted"`. To change that
+operation, bind a new tool by registering again. Registering again also approves every tool
+at its current code.
+
+## Rotate a secret
+
+A secret a provider uses is replaced with `create_secret` under the same name, whether it's a
+credential, the permission credential or the webhook secret. Change its broker config with
+`set_secret_broker`. Both need `hosts:admin` with a role that grants it, as well as
+`secrets:write`, and refuse before handing out a browser link. Without brokering a credential
+stops working, so `set_secret_broker` with `broker: null` also breaks the provider.
+
+Only the secret's owner can rotate it this way, because secret names belong to their owner. If
+another host manager calls `create_secret` with the same name, they get a separate secret and the
+provider keeps the old value. They must register the provider again with their own secret instead.
+
+The new webhook value needs at least 16 characters, whether you pass it directly or enter it
+in the browser (`host_provider_webhook_secret_short`). A browser link requested before the secret
+joined a provider is refused (`host_provider_secret_link_stale`); request a new one.
+
+Rotating needs no re-registration: the next call uses the new value. Update the webhook secret on
+the host at the same time.
+
+## Test a provider
+
+`test_host_provider` runs each approved read-only tool against one repository, using the
+real credential:
+
+```json
+{
+  "provider": "your-host",
+  "repository": "your-host:your-workspace/your-repo",
+  "pullRequest": 4,
+  "headRef": "a-branch-with-a-pull-request",
+  "ref": "a-commit-or-branch",
+  "accountId": "<account id>"
+}
+```
+
+Only `provider` and `repository` are required. Each other field enables the checks that need it:
+
+| Field         | Checks it enables                                                                   |
+| ------------- | ----------------------------------------------------------------------------------- |
+| `pullRequest` | `getPullRequest`, `listPullRequestFiles`, `getDiff`, `listComments`                 |
+| `headRef`     | `findPullRequest`                                                                   |
+| `ref`         | `readFile`, `listFiles`, `listCommitStatuses` (defaults to the pull request's head) |
+| `accountId`   | `getRepositoryPermission`                                                           |
+
+Each result is an `outcome` of `pass`, `fail` (with a fixed code, below) or `skipped`. A skip has
+one of these codes: `not_bound` (no tool bound), `needs_pull_request`, `needs_head_ref`,
+`needs_ref`, `needs_account` (the field above is missing), `allowlist_mode` (no
+`permissionCredential`, so no permission lookup) and `not_read_only` (a write operation, never run).
+
+Write operations are skipped. A read-only tool can only send GET requests. The report holds
+an operation, an outcome and a fixed code for each, and no response data, so you can share it.
+
+| Code                                    | Meaning                                                          |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| `host_unauthorized`, `host_forbidden`   | The host refused the credential for this call.                   |
+| `host_not_found`                        | The host doesn't have what was asked for.                        |
+| `host_rate_limited`, `host_unavailable` | Try again later.                                                 |
+| `host_conflict`                         | The host refused because of the current state.                   |
+| `host_tool_invalid_result`              | The tool's answer doesn't match its operation's shape.           |
+| `host_tool_invalid_params`              | The tool's schema refused what Wardby sends it.                  |
+| `host_tool_request_denied`              | The tool went outside what a bound tool may request (see below). |
+| `host_tool_no_credential`               | See below.                                                       |
+| `host_tool_failed`                      | The tool threw an error. Its message is dropped on purpose.      |
+| `host_tool_timeout`                     | The tool ran out of time or instructions.                        |
+
+`host_tool_no_credential` has these causes: no credential's `repositories` covers this repository,
+the secret can't be decrypted, or the secret is no longer brokered or no longer allows every API
+host.
+
+## Tool contract
+
+Each tool receives `workspace`, `repo` and `repository` (`workspace/repo`), plus its
+operation's input fields (below). Declare them in `paramsZod`.
+
+A tool answers with its operation's result, or `{ "error": "<code>" }` when the host refused,
+where the code is `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited` or
+`unavailable`. Results are checked strictly: an extra key, a missing key or a wrong type fails the
+call with `host_tool_invalid_result`.
+
+A pull request object, as returned by `getPullRequest` and `findPullRequest`, has exactly:
+`number` (positive integer), `title`, `body`, `author` (string or null), `state` (`open` or
+`closed`; a merged pull request is `closed` with `merged` true, so map your host's own states),
+`merged` (boolean), `draft` (boolean), `baseRef`, `headRef`, `headSha` (non-empty), `isFork` (boolean) and
+`htmlUrl` (a URL).
+
+Read operations (method GET):
+
+| Operation                 | Input fields          | Result                                                                                                                                                                                                                                  |
+| ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getPullRequest`          | `number`              | A pull request object.                                                                                                                                                                                                                  |
+| `findPullRequest`         | `headRef`             | `{ pullRequest }`: a pull request object, or null if none.                                                                                                                                                                              |
+| `listPullRequestFiles`    | `number`, `page`      | `{ files, nextPage }`. Each file: `filename`, `status` (`added`, `modified`, `removed` or `renamed`), `additions`, `deletions` (non-negative integers) and optionally `previousFilename`.                                               |
+| `getDiff`                 | `number`              | `{ diff }`: the unified diff text.                                                                                                                                                                                                      |
+| `readFile`                | `ref`, `path`         | `{ kind: "file", content }`, `{ kind: "directory" }` or `{ kind: "not_found" }`. No other keys.                                                                                                                                         |
+| `listFiles`               | `ref`, `path`, `page` | `{ entries, nextPage }`. Each entry: `path`, `type` (`file` or `directory`) and optionally `size` (non-negative integer).                                                                                                               |
+| `listComments`            | `number`, `page`      | `{ comments, nextPage }`. Each comment: `id` (non-empty), `author` and `authorId` (string or null), `body`, `createdAt`, `path` (string or null), `line` (positive integer or null), `parentId` (string or null), `resolved` (boolean). |
+| `listCommitStatuses`      | `ref`, `page`         | `{ statuses, nextPage }`. Each status: `key`, `state` (`pending`, `success`, `failure` or `stopped`) and `url` (string or null).                                                                                                        |
+| `getRepositoryPermission` | `accountId`           | `{ permission }`: `none`, `read`, `triage`, `write`, `maintain` or `admin`. Uses the permission credential and `permissionApiPath`.                                                                                                     |
+
+`listPullRequestFiles`, `listFiles`, `listComments` and `listCommitStatuses` page. Each returns
+one page per call, with `nextPage`: a string to continue from, or null at the end. To get the next
+page, Wardby passes that string back as the optional `page` input, and it leaves `page` out for the
+first page. Declare `page` in `paramsZod`, because `z.object` drops keys it doesn't name, and a tool
+without it would return the first page every time. `test_host_provider` reads the first page only.
+
+`ref` is optional on `readFile` and `listFiles`, where leaving it out means the default branch, so
+declare it as optional there. `listCommitStatuses` always needs one, because statuses belong to a
+commit.
+
+Keep a file's `status` to those four words: Wardby treats a `removed` file as having nothing to read
+at the head.
+
+Write operations:
+
+| Operation           | Method | Result                       |
+| ------------------- | ------ | ---------------------------- |
+| `openPullRequest`   | POST   | A pull request object.       |
+| `updatePullRequest` | PUT    | A pull request object.       |
+| `createComment`     | POST   | `{ id }` (non-empty string). |
+| `editComment`       | PUT    | `{ id }` (non-empty string). |
+| `resolveThread`     | POST   | `{}`                         |
+| `submitVerdict`     | POST   | `{}`                         |
+| `setCommitStatus`   | POST   | `{}`                         |
+
+The input fields of the write operations are defined when agents can use a provider, in a later
+release, so tools for them may need changing then. `test_host_provider` never runs them.
+
+`normalizeEvent` makes no requests and isn't called yet.
+
+Use `fetch(url, { secrets: ["host"] })`. Wardby resolves `host` to the credential for this
+call's repository. A bound tool:
+
+- reaches only `apiHosts`, over https on the default port, with no embedded credentials;
+- stays under `repositoryApiPath` for this repository. `getRepositoryPermission` stays under
+  `permissionApiPath` instead, and is the only operation that gets `permissionCredential`;
+- uses its operation's method: GET for reads, and POST or PUT for writes;
+- may set only the headers `accept`, `content-type`, `if-match` and `if-none-match`;
+- makes at most three requests per call. No request follows a redirect, whether or not it
+  carries a secret: follow a `Location` yourself, which counts as a request and goes through
+  the same limits;
+- can't send the query keys `_method` or any starting `x-http-method`, in any case, which some
+  frameworks read as the request's method;
+- has its path judged by what a server could turn it into: dot-only segments after decoding
+  and encoded separators are refused. A few unusual file names can therefore be refused, and a
+  repository path must be sent literally, not percent-encoded;
+- has no datastore, shared datastore or readable secrets, and its `console` output is dropped;
+- runs under the usual sandbox limits: 10 s per call, 8 s per fetch, 8 MiB per response.
+
+Anything outside these limits fails the call with `host_tool_request_denied`, even if the
+tool catches the error.
+
+## Remove a provider
+
+`delete_host_provider` removes a provider and its snapshots. It's refused while an agent links
+to one of its repositories. `delete_secret` is refused while a provider uses that secret, and
+names the provider.