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 call an HTTP endpoint with a credential you paste through the vault — no ROST-owned app. It is escalate-by-default: the agent may only call a host, method, and explicit path prefix a steward has signed onto the allowlist; any other host, method, or path is refused and escalated, with no request made. 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. 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.

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 and Sheets, stores the returned credential in the vault, and records only account and scope metadata in the integration row. The test action refreshes the vaulted credential and performs a minimal Gmail profile read. Gmail and Sheets agent tools remain configuration-only until their guarded handlers ship; connecting Google does not by itself let an agent read mail or edit a sheet.

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.readiness / rost integration readiness --provider google --json / rost_check_integration_readiness returns the same setup checklist Settings shows: OAuth env and callback status, tenant connection state, granted scopes, latest test state, external verification/CASA caveats, handler availability, and the next Linear issue or action. The checklist is metadata-only. It never returns access tokens, refresh tokens, client secrets, vault refs, or raw provider responses.

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.

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 / rost_store_credential (scope: seat) persists only a vault reference. credential.ingress is credential_flow — it returns a pending confirmation and runs only with a real human-provided secret, captured as a vault reference. (Because it redacts that secret, the pending 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.