Skip to content
ShieldedShell

Dual-agent loop

The dual-agent loop runs two roles in alternation:

  1. Developer — drafts code into developer_output.json
  2. Auditor — reviews and records kill criteria in auditor_output.json
  3. Reconciler — validates JSON, runs static checks, merges approved code when gates pass

Shared state lives in shared_context.txt and JSON buffer files in the workspace.

Run with an engine

Section titled “Run with an engine”

Install an agent CLI and confirm with shieldedshell doctor, then:

Terminal window
shieldedshell loop --engine cline --benchmark 02_ledger_consensus --dir .

Other engines use the same pattern:

Terminal window
shieldedshell loop --engine claude --benchmark 02_ledger_consensus --dir .
shieldedshell loop --engine aider --benchmark 02_ledger_consensus --dir .
shieldedshell loop --engine openhands --benchmark 02_ledger_consensus --dir .

See Agent engines for setup per CLI.

Explicit commands (no engine profile)

Section titled “Explicit commands (no engine profile)”

Bring your own scripts:

Terminal window
shieldedshell orchestrate \
  --dev "node ./agents/dev.mjs" \
  --audit "node ./agents/audit.mjs" \
  --benchmark 02_ledger_consensus \
  --dir ./my-project

Workspace files

Section titled “Workspace files”
FileRole
shared_context.txtTask header and loop status
developer_output.jsonDeveloper JSON (code, explanation, query)
auditor_output.jsonAuditor JSON (verdict, kill criteria)
auth_service.js (or --target)Merge target when reconciler approves

shieldedshell init creates empty buffers if missing.

Phase locks

Section titled “Phase locks”

During each agent turn, ShieldedShell locks files the active role must not write (for example the auditor cannot edit developer_output.json mid-turn). This reduces cross-contamination between roles.

Reconciler gate

Section titled “Reconciler gate”

After each iteration the reconciler:

  • Parses agent JSON output
  • Runs syntax and static verification (benchmark-specific when --benchmark is set)
  • Merges approved code into the target file on success
  • Appends status to shared_context.txt

Loop exits on CRITICAL_SUCCESS or after auto_heal.max_retry_cycles (default 5).

Benchmark secrets

Section titled “Benchmark secrets”

Benchmarks may expose role-specific secrets only during the matching phase (for example auditor-only fixture data). Secrets are hidden again after the turn.

Timeouts

Section titled “Timeouts”

Agent CLI runs use a minimum 15-minute orchestrator timeout so slow LLM turns are not killed at the default 5-minute sandbox limit. Per-engine flags (for example Cline -t 900) are set from engine profiles.

Section titled “Related”