action.pending

Description

Returns the set of `pending_approval` decisions for the current bearer, with their approval-ceremony payloads. The pull-mode complement to push notifications: poll this when you need to wake your agent on a fresh approval.

Input schema

Output shape

{
  decisions: Array<{
    decision_id: string;
    action_class: string;
    summary: string;
    counterparty?: { id: string; display_name: string };
    payload: ApprovalCeremonyPayload;
    expires_at: string;
  }>;
}

`ApprovalCeremonyPayload` is the same shape used by Cortex's own approval UIs. See [Action approval](/pitch/docs/concepts#action-approval).

Example call

JSON-RPC tools/call request body (omit the JSON-RPC envelope when using an SDK; the SDK adds it for you):

{
  "name": "action.pending",
  "arguments": { "limit": 10 }
}

Example response

Tool results are always wrapped as content[0].text with a stringified JSON body. The shape below is what you get back from JSON.parse(result.content[0].text):

{
  "decisions": [
    {
      "decision_id": "dec_01HXP9COMM",
      "action_class": "communicate",
      "summary": "Send: \"Quick check — does Tuesday 2pm still work?\" to Sarah",
      "counterparty": { "id": "entity_01HXSARAH", "display_name": "Sarah Chen" },
      "payload": { "what": "...", "why": "...", "reversal_path": "..." },
      "expires_at": "2026-05-28T14:31:00Z"
    }
  ]
}

Errors this tool can return

See the full error catalog for resolution steps on each code, plus the standard transport-layer responses (401, 429).

Notes