Verbs

agentproto permissions

agentproto permissions ls        [--json] [--session <id>]
agentproto permissions approve   <id> [--always] [--option-id <id>] [--feedback <text>] [--json]
agentproto permissions deny      <id> [--option-id <id>] [--feedback <text>] [--json]
agentproto permissions answer    <id> [--select <field>=<value>]...
                                 [--text <field>=<text>]... [--answers <json|@file>] [--json]
agentproto permissions watch     [--allow-tool <pat>]... [--deny-tool <pat>]...
                                 [--session <id>] [--rules-json <json|@file>]
                                 [--always] [--interval <dur>] [--timeout <dur>]
                                 [--once] [--dry-run] [--json]

The human side of the cross-session permission inbox. A session started in permission-hold mode parks each tool-permission request the agent raises (Write, Bash, …) instead of auto-answering it; this verb lists every parked request across all sessions and approves, denies, or answers one, unblocking the agent.

Requires a running daemon (serve.md or daemon.md).

Starting a session that holds

Permission-hold is opt-in at spawn time — the default is unchanged (requests are auto-answered so the turn never blocks):

# CLI (daemon-backed)
agentproto sessions start claude-code --workspace my-app --hold-permissions

# MCP
agent_start { "adapter": "claude-code", "permissionHold": true }

# HTTP
POST /sessions/agent   { "adapter": "claude-code", "permissionHold": true }

Held sessions render with a ! badge in agentproto sessions --watch. ACP adapters only (e.g. claude-code); adapters with no permission surface ignore the flag.

Discovery

Discovers the daemon via <workspace>/.agentproto/runtime.json (same as sessions.md). The token there is sent as Bearer on the mutating approve/deny/answer routes; ls is read-only. Override with AGENTPROTO_DAEMON_URL / AGENTPROTO_DAEMON_TOKEN.

Subverbs

ls

agentproto permissions ls
agentproto permissions ls --json
agentproto permissions ls --session ses_abc123

GETs /permissions. Lists everything currently held, oldest first:

ID          SESSION         TOOL                AGE    QUESTION
perm_1      ses_abc123      Write               12s    Allow "Write"?
perm_2      ses_def456      Bash                3s     Allow "Bash"?

--json emits the full records (id, sessionId, toolCallId, toolName, text, options, requestedAt, plus the AIP-45 typed fields request (tool-permission | question | plan-approval), question and planApproval when present, the owning session's adapter/title and age). The tool's raw input (e.g. the Bash command string) is included as rawInput and rendered as a truncated preview in the text table. --session <id> filters to one session.

When the row is a multi-field harness question (request: "question"), each field is listed under the row — its id, input kind (radio/checkbox/text, plus +text when free text is allowed, and required), header and prompt, then every choice value (and label). That listing is exactly what answer takes.

approve <id>

agentproto permissions approve perm_1              # allow-once
agentproto permissions approve perm_1 --always     # allow-always, if offered
agentproto permissions approve perm_1 --option-id allow_edits

POSTs /permissions/:id with { decision: "approve" }. Selects an allow-flavored option — allow-once by default, or allow-always when the request offers one and --always is passed. --option-id picks an exact offered option, overriding the decision→option mapping. --feedback <text> attaches free-text context to the resolution; adapters that support it (e.g. mastra-agent suspensions) fold it into the tool's resume data. The agent's turn resumes with the granted tool call.

deny <id>

agentproto permissions deny perm_2

POSTs /permissions/:id with { decision: "deny" }. Selects a reject-flavored option, or cancels the request outright when none is offered. --feedback <text> attaches free-text context (e.g. "reject, but do X instead") for adapters that support it. The tool call fails cleanly and the agent keeps reasoning.

answer <id>

agentproto permissions answer perm_3 --select color=blue --select size=large
agentproto permissions answer perm_3 --text comment="ship it"
agentproto permissions answer perm_3 --answers @answers.json

Submits the answers to a parked harness question — the AIP-45 multi-field form a permission-hold session raises (single or multiple choice, free-text "Other", several questions at once). POSTs /permissions/:id with { answers }; the agent's turn resumes with the elicitation content.

--select <field>=<value> picks a choice value — repeat it for the several values of a multi-choice field. --text <field>=<text> sets a field's typed answer (the "Other" box of a choice field, or a text/number field). --answers <json|@file> takes the whole { "<field>": { "selected": [...], "text": "...", "value": ... } } object instead and is mutually exclusive with --select/--text. Fields left out are skipped — but a bare submit (no answers at all: the submit option, or an approve that would pick it) on a fields question is refused with invalid_answers and the question stays parked; use deny (or option skip) to skip it. ls lists each field's id and choices (see above); --json prints the daemon's response. A question is skipped by deny, not answered.

watch

agentproto permissions watch --allow-tool "Write"
agentproto permissions watch --deny-tool "Bash" --allow-tool "*"
agentproto permissions watch --rules-json @rules.json --once --dry-run

Polls the permission inbox and auto-resolves requests that match explicit rules; anything that doesn't match stays parked for permissions ls / manual approve/deny. There is no implicit "resolve everything" — you must supply at least one rule.

Two rule forms:

FormFlagsNotes
Flag rules--allow-tool <pat>, --deny-tool <pat>, optional --session <id>, optional --always--deny-tool rules are evaluated before --allow-tool rules. Patterns are exact tool names or *-globs (e.g. mcp__*).
JSON rules--rules-json <json|@file>Full rule array; mutually exclusive with the flag rules.

A --rules-json rule looks like:

[
  { "match": { "toolName": "ExitPlanMode", "sessionId": "s-abc" },
    "decision": "approve", "scope": "always" }
]

match needs at least one of toolName or sessionId; sessionId matches the entry's session id or label. decision is "approve" or "deny". optionId and scope ( "once" or "always", approve-only) are forwarded to the daemon verbatim.

FlagDefaultDescription
--allow-tool <pat>—Approve matching tools. Repeatable.
--deny-tool <pat>—Deny matching tools. Repeatable. Evaluated before allows.
--session <id>—Scope all flag rules to one session (id or label).
--rules-json <json|@file>—Full rule array; cannot be combined with flag rules.
--alwaysfalseWith flag rules: prefer the agent's allow-always option when offered.
--interval <dur>2sPoll interval. Accepts 500ms, 30s, 5m, 2h; bare integer = ms.
--timeout <dur>1hGive up after this long. Same duration format.
--oncefalseRun a single poll pass and exit.
--dry-runfalsePrint what would be resolved without actually resolving.
--jsonfalseEmit one compact JSON object per line (NDJSON).

Errors

  • Unknown or already-resolved id → exit 1 with HTTP 404.
  • An approve on a request that offers no allow-flavored option (and no --option-id) → HTTP 409 — pass an explicit --option-id from ls --json.
  • An answer combining --answers with --select/--text → exit 2 (mutually exclusive); a missing <id> or a malformed --select/--text value also exits 2.

Equivalent surfaces

The inbox is one shared registry behind three transports:

ListRespond
CLIpermissions lspermissions approve|deny|answer
MCPpermissions_listpermissions_respond
HTTPGET /permissionsPOST /permissions/:id

GET /permissions/grants is not part of the inbox: it reports the effective AIP-38 grants derived from the messaging switches (defaults.messaging) and each session's allowPromptFrom, plus the configured entries no grant expresses. Its delegation field reports the AIP-46 delegation gate's current mode (off, observe or enforce, from defaults.spawn.delegationGate) and its in-memory counters: every verdict, the would_deny caller/child pairs most frequent first, and the unbound/undeclared callers. Its profileUse field reports the AIP-46 auth-profile gate the same way (defaults.spawn.profileGate, the verdict counts, and the would_deny caller-profile/requested-profile pairs). Its stdioMounts field reports the stdio mount gate (defaults.spawn.stdioMountGate, the verdict counts, and the would_deny command basenames most frequent first). It is read-only; the counters reset when the daemon restarts.

The read-only permissions_explain tool takes an optional profile (a profile ref). It then builds an auth.profile.use decision for that ref, with the caller's set computed exactly as the spawn gate does: its own recorded profile plus defaults.spawn.sharedProfiles.

The bus also emits session:permission-request / session:permission-resolved events, visible through session_events_poll / session_monitor and per-session webhooks.

See also

  • sessions.md — --hold-permissions and the ! badge
  • Roles — the spawn-time delegation gate, a different (spawn-time) permission boundary than this (per-tool) one