Which Guardrail Actually Stopped the Agent?

Use Claude Code hooks to record action decisions, scoped GitHub App permissions to bound repository access, and redacted rehearsal receipts to verify which layer denied each action.

Demand a receipt from the enforcing layer

Give each fixture action an ID and correlate the hook decision, the worker result, and any downstream receipt under that ID. Claude Code exposes tool events and passes structured context when a matcher fires, so a hook handler can record which policy rule it applied. Pair a harmless fixture read that must succeed with a request for a synthetic resource that must be denied. Run both through the intended worker identity and tool route. If the allowed read fails, fix the fixture before interpreting the denial. If the hook records a denial but a downstream receipt shows success, freeze the rollout and inspect the conflicting records. Keep payloads and credentials out of the event record. A useful receipt contains the case ID, route, enforcing layer, and outcome, plus a policy revision in the surrounding run record.

Hooks reference - Claude Code Docs

Check application policy and repository grants independently

For an organization integration, start with a GitHub App and document the repositories and permissions its installation actually grants. A successful edit to an allowed fixture repository establishes that the integration can do its job. Use an administrator-approved fixture and a read-only permission rehearsal to gather a separate service-side denial. At the application layer, replay a synthetic write intent through the policy handler with downstream execution stubbed. The two checks answer different questions. The first measures the service grant on the tested identity and route. The second shows how the application treats that intent. A handler decision with the expected outcome can still leave the repository grant unverified. Record the grant snapshot and policy revision together so the operator can tell exactly which combination was rehearsed before changing either one.

Managing your personal access tokens - GitHub Docs

Choose where tool calls execute

Cursor-hosted Cloud Agents run in isolated cloud VMs. Cursor Self-Hosted Machines execute tool calls on hardware you control, while the agent loop still runs in Cursor's cloud. If your policy requires local checkouts and tool execution, check the self-hosted option against those requirements. If it also requires the agent loop to stay inside your perimeter, that configuration fails the loop requirement.

Prepare a disposable worker and give it the same mounts, network policy, and tool access proposed for the pilot. Put a harmless marker file in a test location the worker must leave unreadable and a second file in the permitted workspace. Confirm the worker can read the permitted file and cannot retrieve the marker. Run the test through the same agent entry point operators will use and check the result independently of the agent's summary.

Choose where Cloud Agents run | Cursor Docs

Check that a hook sees the action

Claude Code provides PreToolUse and PostToolUse events and passes JSON context to a hook handler when the event fires and its matcher matches. Use PreToolUse to inspect the supported tool paths where you need an early decision. Check the event's documented matcher and decision format for your installed version before relying on the hook to block a request.

In a disposable repository, attempt one permitted edit and one edit to a protected fixture. Check that the permitted edit succeeds, the denied request produces the expected hook record, and the fixture's contents stay intact. If the fixture changes and the hook log is empty, inspect the loaded configuration and matcher coverage. If the hook records a denial and the fixture still changes, inspect other enabled tool paths and enforce the file restriction at the filesystem boundary.

Hooks reference - Claude Code Docs

Rehearse the first branch push

GitHub recommends a GitHub App for long-lived integrations. In an illustrative rehearsal, install the pilot app on one disposable private repository and give its worker the permission needed to push task branches there. Use a second private repository outside the installation and seed both with dummy files. Set the target repository's default branch to require the intended review and checks, then use the exact worker identity that would run unattended.

Run a harmless patch and verify three outcomes from the remote side: the task branch receives the expected commit, the worker cannot fetch the second private repository, and a direct push to the default branch is rejected. Inspect the branch tips yourself. If either negative test unexpectedly succeeds, keep push access disabled and examine the installation's repository access, any additional credentials available to the worker, and the branch rules.

Managing your personal access tokens - GitHub Docs

Fix blocked setup without widening access

Cloudflare's documented OpenCode sandbox setup sends model requests through AI Gateway and describes a sandbox that can reach the gateway and github.com. If your pilot needs dependencies from another host, determine whether the failure occurs during package retrieval, model access, or the test itself. A failure during package retrieval gives you no result on the patch's correctness.

Use a clean worker and try supplying the locked dependencies in its prepared image. Repeat the task and confirm both that the tests run and that a request to a disallowed test endpoint still fails. Baking dependencies into the image adds rebuild work when lockfiles change. If that overhead is unacceptable, evaluate an execution setup that supports narrowly scoped access to your approved package mirror and repeat the same checks there.

Run OpenCode in a sandbox · Cloudflare Sandboxes docs

Sources