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_abc123GETs /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_editsPOSTs /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_2POSTs /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.jsonSubmits 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-runPolls 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:
| Form | Flags | Notes |
|---|---|---|
| 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.
| Flag | Default | Description |
|---|---|---|
--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. |
--always | false | With flag rules: prefer the agent's allow-always option when offered. |
--interval <dur> | 2s | Poll interval. Accepts 500ms, 30s, 5m, 2h; bare integer = ms. |
--timeout <dur> | 1h | Give up after this long. Same duration format. |
--once | false | Run a single poll pass and exit. |
--dry-run | false | Print what would be resolved without actually resolving. |
--json | false | Emit one compact JSON object per line (NDJSON). |
Errors
- Unknown or already-resolved id → exit
1withHTTP 404. - An
approveon a request that offers no allow-flavored option (and no--option-id) →HTTP 409— pass an explicit--option-idfromls --json. - An
answercombining--answerswith--select/--text→ exit2(mutually exclusive); a missing<id>or a malformed--select/--textvalue also exits2.
Equivalent surfaces
The inbox is one shared registry behind three transports:
| List | Respond | |
|---|---|---|
| CLI | permissions ls | permissions approve|deny|answer |
| MCP | permissions_list | permissions_respond |
| HTTP | GET /permissions | POST /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-permissionsand the!badge- Roles — the spawn-time delegation gate, a different (spawn-time) permission boundary than this (per-tool) one