feat(tool-server): settings-permissions tool to grant/deny/reset app permissions

[hubgan]

What

Adds a settings-permissions MCP tool that edits an app's runtime permissions out-of-band, without navigating the system Settings UI. It's a test-setup / out-of-band tool — the default way to change a permission is still through the app (in-app toggle or the app-triggered dialog). Reach for this only when the app can't get there:

• pre-authorize (grant) or deny a permission before the app asks, so no dialog interrupts the flow
• re-enable one the user already denied (iOS never re-prompts once denied)
• reset it so the first-run dialog reappears on next launch

Supported permissions: camera, microphone, photos, contacts, notifications, calendar, location, location-always, media-library, motion, reminders.

How

iOS simulator — xcrun simctl privacy grant|revoke|reset <service> [bundleId].

• notifications has no simctl service → surfaced as an unsupported error.
• An "invalid service" failure (e.g. camera on an Xcode that doesn't model it) is wrapped as unsupported with a hint to list supported services.
• A shutdown simulator error carries a boot-device hint.

Android — pm grant / pm revoke (plus clear-permission-flags on reset) over adb.

• One abstract permission fans out to the concrete android.permission.* set (fine/coarse location, per-media reads); location-always grant also grants foreground location since background alone is unusable.
• A pm path preflight rejects an uninstalled package (pm grant/revoke exit 0 for a missing package, which would otherwise report a false success). A transport-level adb failure is rethrown rather than mislabeled as "not installed" (isTerminalAdbError is now exported for this).
• Partial results land in skipped; the action fails only when pm rejects every mapped permission.

Supporting changes

• New failure codes: ANDROID_SETTINGS_PERMISSION_FAILED, IOS_SETTINGS_PERMISSION_FAILED, SETTINGS_PERMISSION_UNSUPPORTED.
• New argent-settings-permissions skill, plus cross-references from argent-device-interact, argent-test-ui-flow, and the argent rule (with a strong "prefer the app dialog over this tool" steer).
• bundleId is regex-validated (same shell-injection guard as launch-app/restart-app) and schema-required for grant/deny.

Testing

vitest — 37/37 pass (schema validation incl. shell-injection payloads, iOS branch, Android branch incl. partial/total pm failures and the preflight). tsc --noEmit clean for tool-server + registry + tests; prettier clean.

[latekvo]

Reviewed the new settings-permissions tool end-to-end — built the branch and ran the real iOS and Android handlers against an iOS 18.5 simulator and an API-34 Android emulator, plus the schema, docs, and test suite. It is well structured and the common grant/deny/per-app paths work as intended (verified observable state changes on both platforms). Inline notes below, mostly around reset semantics on each platform and the accuracy of a few error diagnoses.

[latekvo]

On success applied is set to [service] unconditionally, but a device-wide reset (no bundleId) does not actually clear existing per-app TCC entries on recent iOS. Reproduced on iOS 18.5: after granting camera to two apps, simctl privacy <udid> reset camera with no bundle exits 0 but leaves every per-app row intact, while the tool returns applied:["camera"]; a per-app reset camera <bundleId> correctly removes the single row. So on the device-wide reset path the caller gets a truthful-looking applied for a change that did not happen. Unlike the Android branch, the iOS branch never inspects the resulting state — the prose warns about this runtime behavior, but the return value still reports success.

[latekvo]

The description states the tool returns { action, permission, bundleId, applied, skipped? }, but bundleId is omitted from the result on an iOS device-wide reset (no bundleId supplied), where the handler spreads it only when present. The SKILL doc writes it as bundleId?; this description implies it is always echoed back.

[latekvo]

The installed-app check relies on an exact per-line match against package:<bundleId>. Because pm list packages <pkg> filters by substring, the normal output for an installed app is frequently multiple lines — the target plus any packages whose names contain it (e.g. pm list packages com.google.android.gms returns both package:com.google.android.gms.supervision and package:com.google.android.gms). The per-line .some(...) handles this correctly, but the tests only exercise the single-line, empty, and sibling-only-substring outputs — never the target-among-siblings shape — so a change to whole-output or first-line matching would keep every test green while making a real installed app read as "not installed".

[hubgan]

Fixed in e00cd0a — added a finds the target package among substring siblings test: pm list packages returns three lines (…app.helper, …app, …app.debug) and the test asserts the exact-target line is matched and the grant proceeds. A regression to whole-output or first-line matching now fails, since the first line is a sibling. Also confirmed against a real device — pm list packages com.google.android.gms returns both …gms.supervision and …gms, and the preflight resolves the exact target and grants.

[latekvo]

On API 34+ the platform auto-adds READ_MEDIA_VISUAL_USER_SELECTED (a dangerous runtime permission) to any app that requests READ_MEDIA_IMAGES/READ_MEDIA_VIDEO, and the partial-access dialog grants it persistently while IMAGES/VIDEO get only a session-long grant. Because the photos mapping never includes it, deny photos revokes the three listed permissions and reports full success while the app still passes its partial-access check and keeps reading the user-selected media, and reset photos does not return the app to the not-yet-asked state (the next request shows the "keep/select more" flow, not the first-run dialog). Reproduced on an API 34 emulator: with USER_SELECTED granted, deny photos returned applied: [READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_EXTERNAL_STORAGE] and dumpsys still showed READ_MEDIA_VISUAL_USER_SELECTED: granted=true afterward. This only bites when partial access was previously established through the real dialog, but that dirty-state flow is one the skill doc explicitly targets ("re-enable one the user already denied", "reset dirty state").

[latekvo]

The reset half of the asymmetry documented above is unpinned: tests cover the grant fan-out and deny staying background-only, but no test resets location-always. Changing this condition to action !== "deny" — which makes reset revoke ACCESS_FINE/COARSE_LOCATION too, exactly the "taking away 'always' shouldn't also strip 'while in use'" behavior the comment forbids — leaves all 43 tests green (verified by running the suite against that mutation). The suite pins the other comment-contracts in this file (shutdown-beats-camera-hint, per-app reset, the deny side of this same rule), so the reset side is the one gap.

[latekvo]

This catch folds every adbShell throw into the same per-permission failure shape as a pm rejection, which conflates two very different situations. If the device drops off mid-fan-out after one permission already succeeded (flaky USB / wireless adb), the call returns success with the dead-device permissions in skipped — which types.ts documents as entries "the package manager rejected (typically not declared in the app's manifest...)" — and the observed detail (e.g. device 'emulator-5554' not found) is dropped entirely on that path, so the caller is pointed at the manifest instead of the dead transport. Reproduced against the built module: grant photos with a disconnect after READ_MEDIA_IMAGES returns {applied: [READ_MEDIA_IMAGES], skipped: [READ_MEDIA_VIDEO, READ_EXTERNAL_STORAGE]} with no error. The catch also discards the FailureError classification adbShell already attached: on the all-rejected path the rethrow reports error_kind: "subprocess" with no subprocessFailureMetadata, so a wedged device timing out every pm call loses its timeout kind and exit/signal/command telemetry fields — the iOS branch of this same tool forwards exactly that metadata, and sibling Android branches (launch-app, open-url) let the classified adb error propagate.

[latekvo]

clear-permission-flags first appears in Android 13 — it is absent from the android11-release and android12-release PackageManagerShellCommand and present from android13-release — so this boundary (and the "API < 30" corollary below, the same claim in the skill doc, and the test comment) is off by two major versions. The ignore-the-outcome design holds either way, but the real consequence is wider than documented: on API 29-32, reset can never clear a user-fixed state (set automatically after repeated denies on 11/12), so a permission in "don't ask again" is revoked and reported reset while the dialog stays suppressed — and nothing in the result distinguishes that from a full reset. The skill doc's "does not exist before Android 11" actively misleads someone debugging exactly that on an Android 12 device.

[latekvo]

photos maps only to the photos TCC service, but add-only photo access lives in the separate photos-add service (kTCCServicePhotosAdd, listed separately by simctl privacy). After an app has been granted add-only access, deny photos and reset photos both return applied: ["photos"] while the kTCCServicePhotosAdd row survives untouched — reproduced on an iOS 18 simulator: granted photos-add, ran deny and then reset through the handler, and TCC.db still showed the add-only row at auth 2 after both reported success. For that state the documented deny/reset outcomes (the denied path, or the prompt reappearing) are reported as applied but don't happen.

[latekvo]

If a FAILURE_CODES member ever resolves to undefined at test runtime — vitest loads @argent/registry from its built dist, so a stale local dist that predates the three new codes does exactly that — this comparison becomes undefined === undefined, and every rejects.toSatisfy(failsWith(...)) in the file passes for any rejection, including TypeErrors from broken mocks. Verified end-to-end: with the code removed from the loaded dist, the full suite stayed green and a probe rejection carrying a plain Error satisfied the matcher. CI rebuilds before testing so it is shielded; a local vitest run without a rebuild is not, and nothing asserts the codes are strings.

[latekvo]

For deny, this row's promise — "already granted/denied before the app runs, so no dialog interrupts the flow" — doesn't hold on Android: pm revoke clears the grant but records no refusal (it sets no user-fixed flag, and dialog suppression keys off user-fixed/policy-fixed), so the app's next requestPermissions still shows the system dialog. That is faithful to Android's own single-deny semantics, but it silently diverges from the iOS half of this tool, where deny writes a TCC denial that answers the app without prompting. Nothing in the doc or tool description warns that a pre-launch deny keeps the dialog out of the flow on iOS only.

[latekvo]

This row — plus the gotcha at line 84, the closing note at line 93, and the permission describe-string in index.ts — attributes camera availability to "the installed Xcode's simctl", but the implementation comment (platforms/ios.ts lines 28-35) states support varies by simruntime, independent of whether the Xcode's simctl privacy usage text lists it. That is also the observed behavior: on Xcode 16.4 (and 26.5 per the earlier review round) the usage text omits camera while camera grants succeed. An agent following this wording will blame or switch the Xcode install, or treat the usage listing as authoritative — the error hint in ios.ts points at that same listing — when the actual variable is the target simulator's runtime.

[latekvo]

"Always" isn't true: the hint is deliberately suppressed when the camera failure is a shutdown-simulator error (platforms/ios.ts gates it on !shutdownHint, pinned by the "camera failure on a shutdown simulator" test). The closing note at line 93 has the same problem in a worse spot — it sits right after a failure list that includes "a shutdown simulator (iOS)" and still says a camera failure "additionally hints".

[latekvo]

"Reach for the argent-settings-permissions tool" names the skill, not the tool — the tool id is settings-permissions (the sentence's own closing reference, "See the argent-settings-permissions skill", uses the name correctly). An agent searching its tool list for argent-settings-permissions finds nothing.

[latekvo]

The interface contract above (lines 80-88) reserves false for a definitive "not installed" and undefined for "the probe couldn't answer", but this catch routes only the shutdown shape to undefined — every other probe failure becomes a definitive verdict. Two shapes that aren't verdicts land here: a nonexistent/stale UDID (get_app_container fails with "Invalid device", and device resolution is shape-based, so a deleted sim's UDID reaches this path) and a probe timeout (killed, no "current state" text — a wedged CoreSimulator). Both produce "the app is not installed — install the app first, then grant" for a question the probe never answered. Verified end-to-end: on a random UUID, grant location reports the app isn't installed while grant microphone on the same UUID correctly surfaces simctl's "Invalid device". No false success — the call fails either way — but the steer is wrong in exactly the confidently-wrong-diagnosis way the guard exists to avoid.

[latekvo]

This nets the four device-state patterns plus the timeout kind, but adb's client↔daemon leg fails with shapes that match neither: adb: protocol fault (couldn't read status): Connection reset by peer (an adb server restarting mid-command — a real event on hosts running mixed adb versions, where a version-mismatched client kills and restarts the shared server) and adb: cannot connect to daemon at tcp:...: Connection refused. Both classify as error_kind: "subprocess" and match no terminal pattern (verified against the built adbShell with a redirected ADB_SERVER_SOCKET), so they fold into the per-permission failure shape: a one-call blip mid-fan-out puts the lost permission into skipped under a success result — a deny whose revoke never executed reports success — and a daemon that stays down after the preflight produces the "every mapped runtime permission was rejected... manifest" aggregate, with the transport cause surviving only inside the parenthesized detail. The same failure at the preflight (line 166) propagates with adb's own classification, and the comment above (lines 80-84) defines "the adb transport itself failed" as exactly the category that must propagate — the daemon leg is in that category but escapes the net.

[latekvo]

This range is under-inclusive (it inherited the round-3 review comment's own phrasing): FLAG_PERMISSION_USER_FIXED exists since API 23 — it is what the checkbox-era "Don't ask again" sets on 23-29; API 30 only made it automatic after the second deny — and the flag-clear subcommand is absent everywhere below 33. So reset cannot clear a user-fixed state on API 23-32, not just 29-32; as written here and in the SKILL gotcha it implies sub-29 devices are unaffected. The capability matrix declares no Android version floor, so those levels are in scope.

[latekvo]

The remote branch this PR also adds can't keep this promise: sim-remote has no app-container verb, so the remote backend omits the install probe, and a pre-install grant location on a sim-remote target returns applied: ["location"] — the false success this sentence says the tool prevents. The exemption is stated only in code comments; neither this doc nor the tool description scopes the check to local simulators, and the only remote-path test grants microphone, so nothing exercises the remote guard-skip.

[latekvo]

"deny/reset clear both" is stronger than the implementation guarantees: photos-add is deliberately best-effort — a secondary-service failure is skipped silently, it does not appear in the result's skipped (which types.ts pins as Android-only), and types.ts's applied doc still describes fan-out as an Android-only phenomenon. When the second call fails, the result is a success whose applied lists only photos — consistent with the code's stated best-effort intent, but not with this row's unconditional wording.