Bounded agent execution: how Hunt lets a coding agent investigate without owning the keys

The controls that let Codex, Claude Code, or OpenCode plan a security investigation inside ShakerScan: target binding, one registry entry per capability, reserved budgets, expiring approvals, server-side credentials, and a proof boundary the agent cannot cross.

Summary

Hunt gives an external coding agent the planning role in a security investigation without giving it the keys. The agent proposes; ShakerScan decides whether an action is allowed, executes it under target binding and budgets, keeps credentials server-side, and records evidence. The agent can create candidates and notes, but only deterministic proof contracts can mark a finding verified. This article walks through the controls as the repository documents them at v2.3.1, and states what is verified and what is still pending.

Problem

docs/hunt-architecture.md frames the goal as "Human judgment + AI reasoning + deterministic execution and proof." The human owns scope, objectives, and final judgment; the AI observes, hypothesizes, and proposes; ShakerScan provides "the controlled execution environment, target memory, tools, evidence, and verification." An agent that adapts is only useful if its actions are bounded and its claims are checkable.

How it works

The boundaries are written as numbered invariants in AGENTS.md. The ones that shape Hunt:

No shell. Invariant 3: "Do not expose arbitrary shell commands or planner-supplied argv as capabilities."
Every network action is bound. Invariant 4: "Every network action uses runtime target binding and scope/destination validation."
One registry entry per capability. Invariant 5: each executable capability has "one canonical registry entry declaring risk, budgets, placement, parser/output schema, and evidence contract."
Budgets are reserved first. Invariant 6: "Reserve multidimensional budget before execution and reconcile actual use afterward."
AI is not proof. Invariant 7: "AI may create notes, observations, and evidence-backed candidates; only deterministic proof contracts may mark findings verified."
Strategy is the agent's; safety is the server's. Invariant 8: "Adaptive strategy belongs in Hunt skills or the external planner. Safety, protocol, evidence, and correctness stay server-side."
Partial output survives timeouts. Invariant 9, with cancellation kept distinct.

On top of the invariants, the README and product model record the operational controls:

Hunt requires explicit confirmation that the target is owned or authorized and "a target-bound, expiring approval."
Every Hunt "retains hard ceilings for capability calls, requests, active actions, wall time, ports, hosts, browser actions, device fragility, and candidates."
"ShakerScan keeps credentials server-side, enforces turn/request/action ceilings, blocks arbitrary write methods in the free-form loop, and promotes a Suspected finding to Verified only through deterministic proof."
The 31-entry web-testing methodology catalog "stays server-side instead of occupying the planner context. A Hunt receives at most three compact suggestions, then loads and binds one relevant method", and "no methodology can alter target or approval authority."
The record export "includes explicit capability decisions and the final debrief, never hidden model chain-of-thought."
An administrator can disable every gated AI execution path with AI_OPS_ROUTER_EXECUTE_ENABLED=false.

The review surface is read-only by design. docs/hunt-review-integrity.md: the investigation review panel "cannot propose, approve, execute, or promote anything," and the graph query "exposes allowlisted UUIDs, digests, and enums for authorization records, not arbitrary graph attributes or raw request content."

The proof boundary

docs/hunt-architecture.md calls this "a hard invariant": "AI reasoning creates a candidate. Verification requires deterministic evidence: a boolean/time differential, a controlled-mutation database error, sqlmap proof for injection; a genuine cross-principal comparison for BOLA (not merely HTTP 200)."

AGENTS.md adds the write rules: Hunt "may create/update/delete only its own evidence-linked unverified findings, citing same-Hunt completed/partial evidence. It cannot set proof, verification, target, raw request/response, or ownership fields, or modify findings with verification history." And: "Confidence, AI judgment, labels, or successful HTTP status are not deterministic proof."

The same document keeps the exposure proof set deliberately narrow, which is why an agent's "this looks like a secret" stays an observation until a content contract confirms it.

What is verified, and what is pending

The proof boundary is described as "already enforced" at the current state: "Hunt creates only unverified candidates; verification runs through the deterministic proof moat."
A CI job named Hunt record integrity runs the focused Python tests, "a disposable real PostgreSQL locking and rollback test, UI unit tests, and a UI build." Candidate materialization locks the proposal row and commits the candidate, observation, and link together; a failed link write rolls the candidate back.
Pending: the record-integrity checks "do not run an offensive workload or establish live worker, browser workflow, multi-model, or paired human-productivity acceptance." Efficacy is governed by the separate evaluation protocol, and at this tag no verified Hunt-only finding is recorded (see why Hunt added zero classes on Juice Shop).

Limitations

Data handling for the reasoning side depends on the coding agent and model provider the operator configures. ShakerScan stores no separate LLM key for Hunt, but prompts and redacted target context do reach the configured agent.
Exports are operator-trusted; the offline scorer "does not authenticate edited files or execute verification."
Budgets bound work; they do not bound the wall clock of a human review. Full-reservation charges are reported as upper bounds, separately from measured traffic.
The two positive leads and one no-lead control recorded as live acceptance are "not a human-productivity study or verified recall gain."

Product implications

The Hunt product page states the boundaries in the same terms: scope, capabilities, approvals, budgets, execution, and evidence stay with ShakerScan.
Because the agent cannot cross the proof boundary, a Hunt finding marked Verified carries the same deterministic evidence as a Scan finding. Reviewers can treat the proof state, not the source, as the thing to trust.
The kill switch and the read-only review panel are the two controls an operator should know before enabling Hunt in a shared environment.

References

Sources are quoted from the open-source repository at the tag named above. When a document and the implementation disagree, the code, schema, and tests at that tag are authoritative. Only test systems you own or are explicitly authorized to assess.