From 574b6ab5b191959126c77e0f1d1a824d70a70445 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 13 Jan 2026 09:59:36 +0000 Subject: [PATCH] docs: document provider tool policies --- docs/gateway/configuration.md | 31 +++++++++++ .../sandbox-vs-tool-policy-vs-elevated.md | 3 ++ docs/multi-agent-sandbox-tools.md | 12 +++-- docs/tools/index.md | 53 +++++++++++++++++++ 4 files changed, 95 insertions(+), 4 deletions(-) diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 012bec824..4b412e6b3 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -1614,6 +1614,37 @@ Example (coding profile, but deny exec/process everywhere): } ``` +`tools.byProvider` lets you **further restrict** tools for specific providers (or a single `provider/model`). +Per-agent override: `agents.list[].tools.byProvider`. + +Order: base profile → provider profile → allow/deny policies. +Provider keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` +(e.g. `openai/gpt-5.2`). + +Example (keep global coding profile, but minimal tools for Google Antigravity): +```json5 +{ + tools: { + profile: "coding", + byProvider: { + "google-antigravity": { profile: "minimal" } + } + } +} +``` + +Example (provider/model-specific allowlist): +```json5 +{ + tools: { + allow: ["group:fs", "group:runtime", "sessions_list"], + byProvider: { + "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] } + } + } +} +``` + `tools.allow` / `tools.deny` configure a global tool allow/deny policy (deny wins). This is applied even when the Docker sandbox is **off**. diff --git a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md index 20c44ec49..964a8895f 100644 --- a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md +++ b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md @@ -51,12 +51,15 @@ See [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace moun Two layers matter: - **Tool profile**: `tools.profile` and `agents.list[].tools.profile` (base allowlist) +- **Provider tool profile**: `tools.byProvider[provider].profile` and `agents.list[].tools.byProvider[provider].profile` - **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny` +- **Provider tool policy**: `tools.byProvider[provider].allow/deny` and `agents.list[].tools.byProvider[provider].allow/deny` - **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*` Rules of thumb: - `deny` always wins. - If `allow` is non-empty, everything else is treated as blocked. +Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`). ### Tool groups (shorthands) diff --git a/docs/multi-agent-sandbox-tools.md b/docs/multi-agent-sandbox-tools.md index f469535bf..f714acca5 100644 --- a/docs/multi-agent-sandbox-tools.md +++ b/docs/multi-agent-sandbox-tools.md @@ -188,14 +188,18 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.* ### Tool Restrictions The filtering order is: 1. **Tool profile** (`tools.profile` or `agents.list[].tools.profile`) -2. **Global tool policy** (`tools.allow` / `tools.deny`) -3. **Agent-specific tool policy** (`agents.list[].tools`) -4. **Sandbox tool policy** (`tools.sandbox.tools` or `agents.list[].tools.sandbox.tools`) -5. **Subagent tool policy** (`tools.subagents.tools`, if applicable) +2. **Provider tool profile** (`tools.byProvider[provider].profile` or `agents.list[].tools.byProvider[provider].profile`) +3. **Global tool policy** (`tools.allow` / `tools.deny`) +4. **Provider tool policy** (`tools.byProvider[provider].allow/deny`) +5. **Agent-specific tool policy** (`agents.list[].tools.allow/deny`) +6. **Agent provider policy** (`agents.list[].tools.byProvider[provider].allow/deny`) +7. **Sandbox tool policy** (`tools.sandbox.tools` or `agents.list[].tools.sandbox.tools`) +8. **Subagent tool policy** (`tools.subagents.tools`, if applicable) Each level can further restrict tools, but cannot grant back denied tools from earlier levels. If `agents.list[].tools.sandbox.tools` is set, it replaces `tools.sandbox.tools` for that agent. If `agents.list[].tools.profile` is set, it overrides `tools.profile` for that agent. +Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`). ### Tool groups (shorthands) diff --git a/docs/tools/index.md b/docs/tools/index.md index 87ef3d7f1..2acb9bfc9 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -68,6 +68,59 @@ Example (global coding profile, messaging-only support agent): } ``` +## Provider-specific tool policy + +Use `tools.byProvider` to **further restrict** tools for specific providers +(or a single `provider/model`) without changing your global defaults. +Per-agent override: `agents.list[].tools.byProvider`. + +This is applied **after** the base tool profile and **before** allow/deny lists, +so it can only narrow the tool set. +Provider keys accept either `provider` (e.g. `google-antigravity`) or +`provider/model` (e.g. `openai/gpt-5.2`). + +Example (keep global coding profile, but minimal tools for Google Antigravity): +```json5 +{ + tools: { + profile: "coding", + byProvider: { + "google-antigravity": { profile: "minimal" } + } + } +} +``` + +Example (provider/model-specific allowlist for a flaky endpoint): +```json5 +{ + tools: { + allow: ["group:fs", "group:runtime", "sessions_list"], + byProvider: { + "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] } + } + } +} +``` + +Example (agent-specific override for a single provider): +```json5 +{ + agents: { + list: [ + { + id: "support", + tools: { + byProvider: { + "google-antigravity": { allow: ["message", "sessions_list"] } + } + } + } + ] + } +} +``` + ## Tool groups (shorthands) Tool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools.