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 a steward has signed onto the allowlist; any other host is refused and escalated, with no request made. 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 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.

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.
• 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.