feat(tool-server): settings-permissions tool to grant/deny/reset app permissions #462
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| --- | ||
| name: argent-settings-permissions | ||
| description: Grant, deny, or reset an app's runtime permissions (camera, microphone, photos, contacts, notifications, calendar, location, location-always, media-library, motion, reminders) on an iOS simulator or Android device using the argent `settings-permissions` tool - without navigating the system Settings UI. Use when the permission cannot be changed through the app itself - and only then, pre-authorize before the app asks, deny up front, re-enable a permission the user already denied, or reset so the prompt reappears. If the app can flip it - via an in-app toggle or the system permission dialog the app triggers - interact with the app instead. | ||
| --- | ||
|
|
||
| ## What this tool is for | ||
|
|
||
| `settings-permissions` edits the platform's permission store directly - the iOS simulator's TCC database via `xcrun simctl privacy`, or Android's package-manager permission flags via `pm grant` / `pm revoke`. It replaces the manual **Settings → Privacy** dance during test setup: pre-authorize a service so the app never has to ask, deny it up front to test the refusal path, or reset it so the first-run dialog appears again on the next launch. | ||
|
|
||
| It is a **test-setup / out-of-band** tool, not a general permissions toggle. The default way to change a permission is still through the app - this tool is the exception for the cases the app can't reach. | ||
|
|
||
| ## When to use it - and when NOT to | ||
|
|
||
| Decide with this order. The first matching row wins. | ||
|
|
||
| | Situation | Do this | Why | | ||
| | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | The app has an **in-app control** for the permission (a toggle in its own settings screen) | **Tap it in the app** (`describe` → `gesture-tap`) - do NOT use this tool | It's real user behavior and exercises the flow you're testing. See `argent-device-interact`. | | ||
| | The app is **about to ask** (or just asked) and the system **permission dialog is on screen** | **Tap the dialog** (`Allow` / `Don't Allow` / `Allow While Using App`) - do NOT use this tool | The app-triggered prompt is the natural path; answering it is what a user does. `describe` exposes the dialog buttons; fall back to `screenshot` only if it doesn't. | | ||
| | You need the permission **already granted/denied before the app runs**, so no dialog interrupts the flow | **Use this tool** (`grant` / `deny`) before `launch-app` | The app can't pre-set its own permission; a real user would do it in Settings. This is the core use case. (`deny` suppresses the prompt on **iOS only** - see Gotchas.) | | ||
| | The user **already denied** it and you need it **on** again | **Use this tool** (`grant`) | iOS never re-shows a dialog once denied - the only in-device path is the Settings app. This tool is the shortcut. | | ||
| | You need the **first-run dialog to appear again** (test the prompt itself, or reset dirty state) | **Use this tool** (`reset`) | Returns the permission to "not yet asked" so the app prompts on next use. | | ||
| | The permission is **not one this tool supports** on the target platform (see the support table) | **Do NOT use this tool** | It will return an "unsupported" error. Use the app dialog if the app triggers one, or navigate the real Settings app. | | ||
| | The setting isn't one of the **11 runtime permissions** below (e.g. Wi-Fi, cellular data, dark mode, VPN, Focus) | **Do NOT use this tool** | Out of scope - drive the Settings app or the app's own UI instead. | | ||
|
|
||
| **Rule of thumb:** if a human tester could flip it _inside the app_, do that. Reach for `settings-permissions` only for a change a human would otherwise make in the **system Settings app**. | ||
|
|
||
| ## Supported permissions & platform coverage | ||
|
|
||
| | `permission` | iOS simulator (`simctl privacy` service) | Android (`android.permission.*`) | | ||
| | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | ||
| | `camera` | `camera` - only if the target simulator's **runtime** models it (varies by simruntime, not by the installed Xcode; simulators have no camera hardware) | `CAMERA` | | ||
| | `microphone` | `microphone` | `RECORD_AUDIO` | | ||
| | `photos` | `photos` + `photos-add` (add-only access is a separate TCC service; deny/reset clear both) | `READ_MEDIA_IMAGES` + `READ_MEDIA_VIDEO` + `READ_MEDIA_VISUAL_USER_SELECTED` + `READ_EXTERNAL_STORAGE` | | ||
| | `contacts` | `contacts` | `READ_CONTACTS` + `WRITE_CONTACTS` | | ||
| | `notifications` | **unsupported** - no simctl service; answer the app's dialog instead | `POST_NOTIFICATIONS` | | ||
| | `calendar` | `calendar` | `READ_CALENDAR` + `WRITE_CALENDAR` | | ||
| | `location` | `location` | `ACCESS_FINE_LOCATION` + `ACCESS_COARSE_LOCATION` | | ||
| | `location-always` | `location-always` | `ACCESS_BACKGROUND_LOCATION` (a **grant** also adds fine + coarse - background alone can't read location) | | ||
| | `media-library` | `media-library` | `READ_MEDIA_AUDIO` + `READ_EXTERNAL_STORAGE` | | ||
| | `motion` | `motion` | `ACTIVITY_RECOGNITION` | | ||
| | `reminders` | `reminders` | **unsupported** - no Android runtime permission | | ||
|
|
||
| One abstract permission can map to several concrete Android permissions; which ones actually exist depends on the app's manifest and the device's API level (e.g. `READ_MEDIA_*` on API 33+ vs `READ_EXTERNAL_STORAGE` below it). | ||
|
|
||
| ## Actions | ||
|
|
||
| - **`grant`** - pre-authorize the permission. Requires `bundleId`. | ||
| - **`deny`** - refuse it (iOS `revoke`). Requires `bundleId`. Use to test the app's "permission denied" path. | ||
| - **`reset`** - return to the not-yet-asked state so the dialog reappears on next use. Always per-app (`bundleId` required): | ||
| - iOS: `simctl privacy reset <service> <bundleId>` removes that app's TCC row. A device-wide reset (no bundleId) is **not** offered - on recent iOS runtimes it exits 0 but leaves existing per-app grants untouched, so it would report a change that never happened. | ||
| - Android: `pm revoke` + a best-effort `pm clear-permission-flags` (the flag-clear first appears in Android 13 / API 33; the revoke is what counts toward success). On API 29-32 the flag-clear is unavailable, so a `reset` there revokes the grant but cannot clear a "don't ask again" (user-fixed) state - the dialog may stay suppressed on those older devices. | ||
|
|
||
| ## Parameters | ||
|
|
||
| ```json | ||
| { | ||
| "udid": "<UDID-or-serial>", | ||
| "action": "grant", | ||
| "permission": "camera", | ||
| "bundleId": "com.example.app" | ||
| } | ||
| ``` | ||
|
|
||
| - `udid` - target from `list-devices` (iOS simulator UDID, or Android serial). See `argent-ios-simulator-setup` / `argent-android-emulator-setup` to get one. | ||
| - `action` - `grant` | `deny` | `reset`. | ||
| - `permission` - one of the 11 names above. | ||
| - `bundleId` - iOS bundle id or Android package name. **Required for every action**. | ||
|
|
||
| ## Platform behavior | ||
|
|
||
| **iOS simulator only.** Runs `xcrun simctl privacy <udid> grant|revoke|reset <service> <bundleId>` - always per-app (`bundleId` required). There is no host-side TCC switch on a physical iPhone, so this tool does not apply to real iOS devices. The simulator must be **booted** first (`boot-device`) - otherwise simctl fails with a "current state: Shutdown" error and the tool surfaces the boot hint. | ||
|
|
||
| **Android emulator and physical device.** Runs `pm grant` / `pm revoke` (and, for `reset`, a best-effort `pm clear-permission-flags … user-set user-fixed` - the revoke is what decides success; the flag-clear needs Android 13 / API 33+) over adb. Requirements: | ||
|
|
||
| - The app must be **installed** - the tool probes with `pm list packages` first and errors clearly if the package is missing (a transport/timeout failure surfaces adb's real cause, not a false "not installed"). | ||
| - The app must **declare** the permission in its manifest. `pm` rejects any mapped permission the manifest doesn't request; those come back in the result's `skipped` list. The action succeeds if **at least one** mapped permission sticks, and errors only if `pm` rejected **all** of them. | ||
|
|
||
| ## Gotchas | ||
|
|
||
| - **Changing a permission can terminate a running app** (system behavior on both platforms). Prefer setting permissions **before** `launch-app`; if you change one while the app is running, `restart-app` afterward. | ||
| - **Reset is per-app on both platforms** - pass `bundleId`; there is no reliable device-wide reset. | ||
| - **A partial Android result is normal.** `applied` lists what actually changed; `skipped` lists mapped permissions `pm` rejected (usually not in the manifest, or gated by API level). Both together tell you what happened. | ||
| - **A pre-launch `deny` suppresses the prompt on iOS only.** On iOS a TCC denial answers the app's request, so no dialog appears. On Android `pm revoke` clears the grant but sets no "user-fixed" flag, so the app's next request still shows the system dialog - a pre-launch `deny` there tests the revoked _state_, not a suppressed prompt. | ||
| - **`camera` on iOS** may be rejected by a simulator **runtime** that doesn't model the service (it varies by simruntime, not by the installed Xcode - a runtime can accept `camera` even when the Xcode's `simctl privacy` usage text omits it). simctl reports a rejection as a generic CoreSimulator error, so a `camera` failure (unless it's the shutdown-simulator case, which gets the boot hint instead) carries a hint to run `xcrun simctl privacy` and list the supported services. | ||
| - **`grant location` needs the app installed first (iOS).** Location authorization isn't stored in TCC and isn't applied to a bundle id until the app exists, so a pre-install `grant location` / `grant location-always` records nothing - the tool checks and errors clearly instead of reporting a false success. (TCC-backed services like `camera`/`photos` _can_ be granted before install; they persist and apply on install.) | ||
|
Member
There was a problem hiding this comment. The remote branch this PR also adds can't keep this promise: |
||
|
|
||
| ## Result | ||
|
|
||
| Returns `{ action, permission, bundleId, applied, skipped? }`: | ||
|
|
||
| - `applied` - the platform-level services/permissions actually changed (the simctl service on iOS; the `android.permission.*` names on Android). | ||
| - `skipped` - Android only, present when some mapped permissions were rejected but others succeeded. | ||
|
|
||
| The call **fails** when nothing could be applied - read the error; it names the reason: an unsupported permission for the platform (`notifications` on iOS, `reminders` on Android), the app not installed (including a pre-install `grant location` on iOS), a shutdown simulator (iOS), or `pm` rejecting every mapped permission (usually a missing manifest entry). A non-shutdown `camera` failure additionally hints to list the simulator runtime's supported services (a shutdown-simulator failure gets the boot hint instead). | ||
|
|
||
| ## Examples | ||
|
|
||
| Pre-grant the camera before launching, so the app never prompts: | ||
|
|
||
| ```json | ||
| { "udid": "<UDID>", "action": "grant", "permission": "camera", "bundleId": "com.example.app" } | ||
| ``` | ||
|
|
||
| Test the denied path - refuse location, then launch and observe the fallback: | ||
|
|
||
| ```json | ||
| { "udid": "<serial>", "action": "deny", "permission": "location", "bundleId": "com.example.app" } | ||
| ``` | ||
|
|
||
| Reset notifications on Android so the first-run prompt appears again next launch: | ||
|
|
||
| ```json | ||
| { | ||
| "udid": "<serial>", | ||
| "action": "reset", | ||
| "permission": "notifications", | ||
| "bundleId": "com.example.app" | ||
| } | ||
| ``` | ||
|
|
||
| Grant always-on location on Android (fans out to background + foreground automatically): | ||
|
|
||
| ```json | ||
| { | ||
| "udid": "<serial>", | ||
| "action": "grant", | ||
| "permission": "location-always", | ||
| "bundleId": "com.example.app" | ||
| } | ||
| ``` | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"deny/reset clear both" is stronger than the implementation guarantees:
photos-addis deliberately best-effort — a secondary-service failure is skipped silently, it does not appear in the result'sskipped(which types.ts pins as Android-only), and types.ts'sapplieddoc still describes fan-out as an Android-only phenomenon. When the second call fails, the result is a success whoseappliedlists onlyphotos— consistent with the code's stated best-effort intent, but not with this row's unconditional wording.