Permissions

ACP permissions let a running thread pause when an agent needs approval for a sensitive runtime action. A good permissions flow makes the requested tool, input, and reason visible, lets the user approve or deny one concrete request, and then resumes the thread without losing execution context.

Handle runtime permission requests without hiding risky actions or blocking thread UX.

Understand the permission model

Runtime permission requests are thread-scoped. When a tool action requires more access than the current mode allows, the thread can enter permission_asked state and expose a pending request with a request ID, tool name, input, current mode, required mode, reason, and timestamp.

Treat permission_asked as a paused execution state, not a terminal failure.

Render the exact toolName and input so the user can make an informed decision.

Use requestId as the decision handle; do not approve by tool name alone.

Keep permission requests attached to the thread that produced them.

Surface pending requests clearly

Permission UX should be visible wherever the user monitors work: the current thread, the thread list, and notification-style surfaces. The application should query pending requests for the relevant thread and only show cards for requests that still need a decision.

Show a permission card only while a request is pending.

Keep approve and deny actions close to the request details.

Remove the card immediately after a successful decision response.

Avoid generic progress logs as permission context; permission cards need the actual requested action.

Render pending requests in JavaScript

Approve or deny one request at a time

A permission decision should target exactly one pending request. Approval lets the paused action continue. Denial tells the agent to continue with a safer plan when possible, especially when you include a concise reason.

Approve when the exact requested command, file operation, or network access is acceptable.

Deny when the request is too broad, surprising, destructive, or outside the user’s intent.

Include a reason on denial so the agent can adapt instead of repeating the same request.

Treat stale or already-decided requests as resolved UI state.

Approve or deny with the Python SDK

Decide a request over HTTP

Design for safe defaults

Permission systems are most useful when they stay narrow. The goal is not to make users approve every harmless action; it is to interrupt only when a runtime action meaningfully expands access, risk, or blast radius.

Prefer scoped approvals over broad mode changes.

Keep destructive commands, credential access, external network actions, and deployment steps reviewable.

Log permission decisions as part of the thread execution record.

Make denial a productive path by letting the agent continue with an alternate plan.