## Platform tools — the agent-session tool universe

*Anna App · agent tools*

What can an App agent session actually call? Two distinct regimes, selected at `agent.session.create` time:

**Sandbox (default when `quotaCaps.inherit_host_tools` is false/absent for your grant).** The resolved surface is a pure intersection — `AppToolRegistry.public_set ∩ manifest.ui.host_api.agent.tools (→ user grant) ∩ quotaCaps.allowed_tools [∩ dev_safe on harness PAT sessions]`. Every built-in below is INDIVIDUALLY grantable — e.g. `allowed_tools: ["fs_read_file"]` yields a read-only-filesystem agent that cannot write or exec (forum #192). Host-kit tools (fs / exec / browser) execute on the session's platform-pinned agent client: `fixed` submode targets `fixed_client_id`, `auto` targets the user's default agent — the pinned `client_id` always overrides anything the model supplies, so an App can never aim side effects at an arbitrary machine. Any name outside the registry is **silently dropped** (no error); an empty result means a TEXT-ONLY agent — side-effect claims in its output would be hallucinated (the run emits a `NO_TOOLS_AVAILABLE` warning frame). Use `agent.session.catalog()` to see the registry universe and per-tool `blocked_by` diagnostics BEFORE creating a session. Per-run `allowed_tools` further narrows a sandbox session's surface for that run.

**Inherit (`quotaCaps.inherit_host_tools: true`, requires the user grant).** The session gets the SAME tool kit as the user's main copilot — the platform built-ins plus every Executa the user has installed. This surface is user-specific and dynamic (can be hundreds of tools ≈ 100K prompt tokens — slower + costlier runs); `granted_tools` echoes `["*"]`, and the per-run `run_meta` frame is the authoritative record. Per-run `allowed_tools` does NOT narrow inherit sessions — prefer a sandbox session with an explicit allowlist when you need a policy like read-but-never-write.

The sandbox registry below is drift-checked against `src/services/app_tool_registry.py` in CI — registering a tool without updating this section fails the build.

### Sandbox registry (AppToolRegistry — legal `allowed_tools` values)

- **web_search** — Search the public web (or news) and return concise, provider-agnostic snippets. Same capability as the Host API `anna.web.search` — shared provider routing, `web_grant` gating, result cache and billing (an agent-side call books an `APP_WEB_SEARCH` ledger entry against the session), so the agent surface cannot bypass Host API quota.  `server-side` `web_grant`

- **sheet_read** — Read an Excel workbook (xlsx/xls) attachment as structured, typed data — workbook overview, then paginated rows with `{v, d, t}` cells (dates as ISO 8601) and stable A1 locators like `Sheet1!A2:D18`. Only accepts platform-issued attachment URLs (the `document_url` from the attachment list or an `upload_local_file` result). Truncation is always explicit: follow `truncated.next_call` to continue reading. Books an `APP_DOC_PARSE` floor-CU ledger entry per call.  `server-side` `read-only`

- **doc_read** — Read a DOCX / PPTX / PDF attachment as structured blocks with stable locators (`para:N` / `table:M` / `slide:N` / `page:N`) — use `mode: "outline"` first for large documents, then read content windows. Only accepts platform-issued attachment URLs. Truncation is always explicit via `truncated.next_call`. Books an `APP_DOC_PARSE` floor-CU ledger entry per call.  `server-side` `read-only`

- **fs_read_file** — Read a file on the user's agent machine — text or base64 binary, optional line range.  `NATS RPC` `read-only`

- **fs_write_file** — Write or append content to a file on the user's agent machine. REAL side effects — omit from `allowed_tools` for a read-only agent.  `NATS RPC` `write`

- **fs_list_directory** — List directory contents on the user's agent machine (glob filter, recursive).  `NATS RPC` `read-only`

- **fs_copy_file** — Copy a file or directory on the user's agent machine.  `NATS RPC` `write`

- **fs_move_file** — Move / rename a file or directory on the user's agent machine.  `NATS RPC` `write`

- **fs_delete_file** — Delete a file or directory on the user's agent machine. Destructive.  `NATS RPC` `destructive`

- **fs_search** — Search files by name / glob pattern on the user's agent machine.  `NATS RPC` `read-only`

- **fs_get_info** — Get file metadata (size, mtime, type) on the user's agent machine.  `NATS RPC` `read-only`

- **fs_exists** — Check whether a path exists on the user's agent machine.  `NATS RPC` `read-only`

- **fs_mkdir** — Create a directory on the user's agent machine.  `NATS RPC` `write`

- **exec_run** — Run a single shell command on the user's agent machine (cwd defaults to the client's workspace). REAL side effects.  `NATS RPC` `destructive`

- **exec_run_commands** — Run multiple shell commands sequentially on the user's agent machine. REAL side effects.  `NATS RPC` `destructive`

- **browser_create_instance** — Create a TalentBrowser instance on the user's agent machine — the session entry point for all other browser tools.  `NATS RPC` `browser`

- **browser_navigate** — Navigate the browser to a URL.  `browser`

- **browser_get_html** — Get the current page HTML (core content extraction).  `browser` `read-only`

- **browser_click** — Click a page element.  `browser`

- **browser_fill** — Fill a form element.  `browser`

- **browser_screenshot** — Take a screenshot of the current page.  `browser` `read-only`

- **browser_scroll** — Scroll the page (smart scrolling for lazy-loaded content).  `browser`

- **browser_execute_script** — Execute JavaScript in the page context (advanced operations entry point).  `browser` `destructive`

- **browser_wait_for_element** — Wait for an element to appear (reliable automation).  `browser` `read-only`

- **browser_toolkit** — Router to the 57 extended browser operations (cookies, tabs, iframes, downloads, session persistence, …) without paying their schema-token cost up front.  `browser` `router`

### Inherit host kit — additional tool families (inherit-only, user-specific)

- **fs_* / exec_* / browser_* / web_search** — The same host-kit built-ins as the sandbox registry above — an inherit session always carries ALL of them (per-run `allowed_tools` cannot narrow inherit). `web_search` is the ONLY server-side search surface — the legacy free `ddg_search` / `ddg_news_search` were removed platform-wide (capability fully covered by `web_search`: `topic: "news"`, free DDG provider fallback, unified cache / circuit-breaker / billing).  `also in sandbox`

- **generate_image / edit_image / analyze_image / upload_local_file** — Multimodal built-ins. With a vision-capable model, images attached via `run({attachments})` or uploaded mid-run are presented to the model DIRECTLY — `analyze_image` is the fallback for non-vision models. Bound to the session's model configuration, therefore inherit-only today.  `vision`

- **user_storage_*** — Per-user APS key-value + object storage (get/set/list/delete/save_text/get_url). Wired through user-path middleware, therefore inherit-only today — sandbox sessions use the `storage.*` Host API instead.

- **write_todos / get_todos / spawn_subagent / launch_async_agent …** — Planning + orchestration built-ins (todo tracking, sub-agents, async background agents). Coupled to the host agent's state graph, therefore inherit-only.

- **tool_<owner>_<slug>__<tool> …** — Every Executa the user has installed and enabled, discovered live from their connected clients. Enumerate at runtime via the create response / `run_meta` — not statically documentable.  `dynamic`