# What Is the Two-Call Audit Gate in SwarmForge?

> Understand the two-call audit gate in SwarmForge. Discover how this verification process prevents incomplete commits by requiring dual submission and confirmation for every git handoff.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: deep-dive
- Published: 2026-08-31

---

**The two-call audit gate in SwarmForge is a mandatory verification checkpoint that requires every git handoff to be submitted twice—first triggering an audit challenge, then confirming the submission—to prevent incomplete or accidental commits from propagating through the agent swarm.**

SwarmForge, available in the `unclebob/swarm-forge` repository, is an open-source framework for orchestrating multi-agent workflows through structured handoffs. According to the protocol definitions in the codebase, the **two-call audit gate** acts as a lightweight safety mechanism that forces sending agents to double-check their work before it enters the outbox and reaches the next recipient.

## How the Two-Call Audit Gate Works

Every git handoff in SwarmForge must pass through two distinct phases before the sender’s task card can advance to the next stage.

### Step 1: Triggering the Audit Challenge

When an agent invokes [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) with a `git_handoff` draft, the script performs strict syntactic validation. It verifies that all required fields are present and that the `commit` field contains exactly 10 hexadecimal characters resolving to a single, valid commit object.

If the draft passes validation, the script **does not** queue the handoff. Instead, according to [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) (lines 51–61), it executes the following:

- Records the candidate under `.swarmforge/handoffs/audit_pending/`
- Prints the token `AUDIT_REQUIRED` to standard output
- Increments the task card’s cumulative audit counter

This first call deliberately blocks progression to enforce a mandatory review pause.

### Step 2: Confirming the Audited Handoff

Before the second submission, the sender must re-read the complete inbound payload and verify that every requirement, constraint, and boundary condition has been satisfied. The sender then repeats the **identical** command, using the same `git_handoff` draft, `task`, `recipient`, and commit SHA.

If [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) detects that the second call matches the pending audit entry exactly, it treats the submission as verified, queues the handoff file into the outbox, and clears the audit challenge. If any element—including whitespace or field ordering—has changed, the script issues a new audit challenge and increments the counter again, requiring a third identical call to confirm.

## Safety Guarantees and Accountability Features

The two-call pattern serves three critical functions within the SwarmForge architecture:

- **Prevents Accidental Propagation**: The forced pause between calls creates a natural breakpoint where senders can catch incomplete work before it reaches downstream agents.
- **Maintains Audit Trails**: The cumulative audit counter appears directly on the sender’s task card, providing visible history of how many verification cycles a handoff required before acceptance.
- **Enables Human Review**: The gap between calls creates an explicit intervention point where human reviewers or automated analysis tools can inspect the pending file in `.swarmforge/handoffs/audit_pending/` before the handoff enters the active queue.

## Implementation Details and File Structure

The audit gate logic is distributed across three key locations in the `unclebob/swarm-forge` repository:

- **[`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md)** (lines 51–61): Defines the protocol specification establishing that git handoffs must use the audit gate mechanism.
- **[`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh)**: Implements the runtime validation logic, including the `AUDIT_REQUIRED` token generation and the bitwise comparison logic for detecting unchanged second calls.
- **[`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md)** (line 273): References the audit gate requirement, noting that "Git handoffs use the audit gate described below."

## Example Workflow

The following shell commands demonstrate the complete two-call sequence using a typical git handoff draft:

```sh

# 1️⃣ First attempt – triggers audit challenge

swarm_handoff.sh ./tmp/handoff.txt

# Output: AUDIT_REQUIRED

```

After verifying the commit integrity and requirements, the sender executes the identical command:

```sh

# 2️⃣ Second attempt with unchanged draft – clears audit and queues handoff

swarm_handoff.sh ./tmp/handoff.txt

# Handoff is now queued in the outbox; no audit message

```

A valid handoff draft ([`./tmp/handoff.txt`](https://github.com/unclebob/swarm-forge/blob/main/./tmp/handoff.txt)) must follow this exact format:

```text
type: git_handoff
to: cleaner
priority: 50
task: add-user-service
commit: 1a2b3c4d5e

```

Note that the `commit` field must contain exactly 10 hexadecimal characters that resolve unambiguously to a single commit object; this is validated during the first call.

## Summary

- The **two-call audit gate** requires every git handoff to be submitted twice to [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) before the handoff is queued in the outbox.
- The first call validates syntax and stores a pending audit under `.swarmforge/handoffs/audit_pending/`, returning the token `AUDIT_REQUIRED`.
- The second call must be identical to the first; only then does the script clear the audit and move the handoff to the outbox.
- This mechanism provides safety checks, audit trail counters on task cards, and intervention points for human reviewers or automated tools.
- The implementation resides primarily in [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) and [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) within the `unclebob/swarm-forge` repository.

## Frequently Asked Questions

### What happens if I modify the handoff draft between the first and second call?

If any field—including the commit SHA, recipient, task name, or priority—differs between the two calls, [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) treats the second attempt as a new submission. It creates a fresh audit challenge in `.swarmforge/handoffs/audit_pending/` and increments the audit counter again, requiring you to confirm the modified version with a third identical call before queuing.

### Why does SwarmForge use two calls instead of a simple confirmation prompt?

The two-call pattern decouples the validation phase from the confirmation phase, enabling asynchronous review workflows. As implemented in `unclebob/swarm-forge`, this design supports both human reviewers and automated analysis tools that can inspect the pending audit file between calls, whereas an interactive prompt would block the terminal and prevent scripted automation.

### Where can I find the audit counter for a specific task card?

The cumulative audit counter is displayed directly on the sender’s task card interface. According to the protocol definition in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md), this counter increments every time an audit challenge is issued, providing a visible history of how many verification cycles were required before the handoff advanced.

### Is the two-call audit gate required for all types of handoffs in SwarmForge?

No, the audit gate applies specifically to **git handoffs** as documented in the README (line 273) and [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md). Other handoff types in the SwarmForge ecosystem may use different validation mechanisms, though git-based transfers require this specific two-phase verification to ensure commit integrity.