Docs/SDK/Permissions

Permissions

Avoid browser permission bubbles (outside the DOM and invisible to snapshots) by setting a policy at startup, and applying explicit permission changes mid-run when supported.

This guide covers:

Startup policy: clear or pre-grant permissions before any navigation
Mid-run tools: grant/clear permissions and set geolocation through the Tool Registry
Safety: how to keep permission changes explicit and auditable in traces

Treat permissions as part of verification.

Permission prompts are not actionable UI. Prefer a startup policy and explicit mid-run tools so your trace shows what you granted, when, and why.

What problem this solves
Startup: PermissionPolicy
Mid-run: permission tools
Examples
Troubleshooting

What problem this solves

On Chrome (and Chromium-based browsers), site permission prompts (geolocation, notifications, etc.) are often native browser UI. They are:

Not in the DOM
Not in snapshots
Not reliably dismissible with normal click/type primitives

If your agent “hangs” at a permission prompt, it’s usually because it can’t see or reason about it. The fix is to treat permissions as context configuration.

Startup: `PermissionPolicy`

PermissionPolicy is applied when the browser context is created — before any navigation.

Field	Meaning
`default`	Default behavior on context creation: `"clear"`, `"deny"`, or `"grant"`. (`"clear"`/`"deny"` clears existing permissions; `"grant"` keeps defaults and lets `autoGrant` add more.)
`autoGrant` / `auto_grant`	Permissions to grant up front (e.g., `["geolocation"]`).
`geolocation`	Optional geolocation to set on the browser context.
`origin`	Optional origin scope for permission grants (when supported).

Mid-run: permission tools

When you’re using the Tool Registry, you can change permissions explicitly as part of a step.

Tool	What it does
`grant_permissions`	Grant one or more permissions for the current context.
`clear_permissions`	Clear permissions for the current context.
`set_geolocation`	Set geolocation on the current context (lat/lng, optional accuracy).

Examples

Startup policy (recommended)

from predicate import PredicateBrowser, PermissionPolicy

policy = PermissionPolicy(
    default="clear",
    auto_grant=["geolocation", "notifications"],
    geolocation={"latitude": 37.7749, "longitude": -122.4194},
)

browser = PredicateBrowser(permission_policy=policy)
browser.start()

Mid-run tools (explicit + traceable)

from predicate.tools import ToolRegistry, ToolContext, register_default_tools

registry = ToolRegistry()
register_default_tools(registry, runtime)

ctx = ToolContext(runtime)

await registry.execute("grant_permissions", {"permissions": ["geolocation"]}, ctx=ctx)
await registry.execute("set_geolocation", {"latitude": 37.77, "longitude": -122.41}, ctx=ctx)

Troubleshooting

I still see a Chrome permission prompt:
- Ensure you applied PermissionPolicy before navigation (context creation time).
- If you’re creating new contexts/pages mid-run, ensure the policy is applied to that context too.
Tools throw “not supported”:
- Some backends do not support permission manipulation. Keep permission changes explicit and surface unsupported capability errors early.

Agent Runtime — verification loop
Tool Registry — typed tools (including permission tools)
Browser Setup — context configuration