# How SwarmForge Handles Agent Conflicts: Detection, Resolution & Escalation

> Learn how SwarmForge handles agent conflicts with Git merge detection, delegate resolution, and operator escalation. Understand the conflict resolution process.

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

---

**SwarmForge resolves agent conflicts through Git merge detection, delegate resolution to the receiving agent, and operator escalation for semantic conflicts.**

Parallel agents in multi-agent systems inevitably clash when modifying shared files. The SwarmForge orchestration framework treats conflicts as expected outcomes rather than failures, routing all coordination through a **handoff daemon** that enforces Git-based conflict detection and human escalation protocols. This article examines the exact mechanics of conflict handling in the `unclebob/swarm-forge` repository.

---

## Conflict Detection via Git Merge Monitoring

SwarmForge never permits agents to directly manipulate tmux sockets or repositories. Instead, the `handoff daemon` serializes all coordination through Git handoffs. When two parallel agents modify overlapping files, the receiving agent's helper scripts surface the conflict through **explicit merge failure detection**.

In `swarmforge/scripts/swarmforge.bb` (lines 33–34), the launcher codifies this policy:

> *"If [`merge_and_process.sh`](https://github.com/unclebob/swarm-forge/blob/main/merge_and_process.sh) or `ready_for_next` reports a merge conflict, resolve the conflicted files, git add, and commit. **Do not invent git merge**."*

The helper scripts [`merge_and_process.sh`](https://github.com/unclebob/swarm-forge/blob/main/merge_and_process.sh) and [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) execute `git merge` and monitor exit status. A non-zero exit signals conflict—**no automatic merging is attempted**. The conflict propagates to the agent runtime for manual resolution.

```bash

# ready_for_next.sh – generic receiver that surfaces conflicts

#!/usr/bin/env bash
set -euo pipefail

# …fetch handoff, apply it…

if ! git merge "$COMMIT"; then
  echo "Merge conflict – ask operator"
  pack_dashboard_request.sh clarify ./tmp/conflict-question.txt
fi

```

---

## Agent-Led Resolution Workflow

The receiving agent bears full responsibility for conflict resolution. This mirrors standard Git workflows and ensures single-source-of-truth integrity:

1. **Inspect** conflict markers in affected files
2. **Edit** to resolve overlapping changes
3. **Stage** resolved files via `git add …`
4. **Commit** the resolution with descriptive message

The resolution commit becomes part of the permanent handoff chain, visible to downstream agents.

```clojure
;; Example: agent handling incoming handoff with merge conflict
(defn handle-incoming-handoff [ctx handoff]
  (let [{:keys [commit]} handoff]
    (sh "git" "checkout" commit)               ; apply incoming commit
    (let [{:keys [exit out err]} (sh "git" "merge" "HEAD")]
      (if (zero? exit)
        (println "Merge succeeded")
        (do
          (println "Merge conflict detected – resolving")
          ;; Resolve manually then:
          (sh "git" "add" ".")
          (sh "git" "commit" "-m" "Resolved conflict from handoff")
          (println "Conflict resolved and committed"))))))

```

---

## Operator Escalation for Semantic Conflicts

**Syntactic merges** (overlapping file edits) resolve through Git. **Semantic conflicts**—contradictory requirements, ambiguous specifications, or test failures—require human judgment.

As specified in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) (lines 96–99):

> *"When blocked by ambiguity, contradiction, or test/specification conflict, an agent should ask the operator."*

Agents invoke [`pack_dashboard_request.sh`](https://github.com/unclebob/swarm-forge/blob/main/pack_dashboard_request.sh) to submit clarification requests through the dashboard UI. The system pauses until operator response arrives, preventing autonomous resolution of ambiguous requirements.

---

## Audit Trail and Chain Forwarding

Every handoff—including conflict resolutions—generates immutable records in `.swarmforge/handoffs/`. The daemon:

- Copies handoffs to each recipient's inbox
- Logs resolution events with timestamps
- Enforces **chain forwarding** so downstream agents receive resolved states

The SwarmForge constitution mandates that *intermediate roles always forward a `git_handoff`* after completing work, even for metadata-only changes ([`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md), lines 60–66). This guarantees propagation of conflict resolutions through the agent pipeline.

---

## Key Source Files

| File Path | Purpose |
|-----------|---------|
| `swarmforge/scripts/swarmforge.bb` | Core launcher defining conflict-handling policy (line 33–34) |
| [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Full handoff daemon specification, escalation rules, and audit logging |
| `swarmforge/constitution/articles/handoffs.prompt` | Governance of note handoffs vs. operator escalation |
| [`scripts/merge_and_process.sh`](https://github.com/unclebob/swarm-forge/blob/main/scripts/merge_and_process.sh) | Merge execution and conflict reporting |
| [`scripts/ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/scripts/ready_for_next.sh) | Generic receive script with conflict detection |

---

## Summary

- **Conflict detection** relies on `git merge` exit status in helper scripts—no automatic merging occurs
- **Resolution responsibility** falls to the receiving agent through standard Git workflows
- **Operator escalation** handles semantic conflicts via dashboard requests per the handoff protocol
- **Audit logging** persists all handoffs in `.swarmforge/handoffs/` with full chain forwarding
- **Constitutional rules** enforce git_handoff propagation to maintain resolved state visibility

---

## Frequently Asked Questions

### What triggers a conflict in SwarmForge?

Parallel agents modifying overlapping files in the same worktree trigger Git merge conflicts when the receiving agent attempts to integrate the incoming handoff. The [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) and [`merge_and_process.sh`](https://github.com/unclebob/swarm-forge/blob/main/merge_and_process.sh) scripts detect this through non-zero `git merge` exit codes.

### Can agents automatically resolve merge conflicts?

No. The launcher explicitly prohibits autonomous merging with the directive **"Do not invent git merge"**. Agents must manually inspect conflict markers, edit files, stage with `git add`, and commit the resolution.

### How does SwarmForge handle contradictory requirements?

Semantic conflicts—ambiguous specs, contradictory requirements, or test failures—trigger operator escalation. Agents submit dashboard requests via [`pack_dashboard_request.sh`](https://github.com/unclebob/swarm-forge/blob/main/pack_dashboard_request.sh) and await human clarification rather than choosing autonomous resolutions.

### Where are conflict resolutions recorded?

All handoffs including conflict resolutions are stored in `.swarmforge/handoffs/`, copied to recipient inboxes, and logged by the handoff daemon. This provides reproducible audit trails of who resolved what and when.