Struct PermissionRegistry 

pub struct PermissionRegistry { /* private fields */ }

Registry for managing permission grants and requests.

This registry implements the new grant-based permission system with:

• Hierarchical permission levels (Admin > Execute > Write > Read > None)
• Path-based grants with optional recursion
• Domain and command pattern grants
• Batch permission request handling

Lock Ordering

This struct contains multiple async mutexes. To prevent deadlocks, all methods follow these rules:

1. Never hold multiple locks simultaneously - each method acquires locks in separate scopes, releasing one before acquiring the next
2. Release locks before async operations - locks are released before sending to channels or awaiting other async calls
3. Sequential ordering when multiple locks needed:
   • pending_requests or pending_batches first (for request lookup)
   • session_grants second (for grant operations)

Example pattern used throughout:

// Good: sequential lock acquisition in separate scopes
let request = {
    let mut pending = self.pending_requests.lock().await;
    pending.remove(id)?
}; // lock released here
self.add_grant(session_id, grant).await; // acquires session_grants

Implementations

impl PermissionRegistry

pub fn new(event_tx: Sender<ControllerEvent>) -> PermissionRegistry

Creates a new PermissionRegistry.

Arguments

• event_tx - Channel to send events when permissions are requested.

pub async fn add_grant(&self, session_id: i64, grant: Grant)

Adds a grant for a session.

Arguments

• session_id - Session to add the grant to.
• grant - The grant to add.

pub async fn add_grants(&self, session_id: i64, new_grants: Vec<Grant>)

Adds multiple grants for a session.

Arguments

• session_id - Session to add the grants to.
• new_grants - The grants to add.

pub async fn cleanup_expired(&self, session_id: i64)

Removes expired grants from a session.

pub async fn revoke_grants( &self, session_id: i64, target: &GrantTarget, ) -> usize

Revokes all grants matching a specific target for a session.

Arguments

• session_id - Session to revoke grants from.
• target - Target to match for revocation.

Returns

Number of grants revoked.

pub async fn get_grants(&self, session_id: i64) -> Vec<Grant>

Gets all grants for a session.

Arguments

• session_id - Session to query.

Returns

List of grants for the session (empty if none).

pub async fn clear_grants(&self, session_id: i64)

Clears all grants for a session.

Arguments

• session_id - Session to clear.

pub async fn check(&self, session_id: i64, request: &PermissionRequest) -> bool

Checks if a permission request is satisfied by existing grants.

This checks if any grant in the session satisfies the request based on:

1. Target coverage (grant target covers request target)
2. Level hierarchy (grant level >= required level)
3. Grant not expired

Arguments

• session_id - Session to check.
• request - The permission request to check.

Returns

true if permission is granted, false otherwise.

pub async fn check_batch( &self, session_id: i64, requests: &[PermissionRequest], ) -> HashSet<String>

Checks multiple permission requests and returns which are already granted.

Arguments

• session_id - Session to check.
• requests - The permission requests to check.

Returns

Set of request IDs that are already granted.

pub async fn find_satisfying_grant( &self, session_id: i64, request: &PermissionRequest, ) -> Option<Grant>

Finds which grant (if any) satisfies a request.

Arguments

• session_id - Session to check.
• request - The permission request to check.

Returns

The grant that satisfies the request, if any.

pub async fn request_permission( &self, session_id: i64, request: PermissionRequest, turn_id: Option<TurnId>, ) -> Result<Receiver<PermissionPanelResponse>, PermissionError>

Registers an individual permission request.

If the request is already satisfied by existing grants, returns an auto-approved response immediately. Otherwise, registers the request, emits an event, and returns a receiver to await the response.

Arguments

• session_id - Session requesting permission.
• request - The permission request.
• turn_id - Optional turn ID for UI context.

Returns

A receiver that will receive a PermissionPanelResponse.

pub async fn respond_to_request( &self, request_id: &str, response: PermissionPanelResponse, ) -> Result<(), PermissionError>

Responds to an individual permission request.

Arguments

• request_id - ID of the request to respond to.
• response - The user’s response (grant/deny with optional persistent grant).

Returns

Ok(()) if successful.

pub async fn cancel(&self, request_id: &str) -> Result<(), PermissionError>

Cancels a pending permission request.

This is called by the UI when the user closes the permission dialog without responding. Dropping the sender will cause the tool to receive a RecvError.

Arguments

• request_id - ID of the request to cancel.

Returns

Ok(()) if the request was found and cancelled.

pub async fn pending_for_session( &self, session_id: i64, ) -> Vec<PendingPermissionInfo>

Gets all pending permission requests for a session.

Arguments

• session_id - Session ID to query.

Returns

List of pending permission info for the session.

pub async fn is_granted( &self, session_id: i64, request: &PermissionRequest, ) -> bool

Check if permission is already granted for the session.

This is a convenience method that wraps check(). Uses the Grant::satisfies method from the permission system.

Arguments

• session_id - Session to check.
• request - The permission request to check.

Returns

True if permission was previously granted for the session.

pub async fn register_batch( &self, session_id: i64, requests: Vec<PermissionRequest>, turn_id: Option<TurnId>, ) -> Result<Receiver<BatchPermissionResponse>, PermissionError>

Registers a batch of permission requests.

Requests that are already satisfied by existing grants are auto-approved and not included in the batch sent to the UI.

Arguments

• session_id - Session requesting permissions.
• requests - The permission requests.
• turn_id - Optional turn ID for UI context.

Returns

A receiver that will receive the batch response.

pub async fn respond_to_batch( &self, batch_id: &str, response: BatchPermissionResponse, ) -> Result<(), PermissionError>

Responds to a batch permission request.

Arguments

• batch_id - ID of the batch to respond to.
• response - The batch response with approved grants and denied requests.

Returns

Ok(()) if successful.

pub async fn cancel_batch(&self, batch_id: &str) -> Result<(), PermissionError>

Cancels a pending batch permission request.

This is called by the UI when the user closes the batch permission dialog without responding. Dropping the sender will cause the tools to receive errors.

Arguments

• batch_id - ID of the batch to cancel.

Returns

Ok(()) if the batch was found and cancelled.

pub async fn cancel_session(&self, session_id: i64)

Cancels all pending requests for a session.

This drops the response channels, causing receivers to get errors.

Arguments

• session_id - Session to cancel.

pub async fn clear_session(&self, session_id: i64)

Clears all state for a session (grants and pending requests).

Arguments

• session_id - Session to clear.

pub async fn has_pending(&self, session_id: i64) -> bool

Checks if there are any pending requests for a session.

Arguments

• session_id - Session to check.

Returns

true if there are pending requests.

pub async fn pending_count(&self) -> usize

Gets count of pending requests across all sessions.

pub async fn pending_request_ids(&self, session_id: i64) -> Vec<String>

Gets pending request IDs for a session.

pub async fn pending_batch_ids(&self, session_id: i64) -> Vec<String>

Gets pending batch IDs for a session.