Agent permission request component

Abstract

agent_permission_request is the permission component already emitted by Relay’s coding-agent integrations. Relay validates the shared component fields, preserves integration-owned top-level fields, and never rewrites the option origins.

Preview

TODO: add the real iOS lane capture from /tmp/relay-component-agent-permission-request.png. This slot intentionally has no fabricated screenshot.

Wire example

{
  "send": {
    "conversation_id": "cnv_01JZC7K4RQ",
    "parts": [{
      "type": "data",
      "data": {
        "kind": "agent_permission_request",
        "request_id": "perm_01JZ8A4M",
        "tool_name": "Bash",
        "options": [
          {
            "id": "allow",
            "label": "Allow",
            "style": "primary",
            "origin": { "kind": "agent_permission", "request_id": "perm_01JZ8A4M" }
          },
          {
            "id": "deny",
            "label": "Deny",
            "origin": { "kind": "agent_permission", "request_id": "perm_01JZ8A4M" }
          }
        ]
      }
    }]
  },
  "stored_part": {
    "part_index": 0,
    "type": "data",
    "data": {
      "kind": "agent_permission_request",
      "request_id": "perm_01JZ8A4M",
      "tool_name": "Bash",
      "options": [
        {
          "id": "allow",
          "label": "Allow",
          "style": "primary",
          "origin": { "kind": "agent_permission", "request_id": "perm_01JZ8A4M" }
        },
        {
          "id": "deny",
          "label": "Deny",
          "origin": { "kind": "agent_permission", "request_id": "perm_01JZ8A4M" }
        }
      ],
      "fallback": "1. Allow\n2. Deny"
    }
  },
  "tap_result": {
    "parts": [{
      "type": "data",
      "data": {
        "origin": { "kind": "agent_permission", "request_id": "perm_01JZ8A4M" },
        "option_id": "allow",
        "label": "Allow"
      }
    }],
    "fallback_text": "Allow"
  }
}

Schema table

Field	Type	Required	Notes
`kind`	`"agent_permission_request"`	Yes	Selects the permission renderer
`request_id`	string	Yes	Non-empty integration request identity
`prompt`	string	No	Up to 1,024 characters
`options`	permission option[]	Yes	Non-empty; every option carries `origin`
`fallback`	string	No	Synthesized when omitted
Other top-level fields	JSON	No	Preserved for relayapp compatibility

Each option uses id, label, optional style, and a required origin object. Permission options cannot combine an origin with a link-out URL.

Examples per state

State	Repository artifact
Send request	`examples/components/agent_permission_request-send.json`
Canonical stored message	`examples/components/agent_permission_request-stored.json`
Tap-result user message	`examples/components/agent_permission_request-tap-result.json`

Constraints

Violation	Result
Missing or empty `request_id`	`422 invalid_request`
Empty option list	`422 invalid_request`
Option without `origin`	`422 invalid_request`
Origin combined with a link-out URL	`422 invalid_request`
Invalid common option ID, label, or style	`422 invalid_request`
Message targets a group conversation	`422 invalid_request`

iOS rendering notes

Render with ComponentConfirm machinery while preserving the integration’s allow and deny labels. On tap, echo the chosen option’s origin object verbatim instead of constructing data_action.

Overview

Get started

Messages

Message components

Conversations

Webhooks & events

Reference

Agent permission request component

Abstract

Preview

Wire example

Schema table

Examples per state

Constraints

iOS rendering notes

See also

​Abstract

​Preview

​Wire example

​Schema table

​Examples per state

​Constraints

​iOS rendering notes

​See also

Abstract

Preview

Wire example

Schema table

Examples per state

Constraints

iOS rendering notes

See also