What Is the Two-Call Audit Gate in SwarmForge?

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 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 (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 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 (lines 51–61): Defines the protocol specification establishing that git handoffs must use the audit gate mechanism.
• 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 (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:

# 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:

# 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) must follow this exact format:

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 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 and 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 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, 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}