Session permission requests

Native queued notification acceptance counts as successful delivery. The host first writes and syncs the session-specific rules, then verifies either the official prompt hook or the CLI's own queued notification. Claude confirmation uses an owned, bounded native transcript enqueue record with exact conversation, timestamp and whole-message digest. Codex confirmation uses its native queue preview containing the unique notification and an emptied input composer. The receipt is bound to the managed process generation, PID and start ticks.

History distinguishes native submission from notification queued by CLI. Queued delivery does not claim that the model has read or executed the message; compaction or the current task may finish first. The controller retires the delivery command once native queue acceptance is verified, preventing repeated Enter presses or duplicate notifications. Merely writing the rules, pasting text, pressing Enter, or observing an empty composer is insufficient. Unverified delivery remains retryable without granting additional permissions.

Provider stops used for account continuation have a separate immediate command lane. An authenticated host channel receives the existing durable, generation- fenced stop command immediately; a two-second lightweight queue poll provides a fallback independent of slow inventory/build reconciliation. Both transports share in-flight command deduplication. A verified stop removes only the exact container/PID/UID/start-time/scope/generation from cached inventory, so an old inventory snapshot cannot block switching accounts or resurrect the old process.

Agents request missing policy permissions through the built-in devctl MCP request_permission tool. The request appears in MCP Approvals in both TUI and web, with the Project, session, resource, actions, purpose and constraints. The existing browser push notification and dashboard approval indicator apply. There is no need to copy an agent's request into another conversation.

Use the existing typed mutation first when it fits: grant_service grants an existing catalog Service, for example. A plain request_permission delivers policy text, such as additional production database SELECT scope or permission to call named API methods. To request actual supported configuration changes, attach the exact typed mcpCommands plan described below. Requests cannot target another session or Project.

Example MCP arguments:

{
  "title": "Download public source attachments",
  "resource": "https://api.example.com:443",
  "actions": ["GET attachments referenced in inputs.ndjson"],
  "purpose": "Read source documents for the Project audit",
  "tags": ["external-service", "audit"],
  "risk": "low",
  "impact": "read",
  "reversibility": "reversible",
  "environment": "production",
  "sensitivity": "public",
  "cost": "none",
  "constraints": [
    "At most 2 requests per second across all workers",
    "Store downloads in /data/audits/example/"
  ]
}

Request SQL scope separately with the database endpoint as resource, the exact SELECT exports as actions, and a read-only transaction as a constraint. Do not include passwords, tokens, connection URLs with credentials, private keys, secret values, shell commands or operator instructions masquerading as configuration. Typed commands belong only in mcpCommands. Known credential assignments, signed/token-bearing URLs and control characters are rejected. This validation does not detect every possible secret: agents must never include secret material in policy text.

The initial response contains a persisted approvalId and requiresApproval. An eligible plain request can already be approved when automatic approval is enabled; typed command plans always require manual review. Delivery must still be confirmed through get_permission_status. The operator opens MCP Approvals, selects a repository under its Project, and presses Enter or clicks it to review the requests. Use arrows, Page Up/Down, Home/End to scroll; the browser also supports the mouse wheel. Every requested action and constraint is selected by default. Space or a click toggles either; a / Approve grants only selected actions and retains only selected constraints, and d / Deny declines the complete request. Select at least one action to approve. After either decision, the view returns to the repository list. Esc returns without deciding. Only an authorized console principal can decide: the recovery operator in local mode, or a server user within the controller-reviewed ownership/API scope. A host/session credential cannot approve itself or decide another user's request. An autonomous Run permit cannot authorize its own new policy request.

MCP Approvals → s / Stop words opens the controller's read-only review catalog in TUI and web. It lists whole words, command phrases, Russian stems, disruptive resource operations, and the independent structured-risk checks. The controller API exposes the same catalog at GET /v1/mcp/approvals/stop-words; the UI does not classify requests itself. Matching is case-insensitive. The response-format parameter format=VALUE does not imply disk formatting; format /dev/... and other destructive actions still require review. Agent-declared high risk and uncertain Decisions results remain manual independently of textual matches. Existing decisions and classifications are retained in history.

Generated DEVCTRL.AGENTS.MD includes the canonical stop words and their meaning when managed runtime documentation is materialized or resynchronized. This helps agents explain review triggers, not authorize themselves or hide destructive effects with different wording. Project-owned Exchange devctrl.md remains a separate source of project instructions.

For a plain request, approval creates a canonical session-bound Agent Document and a durable session.permission.apply host command. The host updates the current private DEVCTL.RULES.md in place as the session UID and notifies the running provider to reread it. It does not stop the session, its background work or its Project. The binding retains the permission on subsequent session configuration materialization. Other sessions do not inherit it.

The delivered permission is itself an operator access document. It supplements older narrowly scoped instructions such as PRODUCTION-ACCESS.md; agents must not demand a duplicate manual edit or chat confirmation for an already approved and delivered action. The immutable launch-time summary can predate the broker's current tools. Inspect the actual native client's exposed list; a separate broker tools/list response does not prove native registration. Use only a supported client refresh. Current Codex TUI can retain its startup allowlist, and live catalog reload is unverified. Use an already authorized session transport where available; otherwise report the missing native tool instead of claiming a pending approval. See native catalog limits.

The agent polls get_permission_status with {"approvalId":"..."}. Approval, writing the rules file, and native notification are separate stages. Wait for status: approved and rulesApplied: true (or legacy delivery: delivered), then reread the rules before proceeding. A typed plan must also have execution.state: succeeded; verify any queued host jobs and actual endpoint state independently. rulesApplied is reported only for the approved, current session identity after the host confirms the policy was written. A pending native notification does not prevent the working agent from reading that file. Do not keep polling the notification from the same turn: its safe input point may require that turn to finish. delivery, submissionVerified and native queue receipts keep their existing meanings; writing a file does not prove that Enter was sent or that the CLI accepted the notification. Failed delivery remains visible in MCP Approvals; r / Retry rules delivery retries without creating another permission.

Once the host has written approved rules and only a busy composer, user draft, or input lock delays the notification, the request leaves the active Approvals list and its menu spinner stops. Open History (h) to see the approved request and its queued-notification state. The server continues delivery without an open UI. Missing host confirmation, an uncertain native receipt, failed delivery, and unfinished or failed configuration commands remain actionable. A later notification failure brings the request back into the active list; archiving it does not fabricate a native submission receipt.

The operator CLI also supports:

./devctl mcp approvals
./devctl mcp approve <approval-id>
./devctl mcp deny <approval-id>
./devctl mcp retry-delivery <approval-id>

These CLI approval examples apply to ordinary requests. Typed command plans require the reviewed planHash; use their detail view in an updated console or the operator API below. Older clients cannot approve an unseen command plan.

Permission requests expire after 24 hours while awaiting an operator. Identical pending requests are deduplicated. Repeated already-decided requests return the existing result; denial grants nothing and must not be retried unchanged. Changing the provider generation, account, workspace placement or agent snapshot makes an old request stale rather than granting it to a replacement session. Approval/delivery are persisted and audited; delivery is idempotent.

Reattaching or recovering a still-running process does not change its generation. Older controller counters can be repaired after two exact host observations of the same container, account UID, PID, start time and execution scope. A newer accepted launch receipt or active replacement blocks this repair. Unchanged pending requests and approved requests failed specifically because of that drift follow the corrected counter; delivered grants and unrelated failures are not silently rebound. This does not transfer permissions across a real replacement.

A plain permission is an operator policy, not a new IAM credential or firewall rule. Approving prose alone does not create secrets, change a gateway's method allowlist, enable an API upstream, or technically enforce an HTTP rate limit/SQL read-only rule. A reviewed typed plan can apply the supported configuration changes below; it cannot run arbitrary gateway code or provision credentials. The agent must respect the approved constraints and independently verify that transport, credentials and upstream authorization are ready. Request actual Service grants with grant_service; credential provisioning remains an operator operation. Same-account sessions in one Project still share a Unix UID, so a session document is not an OS isolation boundary between them.

Permanent repository website access

Use session request_repository_network_access when public website access must remain available to this repository across sessions and container restarts:

{
  "hosts": ["api.example.com", "docs.example.com"],
  "ports": [80, 443],
  "reason": "Read the public API reference for this repository",
  "idempotencyKey": "ce799ee7-caa8-4ee7-8618-108c37e20c37"
}

The tool derives the current owned primary repository and its incarnation from the authenticated managed session. Supply public DNS hosts or explicit leading *. patterns. Ports may be omitted, but the supported scope is always both public HTTP/HTTPS ports 80 and 443. Credentials, URLs, private/metadata hosts, arbitrary ports, another Project and the all-destinations wildcard are outside this tool's scope.

Approvals uses its existing Project/repository groups and bulk decisions. The original requested hosts remain visible, and each host has one selectable action. Approving saves only the checked host subset. The repository scope, permanence, fixed ports and public-only safety constraints cannot be unchecked. A manual repository operator decision, or the required team administrator decision for broader authority, saves the selected additions in Network settings without replacing existing hosts. General session auto-approval does not approve these requests.

Poll get_repository_network_access_status with {"approvalId":"..."}. The typed receipt separates the following outcomes:

State Meaning
requested Waiting for a manual decision; no new host is authorized.
persisted The selected hosts are saved permanently; no running managed gateway has confirmed application.
queued The permanent policy is saved and a host gateway update is pending.
applied Trusted host evidence confirms the repository gateway revision.
provision-error The permanent policy is saved, but gateway application failed or remains unverified.
denied, expired, withdrawn, stale This request does not authorize new access; changed repository identity or policy needs a fresh review.

The console preserves saved, queued and applied distinctions in progress and History. It does not present a native notification retry as a gateway repair. There is no extra apply step after the typed decision. A pending request can be withdrawn; remove already persisted hosts in Network settings to revoke access. Review expiry limits pending authorization, not the lifetime of saved hosts. Legacy prose/session approvals remain session scoped and are not migrated by this feature. Plain request_permission still cannot change a gateway.

Execute a reviewed configuration plan

Call get_permission_status with {"commands":true} to discover supported command names and their exact JSON argument schemas for this session's agent. This read changes nothing. The supported registry contains:

Attach at most 20 commands to request_permission; the entire request is bounded to 12,000 UTF-8 JSON bytes. Each command has actionIndex, tool and arguments. actionIndex is the zero-based index of its human-readable action checkbox. Use existing catalog IDs and current values from inspection, never credentials or executable shell text. For example, after verifying that the catalog endpoint exists and RTK is already enabled and installed:

{
  "title": "Connect the test API and update RTK",
  "resource": "Project test API and installed context tools",
  "actions": ["Grant the test API endpoint", "Update installed RTK"],
  "purpose": "Run the Project checks with its configured service and tools",
  "risk": "medium",
  "constraints": ["Keep the current session running"],
  "mcpCommands": [
    {
      "actionIndex": 0,
      "tool": "grant_service",
      "arguments": {"serviceId": "test-api", "endpointId": "http", "alias": "test-api"}
    },
    {
      "actionIndex": 1,
      "tool": "configure_context_tools",
      "arguments": {"action": "update", "tools": ["rtk"]}
    }
  ]
}

The controller always classifies a command array as danger, irrespective of the agent's declaration or a Decisions verdict. Auto-approve never executes it. The operator must open the request, review the exact tool names and arguments, and approve the retained action/constraint checkboxes. Unchecking an action skips every command with that actionIndex; it does not execute a narrower invented command. Other grants and their documents remain intact.

The operator API is POST /v1/mcp/approvals/:id/approve, with the selected actionIndices, constraintIndices and the exact reviewed planHash from commandPlan.hash in the request detail. An omitted or mismatched hash returns 409 with a refresh/review instruction, protecting clients that cannot display the command plan. Ordinary prose approvals remain backward compatible.

After approval, the controller executes selected commands in order, even with all consoles closed. It reuses existing typed dispatchers and rechecks the approving actor, owner, native session/generation, target configuration revisions and Run lease. An authorized canonical operator can approve additional network destinations for a tenant; a tenant approving its own request cannot acquire that operator authority. Commands do not implicitly restart a session or bypass container recreation requirements.

get_permission_status({"approvalId":"..."}) reports execution separately from native rules delivery: plan state, planHash, per-step state and any accepted host job IDs/outcomes. Plan states include awaiting-approval, queued, running, succeeded, failed, uncertain and cancelled; unchecked steps are skipped. succeeded means the configuration dispatcher accepted each selected command, not that a queued host job completed or an upstream endpoint is ready. Verify those outcomes before using the resource.

A started step is persisted before its write. If the controller loses certainty about that write, the plan stops as uncertain: it never automatically replays the command or proceeds to later steps. Inspect actual configuration before requesting any replacement plan. Failure does not roll back earlier changes. Rules delivery is queued only after selected commands succeed and still needs its own native receipt. Retrying rules delivery cannot rerun the command plan. Withdrawal cancels remaining steps and delivery; it does not undo applied changes.

Updated host brokers can serve the current schema and advertise tool-list changes after reconnect. Native registration remains client-dependent: current Codex TUI can retain a startup allowlist or cached schema, and its live refresh is unverified. Preserve active provider processes and containers. Never replace a rejected command array with shell instructions.

The broker supports request/status/withdrawal tools where the existing built-in devctl binding and current policy authorize them; disabling devctl disables this access. Their visibility in a native client is a separate check. After a host-agent restart, active sessions' broker listeners are restored from their existing immutable MCP snapshots automatically. Recovery is scoped to the owning host and current provider generation, retried after failures and cached until that identity changes. It never opens or replaces a terminal. The built-in MCP advertises tool-list changes on reconnect; this is not proof that the running native client imported new names. The updated canonical credential-free built-in configuration removes its static filter for future Codex launches, without changing existing processes or external MCP allowlists. See native catalog limits. Use existing authorized tools or session CLI/socket transport where available. If the native tool is missing or fails and no such transport is available, report that concrete limitation in a structured question instead of claiming a pending devctl approval.

Rules and their snapshot directory belong to the session UID. Delivery repairs older root-owned snapshot directories in place before atomically writing rules; it pins every directory with O_NOFOLLOW and checks the session HOME and rules ownership. Only that directory's metadata is repaired as root; policy writing and tmux notification run as the session UID. No provider/container restart is needed. Delivery failures expose the bounded sanitized cause in MCP Approvals and get_permission_status. Project doctor includes approved rules deliveries as separate checks: pending is a warning, failed is an error, delivered is OK.

Agent packages can resolve the rules path from their verified native session configuration. Antigravity uses its account-owned managed runtime rule and digest to find the snapshot the live CLI actually loaded, even when the controller has recorded a newer configuration. Delivery and withdrawal use that same existing rules file; they do not create a replacement snapshot or discard earlier grants. The normal session, account and process-generation authorization checks still apply. Edited metadata, symlinks or paths outside the session HOME fail closed.

Approving or retrying queues the durable permission command and immediately pushes it over the host's existing authenticated terminal/resource WebSocket. Delivery runs independently of inventory scans, account probes, image builds and the periodic host tick. Polling remains a fallback; reconnect replays pending commands for only that host. Both paths share command-ID deduplication and result posting. Notifications serialize per session and provider generation. A deferred notification remains at the head until native submission is confirmed; subsequent approvals for that generation cannot paste into the composer ahead of it. A busy composer does not block another Project. Polling skips that session for a short cooldown so unrelated host commands can proceed. No global polling interval is shortened. A separate bounded retry pump retries the head notification after one second, without waiting for inventory; following notifications use the same FIFO lane. On transport failure the durable controller queue determines replay order.

The active request list retains approved requests while delivery is pending and shows an animated Delivering rules indicator with elapsed time from the latest queue/retry. Failed deliveries remain visible and retryable without granting the permission again. The request/repository disappears after verified submission; denials disappear immediately. Older unverified successful sends remain in history for explicit revalidation. Only outstanding deliveries refresh faster, with one bounded 500 ms UI poll of /v1/mcp/approvals; ordinary console polling is unchanged. The poll belongs to the application and continues after leaving Approvals, including while another form is open. Confirmation, failure or withdrawal stops the sidebar spinner without keyboard interaction. A slower inventory response cannot replace a newer delivery result. Legacy sends awaiting explicit revalidation show a retry action, not an active-delivery spinner. Once the host has written the rules, the active request shows Rules written · waiting for session confirmation and elapsed time. This stage is persisted, so reopening the console keeps the real status and timer. Other requests for that session remain Queued · N ahead. A provider busy with a tool turn can delay its native acknowledgment even though its rules file is already updated.

Delivery uses explicit bracketed paste followed by a separate Enter key, never a newline inside the pasted text. The provider generation is checked again before Enter. A delivery receipt is written only when the native UserPromptSubmit hook acknowledges the exact notification for the current session and generation; a successful tmux write alone does not count as delivery. This confirms submission, not that the model has already read the rules. The managed lifecycle hook is updated in place through host synchronization; provider sessions need no restart.

Submission acknowledgment has a four-second deadline per attempt. A busy composer, an existing user draft or a delayed native hook keeps delivery pending and retries automatically. No approval is marked delivered without the native receipt. Unsafe paths, replaced provider identities and edited notifications still fail visibly; they require operator review. A retry submits the pending notification without pasting another copy, or accepts a receipt that arrived after the previous attempt. Delivery also recognizes an identical approval notification left in the composer by an older sender and submits it once. Existing or edited user drafts are preserved; delivery waits for the user to submit or clear them. Older receipts that only recorded a sent key are not accepted as verified submissions. In MCP Approvals history, these show notification submission unverified and r / Verify notification. Revalidation keeps the original grant and rules; verified successful submissions cannot be replayed. Docker transport calls and each delivery phase have a 10-second deadline. Queued approvals show elapsed time and missing host confirmation rather than claiming an indefinitely active delivery.

The review screen shows both Project and repository, separates ALLOW from LIMITS, and highlights potentially destructive actions above the other grants. Action and LIMIT checkboxes are selected by default. The controller keeps only selected actions and constraints in the canonical policy and live delivery command. Unchecking a LIMIT explicitly omits that restriction from this grant; other existing policy documents still apply. Empty selections cannot be approved; deny the request instead. Existing CLI approvals with no selection still approve a full ordinary request; command plans also require the reviewed hash described above.

The active review list has three levels: Project, repository name, and request summary. It contains undecided requests and approved requests awaiting verified delivery. Denying the last request removes the repository immediately; an approval keeps it visible until delivery is verified. Select a request and press a / d to decide directly with the current selections (all selected by default), or Enter to review its checkboxes first. Enter on a repository reviews its pending requests together. h / History shows all requests and outcomes, including queued/failed rules delivery. The detail view retains the original request and shows which actions were granted and which constraints were applied or omitted. Approved/denied history entries cannot be approved again; failed delivery can still be retried.

On a repository row or in its combined detail view, a / d applies to all of that repository's pending requests. The buttons show the batch size. On a request row, the action applies only to that request, including its individual detail view. The same browser handler owns these shortcuts when focus is still in the left navigation; the outer App never submits a separate single-request decision. Captured text input in another dialog cannot trigger these actions. Batch approval uses each request's current action/limit checkbox selection; all selections are validated before the first write. Open every command-plan request to review its exact arguments before approving the batch; an unreviewed plan cannot be included through a repository shortcut. Already decided requests and other repositories are excluded. Each decision is saved independently: a partial failure reports the count, refreshes the list, and leaves only failed requests pending for a retry.

Resource tags and risk

Agents annotate requests with multiple resource tags such as filesystem, database, external-service, network, credentials, compute, git and project-specific tags. Tags use lowercase letters, numbers and hyphens. risk is low, medium, high, danger or unknown. Optional fields describe impact (read/write/destructive/administrative), reversibility, environment, sensitivity and cost. Mixed requests can add actionMetadata entries with the unique zero-based action index, its tags and risk. Actions and constraints remain independently selectable. Older clients can send requests without metadata.

The controller validates the declaration and produces the canonical classification. It flags destructive action names and disruptive typed operations, retains an agent's high/danger declaration and conservatively classifies old requests. TUI and web only render this metadata; neither scans request text or decides risk. Classification describes the proposed scope, not a technical guarantee about subsequent shell commands or database privileges.

When a Decisions provider is configured and Approval tags and danger verification is enabled, a bounded controller queue reviews the request using the project/provider budget. The provider can add a resource tag or raise risk; it cannot erase controller/agent danger flags. Unavailable or unknown-risk, budget-blocked or interrupted reviews keep the request manual. Review calls, tokens and cost context appear in Decisions history with purpose Approval tags / danger verification. Failed reviews are not silently re-billed after controller recovery.

Provider failures display a safe cause such as rejected authentication or exhausted credits, without exposing the upstream response or credential. After the operator updates provider configuration, up to 32 unexpired pending reviews that previously failed can be queued again. Existing budgets, session identity and danger checks still apply; saving configuration is not an access approval.

Automatic approval

In MCP Approvals, press u or click Auto-approve ordinary requests. This is off initially. Enabling it approves eligible existing requests and future requests for this console user's sessions; typed command plans, danger, unknown, expired or stale requests remain manual. It preserves all requested actions and LIMITS. It never restarts a session to deliver rules. The switch is persisted in the controller and operates when TUI/web is closed. Server users cannot change another user's switch; session/host MCP tokens cannot enable it themselves. History distinguishes automatic decisions from operator clicks. Turning it off affects future decisions and does not revoke already granted permissions. Pending requests show the controller's reason for pausing automatic approval, including unknown risk, unavailable review or changed session identity. Unknown risk is still eligible for an explicit operator decision.

Decisions risk confidence and resource-tag confidence are recorded separately. Automatic approval accepts an explicit low/medium verdict at any confidence under the enabled non-danger policy; uncertainty about a resource tag alone does not block it. Uncertain inferred tags are omitted. On startup, the controller rechecks legacy inconclusive reviews that combined these two scores or applied an old confidence threshold, once per still-current request with automatic approval enabled. The repair uses the project's existing Decisions budget and is persisted before calling the provider; resolved or stale requests are never re-reviewed. Interrupted reviews remain manual without another charge.

GET /v1/mcp/approvals/automation reads the current user's setting; PUT accepts only {"enabled":true} or {"enabled":false}. Decisions usage settings are separate from this switch. For ordinary standalone typed mutations, automatic approval still binds the one-shot permit to the exact arguments/config revision; the agent must retry with that approval ID. Eligible plain policy requests deliver automatically. This never applies to request_permission.mcpCommands plans.

Withdraw obsolete requests

Agents must call withdraw_permission_request with their own approvalId when access is no longer needed. Saying a request was withdrawn in chat does not change devctrl state. Withdrawal needs no new approval, cannot target another session, and is idempotent. Operators can select a request in MCP Approvals and press w (or click Withdraw request); this action never withdraws an entire repository implicitly.

{"approvalId":"mcp-approval-<request-id>"}

The operator API is POST /v1/mcp/approvals/:id/withdraw. Pending and approved policy requests can be withdrawn; denied/expired requests cannot be converted into another authorization. The tool is separate from typed Service grants: withdrawal does not revoke a Service credential or undo completed SQL/API work.

Withdrawn requests immediately leave the active list and remain in History with status withdrawn and delivery cancelled. The controller retires the queued approval notification, removes its configuration binding, and queues removal of the exact written exception. Host retries recheck command authorization; a runtime cancellation marker prevents an old notification from restoring rules or pressing Enter. Other permissions and user drafts are preserved. get_permission_status reports removal as pending/removed/failed separately from the cancelled delivery. Withdrawal does not restart a session or undo work already performed.

The original Decisions risk verdict is retained separately from confidence. Legacy confidence-gated holds are re-reviewed once for the exact live session generation; current unknown or unavailable verdicts stay manual and are not repeatedly billed.

Native questions to the operator

Managed Claude/Codex lifecycle hooks distinguish a question tool from normal tool execution: request_user_input, request_user_input_async and AskUserQuestion produce QUESTION · NEEDS YOUR ANSWER in Projects/session status and the Dashboard attention count. An asynchronous question remains visible while independent tools continue, with the working lifecycle preserved so automation never mistakes that work for an idle safe point. The marker clears after the native answer completes or the next user prompt is submitted; no question text, options or answers are persisted by this collector. Open the session to answer using the native CLI question interface. Configured browser notifications raise attention for questions, including a question appearing in an already idle session.

The host refreshes existing managed hook scripts in place. It does not restart running agents or pretend a CLI without configured hooks now observes them. There is no documented environment switch for expanding Codex questions into plain terminal output. Codex's external notify currently covers turn completion, not this workflow; see the official notification configuration.