# Native Dialog Handling

AgentKit automatically intercepts native `Alert.alert()`, `PermissionsAndroid`, and `react-native-permissions` dialogs.

## How It Works

- **Conditional suppression** — Native dialogs are only suppressed when an agent is connected. When no agent is connected, they display normally.
- Alert buttons use the format: `alert-{title}-{button-text}`
- Permission buttons use the format: `permission-{name}-grant` / `permission-{name}-deny` / `permission-{name}-block`
- Buttons auto-clean up after being tapped or after a timeout

## Examples

### Alert Dialogs

```bash
# After an action triggers Alert.alert('Confirm', '...', [{text:'Cancel'}, {text:'Delete'}])
list                              # Shows: alert-confirm-cancel, alert-confirm-delete
tap alert-confirm-delete          # Executes the Delete button's onPress handler
```

### Permission Requests

```bash
# Permission request (via PermissionsAndroid or react-native-permissions)
list                              # Shows: permission-camera-grant, permission-camera-deny, permission-camera-block
tap permission-camera-grant       # Grants the permission
```

> 💡 **Tip**: Apps using `react-native-permissions` get automatic interception for both iOS and Android.

## OS-Level vs JS-Level Permissions

AgentKit handles permissions at two layers:

1. **OS-level** — Use `device grant-permissions` CLI command to pre-grant permissions before app launch. This prevents the native OS permission dialog from ever appearing. See [Device Management](./device-management.md).

2. **JS-level** — The built-in `NativeDialogInterceptor` catches any permission dialogs that come from JavaScript code (`PermissionsAndroid`, `react-native-permissions`, `Alert.alert`). The agent can tap grant/deny buttons programmatically.

Both layers work together — pre-grant to prevent OS dialogs, and the interceptor catches any remaining JS-level ones.