@quantumclaw/quantumclaw 2026.3.22

package/docs/tools/multi-agent-sandbox-tools.md

@@ -0,0 +1,364 @@
+---
+summary: “Per-agent sandbox + tool restrictions, precedence, and examples”
+title: Multi-Agent Sandbox & Tools
+read_when: “You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.”
+status: active
+---
+
+# Multi-Agent Sandbox & Tools Configuration
+
+Each agent in a multi-agent setup can override the global sandbox and tool
+policy. This page covers per-agent configuration, precedence rules, and
+examples.
+
+- **Sandbox backends and modes**: see [Sandboxing](/gateway/sandboxing).
+- **Debugging blocked tools**: see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) and `quantumclaw sandbox explain`.
+- **Elevated exec**: see [Elevated Mode](/tools/elevated).
+
+Auth is per-agent: each agent reads from its own `agentDir` auth store at
+`~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`.
+Credentials are **not** shared between agents. Never reuse `agentDir` across agents.
+If you want to share creds, copy `auth-profiles.json` into the other agent's `agentDir`.
+
+---
+
+## Configuration Examples
+
+### Example 1: Personal + Restricted Family Agent
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "default": true,
+        "name": "Personal Assistant",
+        "workspace": "~/.quantumclaw/workspace",
+        "sandbox": { "mode": "off" }
+      },
+      {
+        "id": "family",
+        "name": "Family Bot",
+        "workspace": "~/.quantumclaw/workspace-family",
+        "sandbox": {
+          "mode": "all",
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
+        }
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "family",
+      "match": {
+        "provider": "whatsapp",
+        "accountId": "*",
+        "peer": {
+          "kind": "group",
+          "id": "120363424282127706@g.us"
+        }
+      }
+    }
+  ]
+}
+```
+
+**Result:**
+
+- `main` agent: Runs on host, full tool access
+- `family` agent: Runs in Docker (one container per agent), only `read` tool
+
+---
+
+### Example 2: Work Agent with Shared Sandbox
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "personal",
+        "workspace": "~/.quantumclaw/workspace-personal",
+        "sandbox": { "mode": "off" }
+      },
+      {
+        "id": "work",
+        "workspace": "~/.quantumclaw/workspace-work",
+        "sandbox": {
+          "mode": "all",
+          "scope": "shared",
+          "workspaceRoot": "/tmp/work-sandboxes"
+        },
+        "tools": {
+          "allow": ["read", "write", "apply_patch", "exec"],
+          "deny": ["browser", "gateway", "discord"]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### Example 2b: Global coding profile + messaging-only agent
+
+```json
+{
+  "tools": { "profile": "coding" },
+  "agents": {
+    "list": [
+      {
+        "id": "support",
+        "tools": { "profile": "messaging", "allow": ["slack"] }
+      }
+    ]
+  }
+}
+```
+
+**Result:**
+
+- default agents get coding tools
+- `support` agent is messaging-only (+ Slack tool)
+
+---
+
+### Example 3: Different Sandbox Modes per Agent
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "mode": "non-main", // Global default
+        "scope": "session"
+      }
+    },
+    "list": [
+      {
+        "id": "main",
+        "workspace": "~/.quantumclaw/workspace",
+        "sandbox": {
+          "mode": "off" // Override: main never sandboxed
+        }
+      },
+      {
+        "id": "public",
+        "workspace": "~/.quantumclaw/workspace-public",
+        "sandbox": {
+          "mode": "all", // Override: public always sandboxed
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["exec", "write", "edit", "apply_patch"]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Configuration Precedence
+
+When both global (`agents.defaults.*`) and agent-specific (`agents.list[].*`) configs exist:
+
+### Sandbox Config
+
+Agent-specific settings override global:
+
+```
+agents.list[].sandbox.mode > agents.defaults.sandbox.mode
+agents.list[].sandbox.scope > agents.defaults.sandbox.scope
+agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
+agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
+agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
+agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
+agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
+```
+
+**Notes:**
+
+- `agents.list[].sandbox.{docker,browser,prune}.*` overrides `agents.defaults.sandbox.{docker,browser,prune}.*` for that agent (ignored when sandbox scope resolves to `"shared"`).
+
+### Tool Restrictions
+
+The filtering order is:
+
+1. **Tool profile** (`tools.profile` or `agents.list[].tools.profile`)
+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 policies support `group:*` shorthands that expand to multiple tools. See [Tool groups](/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands) for the full list.
+
+Per-agent elevated overrides (`agents.list[].tools.elevated`) can further restrict elevated exec for specific agents. See [Elevated Mode](/tools/elevated) for details.
+
+---
+
+## Migration from Single Agent
+
+**Before (single agent):**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.quantumclaw/workspace",
+      "sandbox": {
+        "mode": "non-main"
+      }
+    }
+  },
+  "tools": {
+    "sandbox": {
+      "tools": {
+        "allow": ["read", "write", "apply_patch", "exec"],
+        "deny": []
+      }
+    }
+  }
+}
+```
+
+**After (multi-agent with different profiles):**
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "default": true,
+        "workspace": "~/.quantumclaw/workspace",
+        "sandbox": { "mode": "off" }
+      }
+    ]
+  }
+}
+```
+
+Legacy `agent.*` configs are migrated by `quantumclaw doctor`; prefer `agents.defaults` + `agents.list` going forward.
+
+---
+
+## Tool Restriction Examples
+
+### Read-only Agent
+
+```json
+{
+  "tools": {
+    "allow": ["read"],
+    "deny": ["exec", "write", "edit", "apply_patch", "process"]
+  }
+}
+```
+
+### Safe Execution Agent (no file modifications)
+
+```json
+{
+  "tools": {
+    "allow": ["read", "exec", "process"],
+    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
+  }
+}
+```
+
+### Communication-only Agent
+
+```json
+{
+  "tools": {
+    "sessions": { "visibility": "tree" },
+    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
+    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
+  }
+}
+```
+
+---
+
+## Common Pitfall: "non-main"
+
+`agents.defaults.sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`),
+not the agent id. Group/channel sessions always get their own keys, so they
+are treated as non-main and will be sandboxed. If you want an agent to never
+sandbox, set `agents.list[].sandbox.mode: "off"`.
+
+---
+
+## Testing
+
+After configuring multi-agent sandbox and tools:
+
+1. **Check agent resolution:**
+
+   ```exec
+   quantumclaw agents list --bindings
+   ```
+
+2. **Verify sandbox containers:**
+
+   ```exec
+   docker ps --filter "name=quantumclaw-sbx-"
+   ```
+
+3. **Test tool restrictions:**
+   - Send a message requiring restricted tools
+   - Verify the agent cannot use denied tools
+
+4. **Monitor logs:**
+
+   ```exec
+   tail -f "${QUANTUMCLAW_STATE_DIR:-$HOME/.quantumclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
+   ```
+
+---
+
+## Troubleshooting
+
+### Agent not sandboxed despite `mode: "all"`
+
+- Check if there's a global `agents.defaults.sandbox.mode` that overrides it
+- Agent-specific config takes precedence, so set `agents.list[].sandbox.mode: "all"`
+
+### Tools still available despite deny list
+
+- Check tool filtering order: global → agent → sandbox → subagent
+- Each level can only further restrict, not grant back
+- Verify with logs: `[tools] filtering tools for agent:${agentId}`
+
+### Container not isolated per agent
+
+- Set `scope: "agent"` in agent-specific sandbox config
+- Default is `"session"` which creates one container per session
+
+---
+
+## See also
+
+- [Sandboxing](/gateway/sandboxing) -- full sandbox reference (modes, scopes, backends, images)
+- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging "why is this blocked?"
+- [Elevated Mode](/tools/elevated)
+- [Multi-Agent Routing](/concepts/multi-agent)
+- [Sandbox Configuration](/gateway/configuration-reference#agents-defaults-sandbox)
+- [Session Management](/concepts/session)

package/docs/tools/pdf.md

@@ -0,0 +1,156 @@
+---
+title: "PDF Tool"
+summary: "Analyze one or more PDF documents with native provider support and extraction fallback"
+read_when:
+  - You want to analyze PDFs from agents
+  - You need exact pdf tool parameters and limits
+  - You are debugging native PDF mode vs extraction fallback
+---
+
+# PDF tool
+
+`pdf` analyzes one or more PDF documents and returns text.
+
+Quick behavior:
+
+- Native provider mode for Anthropic and Google model providers.
+- Extraction fallback mode for other providers (extract text first, then page images when needed).
+- Supports single (`pdf`) or multi (`pdfs`) input, max 10 PDFs per call.
+
+## Availability
+
+The tool is only registered when QuantumClaw can resolve a PDF-capable model config for the agent:
+
+1. `agents.defaults.pdfModel`
+2. fallback to `agents.defaults.imageModel`
+3. fallback to best effort provider defaults based on available auth
+
+If no usable model can be resolved, the `pdf` tool is not exposed.
+
+## Input reference
+
+- `pdf` (`string`): one PDF path or URL
+- `pdfs` (`string[]`): multiple PDF paths or URLs, up to 10 total
+- `prompt` (`string`): analysis prompt, default `Analyze this PDF document.`
+- `pages` (`string`): page filter like `1-5` or `1,3,7-9`
+- `model` (`string`): optional model override (`provider/model`)
+- `maxBytesMb` (`number`): per-PDF size cap in MB
+
+Input notes:
+
+- `pdf` and `pdfs` are merged and deduplicated before loading.
+- If no PDF input is provided, the tool errors.
+- `pages` is parsed as 1-based page numbers, deduped, sorted, and clamped to the configured max pages.
+- `maxBytesMb` defaults to `agents.defaults.pdfMaxBytesMb` or `10`.
+
+## Supported PDF references
+
+- local file path (including `~` expansion)
+- `file://` URL
+- `http://` and `https://` URL
+
+Reference notes:
+
+- Other URI schemes (for example `ftp://`) are rejected with `unsupported_pdf_reference`.
+- In sandbox mode, remote `http(s)` URLs are rejected.
+- With workspace-only file policy enabled, local file paths outside allowed roots are rejected.
+
+## Execution modes
+
+### Native provider mode
+
+Native mode is used for provider `anthropic` and `google`.
+The tool sends raw PDF bytes directly to provider APIs.
+
+Native mode limits:
+
+- `pages` is not supported. If set, the tool returns an error.
+
+### Extraction fallback mode
+
+Fallback mode is used for non-native providers.
+
+Flow:
+
+1. Extract text from selected pages (up to `agents.defaults.pdfMaxPages`, default `20`).
+2. If extracted text length is below `200` chars, render selected pages to PNG images and include them.
+3. Send extracted content plus prompt to the selected model.
+
+Fallback details:
+
+- Page image extraction uses a pixel budget of `4,000,000`.
+- If the target model does not support image input and there is no extractable text, the tool errors.
+- Extraction fallback requires `pdfjs-dist` (and `@napi-rs/canvas` for image rendering).
+
+## Config
+
+```json5
+{
+  agents: {
+    defaults: {
+      pdfModel: {
+        primary: "anthropic/claude-opus-4-6",
+        fallbacks: ["openai/gpt-5-mini"],
+      },
+      pdfMaxBytesMb: 10,
+      pdfMaxPages: 20,
+    },
+  },
+}
+```
+
+See [Configuration Reference](/gateway/configuration-reference) for full field details.
+
+## Output details
+
+The tool returns text in `content[0].text` and structured metadata in `details`.
+
+Common `details` fields:
+
+- `model`: resolved model ref (`provider/model`)
+- `native`: `true` for native provider mode, `false` for fallback
+- `attempts`: fallback attempts that failed before success
+
+Path fields:
+
+- single PDF input: `details.pdf`
+- multiple PDF inputs: `details.pdfs[]` with `pdf` entries
+- sandbox path rewrite metadata (when applicable): `rewrittenFrom`
+
+## Error behavior
+
+- Missing PDF input: throws `pdf required: provide a path or URL to a PDF document`
+- Too many PDFs: returns structured error in `details.error = "too_many_pdfs"`
+- Unsupported reference scheme: returns `details.error = "unsupported_pdf_reference"`
+- Native mode with `pages`: throws clear `pages is not supported with native PDF providers` error
+
+## Examples
+
+Single PDF:
+
+```json
+{
+  "pdf": "/tmp/report.pdf",
+  "prompt": "Summarize this report in 5 bullets"
+}
+```
+
+Multiple PDFs:
+
+```json
+{
+  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
+  "prompt": "Compare risks and timeline changes across both documents"
+}
+```
+
+Page-filtered fallback model:
+
+```json
+{
+  "pdf": "https://example.com/report.pdf",
+  "pages": "1-3,7",
+  "model": "openai/gpt-5-mini",
+  "prompt": "Extract only customer-impacting incidents"
+}
+```

package/docs/tools/perplexity-search.md

@@ -0,0 +1,174 @@
+---
+summary: "Perplexity Search API and Sonar/OpenRouter compatibility for web_search"
+read_when:
+  - You want to use Perplexity Search for web search
+  - You need PERPLEXITY_API_KEY or OPENROUTER_API_KEY setup
+title: "Perplexity Search"
+---
+
+# Perplexity Search API
+
+QuantumClaw supports Perplexity Search API as a `web_search` provider.
+It returns structured results with `title`, `url`, and `snippet` fields.
+
+For compatibility, QuantumClaw also supports legacy Perplexity Sonar/OpenRouter setups.
+If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`, or set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
+
+## Getting a Perplexity API key
+
+1. Create a Perplexity account at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
+2. Generate an API key in the dashboard
+3. Store the key in config or set `PERPLEXITY_API_KEY` in the Gateway environment.
+
+## OpenRouter compatibility
+
+If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`.
+
+Optional compatibility controls:
+
+- `plugins.entries.perplexity.config.webSearch.baseUrl`
+- `plugins.entries.perplexity.config.webSearch.model`
+
+## Config examples
+
+### Native Perplexity Search API
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+### OpenRouter / Sonar compatibility
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "<openrouter-api-key>",
+            baseUrl: "https://openrouter.ai/api/v1",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+## Where to set the key
+
+**Via config:** run `quantumclaw configure --section web`. It stores the key in
+`~/.quantumclaw/quantumclaw.json` under `plugins.entries.perplexity.config.webSearch.apiKey`.
+That field also accepts SecretRef objects.
+
+**Via environment:** set `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
+in the Gateway process environment. For a gateway install, put it in
+`~/.quantumclaw/.env` (or your service environment). See [Env vars](/help/faq#how-does-quantumclaw-load-environment-variables).
+
+If `provider: "perplexity"` is configured and the Perplexity key SecretRef is unresolved with no env fallback, startup/reload fails fast.
+
+## Tool parameters
+
+These parameters apply to the native Perplexity Search API path.
+
+| Parameter             | Description                                          |
+| --------------------- | ---------------------------------------------------- |
+| `query`               | Search query (required)                              |
+| `count`               | Number of results to return (1-10, default: 5)       |
+| `country`             | 2-letter ISO country code (e.g., "US", "DE")         |
+| `language`            | ISO 639-1 language code (e.g., "en", "de", "fr")     |
+| `freshness`           | Time filter: `day` (24h), `week`, `month`, or `year` |
+| `date_after`          | Only results published after this date (YYYY-MM-DD)  |
+| `date_before`         | Only results published before this date (YYYY-MM-DD) |
+| `domain_filter`       | Domain allowlist/denylist array (max 20)             |
+| `max_tokens`          | Total content budget (default: 25000, max: 1000000)  |
+| `max_tokens_per_page` | Per-page token limit (default: 2048)                 |
+
+For the legacy Sonar/OpenRouter compatibility path, only `query` and `freshness` are supported.
+Search API-only filters such as `country`, `language`, `date_after`, `date_before`, `domain_filter`, `max_tokens`, and `max_tokens_per_page` return explicit errors.
+
+**Examples:**
+
+```javascript
+// Country and language-specific search
+await web_search({
+  query: "renewable energy",
+  country: "DE",
+  language: "de",
+});
+
+// Recent results (past week)
+await web_search({
+  query: "AI news",
+  freshness: "week",
+});
+
+// Date range search
+await web_search({
+  query: "AI developments",
+  date_after: "2024-01-01",
+  date_before: "2024-06-30",
+});
+
+// Domain filtering (allowlist)
+await web_search({
+  query: "climate research",
+  domain_filter: ["nature.com", "science.org", ".edu"],
+});
+
+// Domain filtering (denylist - prefix with -)
+await web_search({
+  query: "product reviews",
+  domain_filter: ["-reddit.com", "-pinterest.com"],
+});
+
+// More content extraction
+await web_search({
+  query: "detailed AI research",
+  max_tokens: 50000,
+  max_tokens_per_page: 4096,
+});
+```
+
+### Domain filter rules
+
+- Maximum 20 domains per filter
+- Cannot mix allowlist and denylist in the same request
+- Use `-` prefix for denylist entries (e.g., `["-reddit.com"]`)
+
+## Notes
+
+- Perplexity Search API returns structured web search results (`title`, `url`, `snippet`)
+- OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
+- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`)
+
+See [Web tools](/tools/web) for the full web_search configuration.
+See [Perplexity Search API docs](https://docs.perplexity.ai/docs/search/quickstart) for more details.