Managing teammate trust policies and blocking senders

Use agentrelay trust to manage per-teammate auto-write permissions in trust.yaml, and agentrelay block to prevent a teammate’s handoffs from reaching your agent.

The trust model has two CLI-facing levers: agentrelay trust for fine-grained per-teammate policies, and agentrelay block / unblock for immediate revocation. Both operate on ~/.agentrelay/trust.yaml, which the MCP server reads on every incoming handoff.

agentrelay trust

The trust command provides typed read/write access to ~/.agentrelay/trust.yaml. You can also edit that file directly with any text editor — the CLI is a convenience layer for scripting and discoverability.

trust list

Lists all entries in your trust file: explicit teammate policies, the unknown-teammate policy, and the current block list.

npx -y -p agentrelay-mcp agentrelay trust list

trust set

Sets or updates the trust policy for a specific handle. All flags are optional — omitted flags leave the existing value unchanged.

npx -y -p agentrelay-mcp agentrelay trust set <handle> \
  --auto-write-paths "docs/,README.md"

Flag	Type	Description
--auto-write-paths	comma-separated string	Glob-prefix paths the agent can write to without prompting you. docs/ matches all files under docs/.
--auto-read	boolean	Allow the agent to perform reads in response to this teammate’s handoffs without prompting
--auto-test	boolean	Allow the agent to run tests in response to this teammate’s handoffs without prompting
--require-approval	comma-separated string	Tool names that always require your explicit approval regardless of other settings

For example, to let Carol’s agent auto-write documentation files but still ask for approval on everything else:

npx -y -p agentrelay-mcp agentrelay trust set carol@acme \
  --auto-write-paths "docs/,README.md" \
  --auto-read true \
  --auto-test true

This produces the following entry in trust.yaml:

teammates:
  carol@acme:
    auto_read: true
    auto_test: true
    auto_write_paths:
      - docs/
      - README.md
    require_approval:
      - Edit
      - Write
      - Bash

trust reset

Removes the explicit entry for a handle, reverting that teammate to the defaults policy.

npx -y -p agentrelay-mcp agentrelay trust reset <handle>

If the handle is not in the trust file, the command exits without error.

Editing trust.yaml directly

The file is designed to be human-readable and hand-editable. The CLI only writes when something actually changes, so you retain your formatting on direct edits. The full schema:

version: 1

teammates:
  bob@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: []
    require_approval: ["Edit", "Write", "Bash"]

  carol@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: ["docs/", "README.md"]
    require_approval: ["Edit", "Write", "Bash"]

unknown_teammates:
  policy: "reject"   # 'reject' | 'allow_with_default_trust'

blocked:             # populated by `agentrelay block`
  - mallory@external

defaults:
  auto_read: true
  auto_test: true
  auto_write_paths: []

auto_write_paths entries are matched as glob prefixes — docs/ matches docs/api.md and docs/setup/quickstart.md. Setting unknown_teammates.policy: reject means any handoff from a handle not listed under teammates: is automatically rejected without prompting you.

---

agentrelay block / unblock

block adds a teammate to the blocked list in your local ~/.agentrelay/trust.yaml. When your MCP server processes an incoming handoff, it reads this file and rejects any handoff from a blocked handle before contacting the relay.

The block takes effect on the next incoming handoff evaluation by your local MCP server. To block a sender at the relay level (so they cannot send even if your MCP server is not running), you can also call POST /agents/me/block directly via the relay REST API. See Admin endpoints for details.

block

npx -y -p agentrelay-mcp agentrelay block <handle>

For example:

npx -y -p agentrelay-mcp agentrelay block mallory@external

This adds mallory@external to the blocked: [...] array in trust.yaml. Your MCP server will reject any incoming handoff from that handle on the next evaluation — before returning any content to your agent.

unblock

npx -y -p agentrelay-mcp agentrelay unblock <handle>

Removes the handle from the local blocked list in trust.yaml. Your MCP server will no longer reject handoffs from that handle on the next evaluation.

Listing blocks

npx -y -p agentrelay-mcp agentrelay block --list

Returns the current block list from your local trust.yaml. The blocked array is also visible in agentrelay trust list.

How blocks survive restarts

The block list lives in ~/.agentrelay/trust.yaml under the top-level blocked: key. The MCP server reads this file on startup and on each handoff evaluation, so blocks survive process restarts without any additional configuration.

Entries in blocked: are a hard override. Even if a handle appears under teammates: with explicit trust, a matching entry in blocked: always wins — the blocked handle is rejected regardless of any other policy.