Tool access and vault

Tool access belongs to the seat, not to a person or a chat session. A tool should be available only when the seat's Charter explains why the tool is needed and what the seat may do with it.

Safe access model

• Store credentials as vault references.
• Never place raw secrets in prompts, docs, tool arguments, or logs.
• Bind tools to a seat and Charter.
• Sign the permission manifest before agent go-live.
• Let the server guard every tool call.
• Revoke tokens and credentials when a seat is decommissioned.

Approval boundaries

Connecting a tool is a human-controlled step. The agent can recommend a tool, explain why it is useful, and draft the manifest. A human approves the tool connection and any credentials.

Generic REST connector

For an API with no dedicated connector, the generic REST tool lets a seat read an HTTPS endpoint with a credential you paste through the vault — no ROST-owned app. The agent-facing tool is GET-only. It is escalate-by-default: the agent may only call a host and explicit path prefix a steward has signed onto the allowlist; any other host or path is refused and escalated, with no request made. Mutating methods and request bodies fail before credential binding. A path prefix of / means the steward intentionally approved every path. The connector sets the Authorization header from the vaulted credential itself — the agent never sees the token, and the secret is redacted from the response before it reaches the agent, the audit row, or the logs. The token is only ever sent over HTTPS, only to the signed host and scoped path, and a redirect is never followed — so an allowlisted endpoint cannot bounce the call (and the token) to another host. Signal-source pulls also resolve the host at execution time, reject private or reserved addresses, and pin the outbound socket to the validated address so DNS rebinding cannot move the request after approval. A sandbox dry run of a REST tool makes no real request.

Slack post connector

slack.post_message reuses the connected Slack workspace credential and the seat's Slack channel binding. A live call posts only to that bound channel, through the server-side guard and vault-bound bot token. If the bound channel is marked sensitive, the handler escalates for human approval instead of posting. A sandbox dry run makes no Slack request and does not open the vault.

Gmail connector

The native Gmail handlers run inside the same broker boundary as the REST and Slack connectors: every call passes the server guard and writes an audit row, and the vaulted Google OAuth token is bound only inside a credential closure — the agent never sees it, and both the access and refresh tokens are redacted from anything a handler returns. gmail.read (read scoped inbox) and gmail.draft (compose a draft, never send) are autonomous-eligible when a tenant has a connected Google credential. gmail.send is approval-gated: it never sends autonomously — it holds the action for steward approval. A sandbox dry run previews the intended read/draft/held-send with no Gmail request and without opening the vault. For partner demos before Google verification is complete, use sandbox dry runs, setup previews, and approval-held examples as the demo-safe substitute. Live external Gmail send stays gated on Google verification and domain cutover (DER-880 / DER-881).

Google connector status

Google can be connected from Settings once the workspace OAuth app is configured. The connection flow requests offline access for Gmail read/compose/send and Sheets, stores the returned credential in the vault, and records only account, scope, and capability-availability metadata in the integration row. Partial grants are accepted when at least one connector capability is usable; missing or revoked scopes reduce the affected capability instead of granting more authority. The test action refreshes the vaulted credential and performs a minimal Gmail profile read. Gmail read/draft/send, bounded Sheets read, and approval-held Sheets write handlers run through the guarded broker when Google is connected; connecting Google still does not bypass the signed Charter manifest, tenant policy ceiling, credential vault, or tool-call audit. Sheet grants should use exact signed argument bindings for approved spreadsheet ids and ranges.

Connectors work the same on either lane

A seat's governed connectors are available whether its agent runs on the cloud lane or the runner lane. ROST projects each connector the seat's signed Charter grants onto the seat's own MCP surface and executes it server-side — so a runner-lane agent calls the same Gmail, Sheets, and Slack connectors a cloud-lane agent does, with identical governance: the same server guard, the same held-write approval for send/write tiers, and the same tool-call audit row. The OAuth or vaulted credential is resolved and bound only on the server inside the credential closure and never travels to the runner. Because this projection is derived from the Charter manifest and the connected integration, connecting a new integration makes its capabilities available to an already-live runner seat with no charter re-sign or code change. Connectors without a server-side handler yet stay cloud-only and are shown on the seat's Tools tab as not available on the runner lane until one ships.

A connected Baserow REST integration (integration.connect_rest) derives a baserow.read tenant capability ceiling the same way: a live connection surfaces read, and a disconnected/revoked one collapses to off. The derivation is read-only by design — baserow.write is never inferred from the connection and is granted only through an explicit per-seat brokered secret grant, matching the conservative-by-default rule for every connection-backed ceiling.

CLI and MCP can inspect connector readiness without seeing secrets: integration.list / rost_list_integrations lists connected providers and health metadata, integration.status / rost_get_integration_status reads one provider by id or name, and integration.test / rost_test_integration_connection runs the installed provider-specific health check. For Google, the test refreshes the vaulted OAuth credential and reads the Gmail profile, then records only account, scope, and health metadata.

integration.connect_rest creates or rotates the supported Baserow REST integration through the credential flow. It stores the token in the vault, persists only endpoint/account metadata plus a tenant-scoped integration row, marks the adapter as rest, and returns no vault ref or secret. Because the input includes a raw secret, generated CLI argv refuses the command and it is deliberately not exposed as an agent-callable MCP tool; run it from Settings or the command API credential flow instead of shell arguments.

integration.readiness / rost integration readiness --provider google --json / rost_check_integration_readiness returns the operator setup checklist: app configuration status, tenant connection state, granted scopes, latest test state, the demo-safe partner path, external verification/CASA caveats, handler availability, and the next operator action. The checklist is metadata-only. It never returns access tokens, refresh tokens, client secrets, vault refs, or raw provider responses. Settings deliberately keeps the live Google card narrower: connected account, last successful test, granted capabilities, and connect/reconnect/test actions.

One write-only credential flow across every surface

There is exactly one way to give a connected tool its credential, and it is the same on every surface (agent setup, Charter Builder, CLI, MCP). Connecting a tool only authorizes the access — it never captures a secret. When a connected tool needs a credential, you stage a vault-backed *request* (provider, scope, and a credential name — all labels, never the secret). You then provide the actual secret separately through the vault-backed ingress flow from Settings. No ROST surface ever has a field that accepts raw secret material, so a secret can never reach a prompt, log, event, or tool argument.

What to check before connecting a tool

• The seat has an active or ready-to-approve Charter.
• The Charter names the responsibility that needs the tool.
• The autonomous and approval scopes are clear.
• Must-escalate cases are stated.
• The tool provider and credential name are enough for audit; secret values are not displayed.

Change tool access after go-live

Tool access on a live seat is part of its signed Charter, so changing it is a governed amendment, not an in-place edit. You can make the change from the agent detail page without leaving it: the Tools tab's manage-tools drawer edits the permission manifest directly — grant or revoke a tool, adjust its scope tier, or add an available tool from the catalog. Your edits are staged as one confirmation that lands in Approvals with a plain summary of what changes ("grants work.record (draft) · revokes email.draft"). Approving that confirmation is the re-sign: it creates a new Charter version that supersedes the prior one, and prepares a successor agent pinned to that new version. The running agent does not switch to the new manifest at that moment. It stays on the manifest it rehearsed, and the tool guard keeps enforcing that one, until you rehearse the successor with a dry run and promote it with agent.go_live — the promotion is what moves the seat onto the new manifest, and it retires the agent generation it replaced. Nothing changes until a human approves — selecting a tool never grants access on its own.

The charter builder's amendment mode edits the same manifest for a draft Charter (toggle a tool's grant or scope tier), staged into the draft; the draft stays inert until the existing sign or go-live step. If a seat already has an amendment draft open, finish it in the charter editor rather than staging a separate tool change from the drawer.

Connect tools and credentials from CLI or MCP

• Stage tools on a draft agent: agent.configure_tools / rost_configure_agent_tools — connect or decline proposed tools and stage credential-ingress requests. Pass vault references, never raw secret material.
• Inspect connector readiness: integration.list / rost_list_integrations, integration.status / rost_get_integration_status, and integration.test / rost_test_integration_connection return provider metadata and health only.
• Store a secret: credential.ingress (scope: seat) persists only a vault reference. It is credential_flow — because it carries a real human-provided secret it runs only through the Settings vault-ingress flow (a human session); generated CLI argv refuses it and it is deliberately not an agent-callable MCP tool. (Because it redacts that secret, its confirmation also shows a high-risk badge — see the confirmations guide for badge-versus-level.)
• Sign the manifest: charter.sign_manifest / rost_sign_charter_manifest requests human confirmation for the seat's permission manifest.
• Mint local access: prefer rost mcp install for users; mcp_token.create is human_required and returns the token once. List metadata with mcp_token.list (never token material); revoke with mcp_token.revoke.

When to stop for confirmation

credential.ingress and agent.configure_tools are credential_flow; charter.sign_manifest, mcp_token.create, and mcp_token.revoke are human_required. Connecting a tool, storing a credential, or minting a token is a human-approved act. An agent drafts and explains; a human approves through the confirmation flow. Secrets never appear in prompts, logs, tool arguments, or an args_summary. See the confirmations guide.