> ## Documentation Index > Fetch the complete documentation index at: https://docs.ironbee.ai/llms.txt > Use this file to discover all available pages before exploring further. # How Verification Works > The completion gate, verification cycles, verdicts, and retries what happens when your agent finishes a task. IronBee's core idea is simple: **code isn't done until it's verified.** This page explains the mechanism behind that: how IronBee intercepts task completion, what the agent has to do to pass, and what happens when it doesn't. *** ## The completion gate When you run `ironbee install`, IronBee registers a **completion hook** with your AI client (the `Stop` hook in Claude Code and Codex, the `stop` hook in Cursor). It fires when the agent tries to finish a task. If the agent changed code files, the hook runs verification before letting the task complete: ```mermaid theme={null} flowchart TD A[Agent edits code] --> B[Agent tries to finish] B --> C{IronBee completion gate} C -->|all active cycles pass| D([Task completes]) C -->|any cycle fails| E[Agent fixes the issues] E --> B ``` If no code files changed (docs, config, etc.), the gate doesn't trigger. *** ## Verification cycles A **cycle** is one pass of testing against a real surface. IronBee has six, and any combination can be active for a project: | Cycle | Exercises the change through… | | -------- | --------------------------------------------------------------------------------------------- | | Browser | A real browser, navigation, screenshots, console, accessibility | | Node | The Node.js V8 inspector, probes, runtime snapshots, and outbound HTTP capture | | Python | A running Python process over debugpy/DAP, probes, thread dumps, and outbound HTTP capture | | Backend | Real protocol calls HTTP, gRPC, GraphQL, WebSocket | | Android | An emulator over ADB taps, swipes, screenshots, UI snapshots, Logcat, HTTP capture | | Terminal | A pseudo-terminal (PTY) spawn the CLI / REPL / TUI, send input, capture output and exit codes | When a task completes, **every active cycle whose patterns match the changed files must pass in the same verification attempt**. They run in parallel, not one task at a time. See [Verification](/cli/guides/verification) for choosing which cycles are active. *** ## The verdict To pass a cycle, the agent exercises the affected paths with that cycle's tools and submits a **verdict**, its assessment of whether the change works: ```json theme={null} { "status": "pass", "checks": [ ... ], "issues": [ ... ], "fixes": [ ... ] } ``` IronBee doesn't take `status: "pass"` at face value. Each cycle defines the tools that must appear on the wire before a pass counts: required tools (all-of) and alternative evidence paths (any-of). If the agent claims success without actually using the tools, the gate overrides the verdict to **fail**. This is what stops an agent from declaring "it works" without testing. *** ## Retries A failed verdict sends the agent back to fix the issues and verify again. The [`maxRetries`](/cli/configuration/configuration#core-options) limit (default **3**) caps this loop: once it's hit, the agent is allowed to complete the task **but must report the unresolved issues** rather than silently pass. One counter covers all active cycles. *** ## Who drives the tools On **Claude Code** and **Codex**, the main agent doesn't run the devtools tools itself — it **delegates to a dedicated `ironbee-verifier` sub-agent** that owns them. This keeps the heavy devtools output (DOM, console, screenshots) out of the main conversation while still recording everything to the same session. **Cursor** has no sub-agent surface, so its main agent verifies directly. See [Verification → How verification runs](/cli/guides/verification#how-verification-runs-the-verifier-sub-agent). *** ## Default vs custom scenarios By default the gate verifies only the areas affected by what changed. You (or the agent) can instead pass a **custom scenario** to [`/ironbee-verify`](/cli/clients/claude-code#slash-commands) — inline text or a path to a scenario file — to specify exactly which flows, states, and endpoints to exercise. See [Custom verification scenarios](/cli/guides/verification#custom-verification-scenarios). *** ## Enforce, assist, and monitoring-only The blocking gate described above is **enforce mode**. It's one of three [verification modes](/cli/guides/verification#verification-modes), and it's **opt-in** — a fresh install defaults to **assist**: * **Assist** *(default)* (`ironbee verification auto disable`) - the `/ironbee-verify` command, the verifier sub-agent, and the devtools MCP server stay installed so the agent (or you) can verify on demand, but no gate ever blocks completion. Every manual cycle is still recorded to the Collector. Turn on full enforcement with `ironbee verification auto enable`. * **Monitoring-only** (`ironbee verification disable`) - none of the machinery is installed. The agent works unblocked, but session lifecycle, tool calls, and timing still flow to the Collector. Useful for measuring baseline behavior before turning verification on. *** ## Area-specific guidance Teams can steer *how* the agent verifies a given part of the codebase by committing [`.ironbee/VERIFICATION.md`](/cli/guides/verification-context) files. When a change touches that area, IronBee injects the matching guidance into the agent's context as it starts verifying: advisory instructions layered on top of the standard flow, resolved hierarchically from the changed paths. *** ## Session isolation Every agent task runs as its own **session**, tracked independently in a per-session `sessions//` directory (by default under `~/.ironbee/projects//`, outside the project tree — see [Runtime files](/cli/advanced/runtime-files#where-per-session-data-lives)). Concurrent sessions, even in the same project, keep separate event logs, verdicts, and retry counters, so they never interfere. See [Runtime files](/cli/advanced/runtime-files) for what's stored per session. *** ## What's next? Install, remove, track, and update IronBee across your projects. Choose which cycles run and how enforcement behaves.