Technical Preview — 0.37.12. APIs, evidence formats, and deployment contracts may change before 1.0.

Quick start

Already use Codex? Run the same conversational TUI through Claim Plane.

Claim Plane does not replace Codex. It controls authority around the session: Codex explores and implements normally, while Claim Plane admits the task scope, requires explicit amendments for necessary scope growth, verifies the final Git diff, runs the configured acceptance checks after Codex exits, and seals the evidence.

1. Install the CLI

uv tool install claim-plane
# or: pipx install claim-plane

Claim Plane uses the Codex CLI already installed and authenticated on your machine.

2. Enroll a repository once

Run these commands from a Git feature branch:

cd my-project
git switch -c agent/my-task

claim-plane init
claim-plane connect codex
claim-plane doctor

doctor reports the actual adapter, sandbox, policy, and enforcement boundary before an agent starts changing files.

3. Work in Codex as usual

claim-plane codex --policy guarded

Then describe the task inside the normal Codex session:

Fix timeout handling and update the appropriate regression tests.

That is the default daily workflow. On later sessions in the same enrolled repository, claim-plane codex --policy guarded is normally the only command you need.

What happens around the session

You work with the normal Codex TUI
              ↓
Codex proposes a task-bound ChangeIntent before mutation
              ↓
Claim Plane admits the initial authority
              ↓
Necessary scope growth uses a recorded amendment instead of silent expansion
              ↓
Codex exits; Claim Plane verifies the real Git diff and runs acceptance
              ↓
DELIVERY VERIFIED, REJECTED, REVIEW REQUIRED, or another explicit outcome
              ↓
Durable report and replay evidence under .claim-plane/runs/

For normal use, omit --scope and let the task establish the initial authority. Supply an explicit starting boundary when reproducibility or review requires it:

claim-plane codex \
  --scope src/connectors/github.py \
  --policy guarded

A genuinely required additional file can pass through the brokered amendment path. Add --lock-scope only when every expansion must be forbidden.

Read the five-minute walkthrough, the explicit guarantees and trust boundaries, and the troubleshooting guide.

Why Claim Plane exists

A Git worktree isolates a process, but it does not prove that an agent stayed within the task, that every scope expansion was justified, or that a successful agent exit matches the final repository state. Claim Plane separates probabilistic planning from deterministic authority and verification.

It does not replace Git, an IDE, a planner, or a coding agent. Codex remains the interactive coding experience; Claim Plane is the control and evidence layer around it.

Task
  ↓
Planner emits ChangeIntent
  ↓
Agent Lexicon resolves canonical concepts
  ↓
Claim Plane performs atomic pre-write admission
  ↓
Workers execute in isolated worktrees
  ↓
Contract changes invalidate affected dependents
  ↓
Integration Verifier checks real Git hunks, contracts, policies, and acceptance
  ↓
Clean integration or targeted repair

claim-plane swarm plan <session-id>
claim-plane swarm admit <session-id>
claim-plane swarm scheduler <session-id>
claim-plane swarm provision-worktrees <session-id>
claim-plane swarm worktrees <session-id>
claim-plane swarm run-codex <session-id> --work-id <work-id>
claim-plane swarm merge-plan <session-id>
claim-plane swarm merge-next <session-id>
claim-plane swarm merge-queue <session-id>
claim-plane swarm runs <session-id>
claim-plane swarm recovery-status <session-id>
claim-plane swarm recover <session-id>
claim-plane swarm replace-codex <session-id> --work-id <work-id> --run-id <run-id>

Deterministic single-agent evidence

The current technical preview retains deterministic single-agent candidate and verdict binding. Every new controlled run seals the task, base and result repository states, change summary, effective policy, adapter contract, acceptance definition, and lifecycle head into one reproducible decision digest. Evidence reports recompute that binding and replay verifies equivalence without rerunning the provider.

Frozen OSS pilot

The repository includes a three-task real-repository pilot for the interactive Codex workflow. It prepares exact Jinja, Click, and dirty-equals repository states from a frozen CooperBench revision, runs each arm in an independent directory, and executes authoritative acceptance in an isolated temporary worktree. The evaluator uses the task-required agent_workspace layout, combines official tests with the candidate tree through a base-aware merge, and records classified failures with full logs under .claim-plane/oss-pilot/acceptance/.

claim-plane oss-pilot list
claim-plane oss-pilot prepare jinja-loader-local --arm guarded
claim-plane oss-pilot run jinja-loader-local --arm guarded --model gpt-5.6-luna
claim-plane oss-pilot status jinja-loader-local --arm guarded

See benchmark/oss-pilot/README.md for all three tasks, frozen inputs, and the comparative-arm layout.

Inspection friction hardening

The Codex guard accepts bounded read-only chains and pipelines when every stage can be proven non-mutating. Typical repository inspection remains concise without allowing shell redirection or unclassified executables to bypass resource authority.

git show --stat HEAD | head -20
rg -n "ChangeIntent" src tests | head -40
git diff --check; git status --short

claim-plane codex-intent status reports allowed compound inspections, pipelines, unclassified shell denials, and subsequent read-only recoveries. The same summary is bound into controlled-run evidence for comparative Bare, Observe, and Guarded runs.

Targeted test feedback and current verdict

During an admitted interactive task, Codex may run bounded targeted tests and common project-native test commands to repair its work. The project-configured full acceptance command remains reserved for Claim Plane and runs independently after the agent exits. Untracked test caches and build outputs are treated as managed artifacts; tracked source, configuration, snapshots, and golden files remain subject to normal authority checks.

OSS pilot re-verification is sealed to the current candidate digest. oss-pilot status, report, and replay keep the immutable delivery outcome separate from the latest acceptance recheck. A rejected delivery remains rejected even when its unchanged candidate later passes the evaluator; the candidate is labeled MATCHES_PASSING_ACCEPTANCE_RECHECK rather than being promoted to verified delivery.

Comparative single-agent validation

Version 0.37.9 turns the frozen OSS pilot and dogfood contracts into one operator workflow for fidelity-matched Bare Codex, Claim Plane Observe, and Claim Plane Guarded executions. The preview profile freezes 12 feature-level tasks across at least six repository families and expands them into a 36-cell matrix. The release profile freezes 20 tasks and two independent execution replicates.

claim-plane validation init --profile preview --model gpt-5.6-luna
claim-plane validation prefetch --next
claim-plane validation status
claim-plane validation run --next
claim-plane validation report
claim-plane validation bundle --out claim-plane-validation.zip

validation prefetch executes only the dependency-setup prefix of the frozen task evaluator, stops before official tests, and stores one task-level virtual environment. The same environment and download cache are activated for Bare, Observe, and Guarded, so Codex can run targeted tests against the project dependencies in every arm. Candidate source is rebound with an editable no-dependency install before each execution. Claim Plane also injects that environment into Codex shell tools with one-run shell_environment_policy overrides and disables login-shell profile rewriting for the validation session. Before opening Codex, it removes parent Python launcher redirects, verifies the exact virtual-environment prefix, imports pytest and top-level test dependencies, and checks the editable candidate import. Prepared site-packages are pinned into the one-run Codex PYTHONPATH, which keeps macOS framework and pyenv launchers from selecting the parent interpreter's package set.

Private pytest acceptance installs explicit evaluator-only prerequisites before the repository's initial conftest.py imports, then witnesses exact hidden node execution. Skipped or stale dependency-gated tests remain EVALUATOR_INCOMPLETE; preserved candidates can be resumed without rerunning Codex.

The comparative runner keeps frozen evaluator programs and hidden acceptance inputs in a private persistent vault outside the workspace tree. Agent-visible manifests contain only public task identity, while Codex web search and shell networking are disabled for the cell. Newly written session and run records are audited after Codex exits; detected reference-artifact access records the cell as CONTAMINATED and skips official acceptance. The agent-facing acceptance command resolves python from the prepared environment rather than embedding an absolute host interpreter.

Official Python acceptance is also witness-bound. Claim Plane derives the private pytest node IDs added or modified by the frozen test input and requires every node to be collected, executed, and passed. A skipped test, an uncollected node, a missing pytest session, or an optional dependency that cannot be installed produces EVALUATOR_INCOMPLETE, never PASS. The compact witness summary is sealed into the re-verification evidence and exported with the validation bundle. Candidate workspaces and shared development environments are stored outside the matrix directory, so a session cannot discover previous-arm candidates by traversing its ordinary parent directories.

Observe and Guarded defer their internal acceptance to the comparative runner. The external frozen evaluator therefore runs exactly once per cell, after the agent exits, and remains the sole authoritative task verdict.

Preview acceptance defaults to five minutes and streams evaluator output. Long silent phases emit elapsed-time heartbeats. Claim Plane stores the cell phase before Codex and before acceptance, so one interruption preserves the candidate and prints a resumable command:

claim-plane validation status
claim-plane validation resume <execution-id>

Timeouts and evaluator-environment failures keep the same candidate resumable and do not fill the comparative matrix with a false task verdict.

Candidates created by 0.37.0 are detected as LEGACY_CANDIDATE. Their measured agent time can be restored during the one-time recovery:

claim-plane validation resume <execution-id> --agent-seconds 178

Diagnostic cells produced before runtime-fidelity matching can be removed across all three arms while preserving the prepared dependency cache:

claim-plane validation reset-task <task-id>

validation run --next prepares the exact repository state, opens the selected Codex arm, runs the same isolated official evaluator after the agent exits, and binds measured scope, friction, timing, token, drift, and acceptance metrics to the immutable plan cell. Aggregation rejects missing, duplicate, unexpected, or mismatched cells instead of filling gaps.

See benchmark/single-agent-validation/README.md for the full workflow and release gate semantics.

Research paper

Claim Plane: Enforceable Change Intents and Dynamic Scope for Parallel Coding Agents
Maxim Nikolaev · Software Engineering (cs.SE) · 2026

• arXiv abstract
• PDF
• DOI: 10.48550/arXiv.2607.21909
• Paper metadata and citation
• Published six-pair CooperBench reproduction

Repository-level software citation metadata is available in CITATION.cff, and the paper-specific BibTeX entry is available in papers/claim-plane-2026/citation.bib.

More ways to run

Open the same interactive TUI with the first task already submitted:

claim-plane codex "Fix timeout handling and update its regression test" \
  --policy guarded

Run a bounded unattended task instead of an interactive session:

claim-plane run "Add pagination to the audit API and extend its tests" \
  --policy guarded

Inspect the latest durable evidence without reopening Codex:

claim-plane report latest
claim-plane replay latest

Inspect the installed product contract and packaged schemas:

claim-plane preview
claim-plane exit-codes
claim-plane schemas list

See upgrade and uninstall behavior before changing an existing installation.

Installation details

The quick-start installation is:

uv tool install claim-plane
# or: pipx install claim-plane

Optional semantic identity and evidence signing extras:

uv tool install "claim-plane[semantic,signing]"

Verify the installation and public CLI contract:

claim-plane --version
claim-plane preview
claim-plane exit-codes

For development from a checkout:

pip install -e ".[dev,signing]"

# Optional local Agent Lexicon checkout
pip install -e ../agent-lexicon

Run the complete checks, the focused interactive authority suite, and the example:

./scripts/check.sh
./scripts/check-interactive-safety.sh
./scripts/demo.sh

Adapter guarantees

Inspect the effective Codex capabilities before selecting an enforcement policy:

claim-plane adapters inspect codex --repo .
claim-plane adapters inspect codex --repo . --policy guarded
claim-plane doctor codex --repo . --policy strict

The manifest distinguishes HARD_BLOCKED, OBSERVED, POST_VERIFIED, and UNAVAILABLE behavior and identifies whether each guarantee comes from Claim Plane, the adapter, the runtime, or their composition. Policy compatibility fails closed when the selected level requires a guarantee that the current runtime boundary cannot provide. The manifest digest and effective adapter/runtime identity are included in normalized session evidence.

Run the shared compatibility suite without invoking a model provider:

claim-plane adapters conformance codex
claim-plane adapters conformance reference --out conformance.json

The same thirteen scenarios are applied to the dependency-free reference adapter and Codex. The report covers declared and undeclared mutations, atomic amendments, stale authority, lease expiry, idempotency, invalid event order, crash resume, cancellation, completion coverage, corrupt state, and secret redaction. Every available guarantee must map to passing scenarios; an uncovered or failed claim makes the report incompatible and returns a non-zero exit code.

Adapter registry

Discover available adapters, verify protocol compatibility, and pin the selected runtime before controlled work:

claim-plane adapters list --inspect
claim-plane adapters doctor codex --repo .
claim-plane adapters pin codex --repo .

The handshake negotiates the installed Claim Plane protocol against the adapter's semantic version range and reports the adapter, runtime, capabilities, guarantees, source, and project pin. An incompatible range or a pinned adapter/runtime mismatch fails before a Codex session starts. The pin is stored under .claim-plane/adapters/pins/ and may be removed with claim-plane adapters pin codex --clear.

External adapter packages can publish a claim_plane.adapters Python entry point. They are discovered without changing Claim Plane Core and use the same manifest, conformance, handshake, and pinning paths as Codex.

Interactive Codex launcher

Use the normal Codex conversational TUI without giving up Claim Plane authority or final evidence:

claim-plane codex --policy guarded

An optional initial prompt opens the same TUI with the first task already submitted:

claim-plane codex "Fix timeout handling and update its regression test" \
  --scope src/connectors/github.py \
  --policy guarded

Claim Plane owns the working directory, workspace-write sandbox, approval policy, model override, initial scope, and final verifier. Codex still owns the interactive conversation. Each completed turn is recorded without ending the controlled session; a follow-up prompt continues under the same admitted intent. When the TUI exits, Claim Plane independently verifies the final Git state, runs configured acceptance, records its duration, seals the controlled-run record, and prints the same delivery card used by one-shot execution. Scope remains automatic unless the operator supplies --scope; --lock-scope disables amendments. Brokered expansion requires a concrete rationale that explains why the exact denied resource is necessary for the task. Explicit operator requests to add or update tests are retained as structured completion obligations without storing prompt text. Final verification therefore rejects a delivery when the requested test artifact was not changed, even if the admitted source change is scope-clean and the pre-existing test suite still passes.

One-command controlled Codex run

After enrollment and diagnostics, one command owns the bounded Codex process, authority lifecycle, and final Git verification:

claim-plane init
claim-plane connect codex
claim-plane doctor
claim-plane run "Add pagination to the audit API" --policy guarded

The runner performs adapter negotiation and policy compatibility checks before execution, launches Codex in workspace-write mode, binds the runtime session to a stable run identity, and preserves the normal ChangeIntent admission and amendment path. Ctrl-C and wall-time expiry stop the process and revoke unfinished authority. A successful runtime exit is not sufficient for a green result: Claim Plane inspects the active intent, verifies completion against the current Git state, and returns DELIVERY VERIFIED, REJECTED, REVIEW REQUIRED, CANCELLED, TIMED OUT, or FAILED.

The default terminal view is intentionally compact: it shows preflight, Codex lifecycle, final scope and acceptance checks, risk, changed files, duration, and the evidence location without dumping raw runtime logs. The agent's final message is labelled as untrusted context rather than verification evidence. Use --verbose when diagnosing the underlying Codex stream, or --json for automation.

Scope remains automatic for normal use. For a reproducible initial authority boundary, repeat --scope with repository-relative files or directories; a genuinely required additional file must pass through the brokered amendment path. Add --lock-scope only when CI or an operator must forbid every expansion.

claim-plane run "Fix timeout handling and update its regression test" \
  --scope src/connectors/github.py \
  --policy guarded

The durable result is written under .claim-plane/runs/<run-id>/run.json. It contains task and final-message digests rather than raw text, the starting and resulting Git-state digests, adapter manifest and handshake identity, policy compatibility, lifecycle evidence, verification summary, final file and hunk metadata, configured acceptance commands, and cancellation outcome. Use --out result.json for an additional export, --timeout for the wall-time ceiling, and --model for an explicit Codex model override.

Evidence report and replay

A completed controlled run can be inspected without reopening Codex or repeating provider calls:

claim-plane report latest
claim-plane replay latest
claim-plane report <run-id> --json --out evidence-report.json
claim-plane replay <run-id> --json --out evidence-replay.json

The report is rebuilt from the durable run record and normalized append-only lifecycle journal. It includes task digests, repository bindings, adapter and runtime identity, effective policy, risk findings, guarantee levels, final changed files, hunk coordinates, acceptance status, usage, elapsed time, blocked attempts, observed mutations, scope amendments, verification, and a canonical evidence digest. Source content, raw prompts, tool payloads, credentials, and the final agent message are not exported.

Replay renders the same causal event stream as a stable decision chronology. It is a reconstruction of stored authority transitions, not a new model execution. A corrupt, out-of-order, or mismatched lifecycle stream cannot be replayed or represented as valid evidence.

Policy presets and risk classes

Inspect the effective policy before running an agent and classify sensitive paths without starting Codex:

claim-plane policy inspect --repo .
claim-plane policy inspect --policy strict --repo .
claim-plane policy classify src/auth/session.py migrations/0042_tokens.sql --repo .

The public presets have stable semantics:

• observe records supported would-deny decisions but lets the runtime continue; final Git verification remains mandatory. Control-plane files, corrupt state, branch drift, and pre-existing user changes are never weakened by shadow mode.
• guarded blocks supported undeclared mutations, routes scope growth through atomic re-admission, and marks high- or critical-risk delivery for review.
• strict fails closed for unknown, destructive, network, secret, and critical-resource actions. It starts only when the adapter manifest proves the required guarantees.
• critical requires a human gate for every delivery and denies critical-resource mutation without stronger authority. It never represents an automatic merge decision.

Repository risk is deterministic and path based. The default is medium; built-in rules identify CI workflows, migrations, secret material, review authority, package contracts, and runtime topology. Projects can add rules in .claim-plane/config.yaml:

risk:
  default: medium
  include_builtin_rules: true
  rules: [{"match": "src/auth/**", "level": "critical", "reason": "authentication boundary"}]

When several rules match, the highest risk wins. The run evidence stores the full effective policy, its digest, every changed-path classification, reason codes, and the final policy action. A runtime and acceptance result that would otherwise be VERIFIED becomes REVIEW_REQUIRED or REJECTED when the effective risk policy requires it.

Dogfood and golden task suite

The single-agent technical preview is evaluated on one frozen task corpus rather than changing examples between runs. The suite binds repository commits, task prompts, source references, acceptance commands, task classes, risk classes, coder seeds, and the fixed three-arm comparison:

Bare Codex
Claim Plane Observe
Claim Plane Guarded

Freeze and validate the reviewed corpus before any provider calls, then expand it into a deterministic run matrix:

claim-plane dogfood freeze candidate.json --release-grade --out golden-suite.json
claim-plane dogfood validate golden-suite.json --release-grade
claim-plane dogfood plan golden-suite.json \
  --release-grade \
  --model <model> \
  --out run-plan.json

A release-grade suite requires 20–30 tasks, 5–10 repositories, at least two coder seeds, multiple task and risk classes, full repository commit SHAs, and explicit acceptance commands. Each task/seed/arm cell has a stable execution identity. The same frozen task and acceptance contract are reused across all arms.

Execution and evaluation produce claim-plane.dogfood-result.v1 documents. Bind each measured evaluator output to its immutable plan cell before aggregation:

claim-plane dogfood record \
  run-plan.json <execution-id> evaluation.json \
  --out results/<execution-id>.json

Aggregation never fabricates missing measurements and fails completeness when a cell is absent, duplicated, unexpected, or bound to the wrong suite or plan:

claim-plane dogfood aggregate \
  golden-suite.json run-plan.json results/*.json \
  --release-grade \
  --out release-summary.json

claim-plane dogfood gate release-summary.json

The summary reports task success, accepted delivery, undeclared and missed mutations, scope amendments, false blocks, human repairs, retries, wall time, token and cost fields when available, changed files and lines, public API drift, and dependency drift. The release gate returns INCOMPLETE for a partial matrix and BLOCKED when guarded mode materially reduces task success without the configured accepted-delivery improvement. It does not present example values as measured results. See benchmark/golden-suite/README.md for the full artifact flow.

Codex swarm operator

Version 0.31.0 exposes the complete swarm lifecycle through one bounded operator command:

claim-plane init
claim-plane swarm start --spec swarm-session.json

For an existing session:

claim-plane swarm start <session-id>
claim-plane swarm status <session-id>
claim-plane swarm logs <session-id> --follow

swarm start does not grant new authority. It materializes the current concurrency plan, shared admission, managed worktrees, and merge queue, then dispatches only scheduler-runnable work within the session budget. Successful workers are integrated in deterministic order and the session reaches COMPLETED only after two-level verification produces SWARM VERIFIED. Merge conflicts, dirty failed worktrees, stale state, or control-plane errors stop the operator loop and remain explicit recovery work.

Run the fully offline demo without an API key or network access:

claim-plane swarm demo

The demo creates three work items, runs two independent workers concurrently, releases the dependent worker only after integration, and leaves the repository and evidence available for inspection.

Swarm planning foundation

Claim Plane can persist a planner-proposed swarm decomposition and a hard execution budget before any worker is launched:

claim-plane init
claim-plane swarm validate-budget --policy examples/swarm/budget-policy.json --work-items 2
claim-plane swarm create --spec examples/swarm/session-spec.json
claim-plane swarm status <session-id>
claim-plane swarm graph <session-id>
claim-plane swarm budget <session-id>
claim-plane swarm plan <session-id>
claim-plane swarm concurrency <session-id>
claim-plane swarm admit <session-id>
claim-plane swarm admission <session-id>
claim-plane swarm scheduler <session-id>
claim-plane swarm merge-plan <session-id>
claim-plane swarm merge-queue <session-id>

The session is bound to one repository identity and exact Git commit. Work items carry proposed operations, preserve requirements, acceptance commands, and explicit dependencies. Claim Plane rejects duplicate identifiers, missing dependencies, cycles, repository-escaping paths, and attempts to include control-plane or Git state.

The budget is a separate versioned protocol object. It caps active workers, per-work-item concurrency, work-graph size, total launches, token use, cost, wall time, replans, repairs, and restarts. It also records fail-closed policies for same-file work, unknown overlap, shared contracts, and schema changes. Work graph and budget replacements each require their own expected version, preventing concurrent planner updates from silently overwriting one another. The adaptive concurrency controller consumes the exact graph and budget versions, adds deterministic serialization constraints, packs safe work up to max_active, and persists source-bound execution waves. A graph or budget replacement invalidates that plan atomically. Shared admission then derives one source-bound ChangeIntent per work item and checks the authority topology before execution. The dynamic scheduler combines those admitted intents, effective dependencies, durable run state, retry ceilings, and remaining worker capacity to release only currently runnable work. Graph, budget, or concurrency-plan changes invalidate the admission record atomically. Once merge-plan exists, dependency release is integration-aware: a successful prerequisite must reach the managed integration branch before a dependent worker can start.

See Swarm sessions and work graphs for the complete format and CLI.

Codex project enrollment

Claim Plane can register a project-local lifecycle bridge for Codex without replacing the normal codex command:

cd my-project
claim-plane init
claim-plane connect codex
claim-plane doctor

codex

claim-plane init creates a stable project identity, writes the versioned .claim-plane/config.yaml, discovers the default branch and likely acceptance commands, prepares local state, and keeps .claim-plane/ out of Git status through the repository-local exclude file. Re-running initialization preserves the project identity and user-edited acceptance commands.

claim-plane connect codex installs Claim Plane-owned handlers in .codex/hooks.json while preserving unrelated project hooks. It records the detected runtime and sandbox characteristics and creates an exact adapter pin when the runtime reports a version. Re-running enrollment is safe and does not duplicate handlers.

The connector registers one stable dispatcher for SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, and SessionEnd. Codex discovers these project-local hooks automatically for trusted projects. On the first Codex session, open /hooks to review and trust the command hooks; Codex records trust against the hook definition.

For the first task in a session, Claim Plane pins the current Git commit, creates a private session-bound task identity, and injects model-visible coordination context through UserPromptSubmit. Codex can inspect the repository read-only, propose the expected committed and contingent scope, preserve requirements, and advisory acceptance checks, then submit that proposal through the local CLI. Claim Plane supplies the intent ID, owner, task ID, and immutable base commit itself before performing normal atomic admission. Project-configured acceptance remains operator-owned: when configured commands exist, Codex cannot replace or extend the executable final-verification contract, and its proposal is retained only as audit metadata.

The raw user prompt is not stored in connector state. The task record keeps a SHA-256 digest and prompt length for correlation, while the admitted intent stores the explicit goal and execution contract that Codex proposed. Repeated admission of identical content is idempotent, and a changed Git HEAD before admission is rejected as a stale bootstrap.

Once admitted, normal Codex prompt and tool lifecycle events renew the active intent lease automatically. The model does not need to issue a separate heartbeat command during an active session.

For intercepted PreToolUse calls, Claim Plane classifies repository effects before execution. Read-only calls continue normally. A mutation already covered by committed scope continues through Codex's normal sandbox and approval flow. A mutation covered by one contingent declaration is atomically promoted and re-admitted before the tool call continues. Undeclared mutations, stale-base mutations, unknown mutating tool surfaces, and shell commands whose repository effects cannot be proven are denied with model-visible guidance. Claim Plane stores the decision, affected paths, and counters without persisting raw tool arguments.

When a denial identifies concrete additional file authority, the guard issues a short-lived, session-bound scope-amendment ticket containing only the exact denied mutation set. Codex supplies a rationale through claim-plane codex-intent amend; it cannot choose different paths, change the task identity, change the pinned base, or remove existing preserve and acceptance requirements. Claim Plane derives the amended ChangeIntent, checks ticket integrity and intent freshness, performs normal atomic re-admission, and activates the amended intent only when admission succeeds. A rejected amendment leaves the previously active intent unchanged. Multiple contingent resources that cannot be promoted individually in one tool call can therefore be committed together through one inspectable amendment.

The connector also reserves a narrow shell control channel for claim-plane codex-intent admit, status, amend, verify, and abandon. The command must target the current Codex session and current repository; initial admission uses --proposal-json rather than a shell pipe or repository temporary file. Other Claim Plane commands and opaque shell effects remain subject to the normal fail-closed classification. Connector control state under .claim-plane/**, .git/**, and .codex/** cannot be granted through a session intent or amendment.

For a directly launched Codex session, Stop remains the bounded verified-completion checkpoint. Under claim-plane codex, however, Stop is only a conversational turn boundary: the hook reports AGENT TURN COMPLETED and final verification pending, allowing the user to continue the TUI without a premature green result. After the user exits, the launcher collects tracked and untracked repository changes, checks the actual work against admitted scope and preserve/contract policy, executes declared acceptance with worktree-integrity checks, and seals normalized verification before session end.

A clean launcher-owned completion is persisted and surfaced as VERIFIED with changed-file counts, mutation-authority counters, scope expansions, acceptance outcome, and verification findings. Direct sessions retain the bounded repair continuation: a failed first Stop can return findings once, and a still-failing continuation ends explicitly UNVERIFIED instead of looping indefinitely. The same gate remains available through claim-plane codex-intent verify --session-id <id> --repo . and claim-plane codex-intent status.

The connector hardens long-running local use as well. Pre-existing user changes are fingerprinted at task bootstrap: unchanged pre-existing paths are excluded from task attribution, while Codex is denied mutation authority over those paths so existing work is not silently mixed into an autonomous task. Only one active Codex session may hold mutation authority in a physical worktree; independent concurrent sessions should use separate Git worktrees, where normal Claim Plane coordination still applies. A resumed session renews a live intent automatically and can re-admit an expired intent only when the pinned commit and branch are unchanged. Changed repository state, released or stale authority, corrupted session state, missing enrollment state, branch switches, and connector hook drift all fail closed. Re-running claim-plane connect codex repairs connector-owned hook definitions while preserving unrelated hooks. If an unfinished session is intentionally discarded, claim-plane codex-intent abandon --session-id <id> --repo . releases its intent authority so another Codex session can use the same worktree immediately.

committed mutation  -> authorize -> Codex sandbox/approval -> execute
contingent mutation -> promote + re-admit -> authorize -> execute
undeclared mutation -> deny -> exact ticket -> reason -> re-admit -> retry
unprovable mutation -> deny before tool execution
direct Codex Stop -> collect evidence -> VERIFIED or bounded repair continuation
claim-plane codex Stop -> turn completed -> exit TUI -> acceptance -> VERIFIED

claim-plane doctor checks Git and worktree state, project configuration, state-directory permissions, acceptance commands, credential hygiene, Codex runtime and authentication availability, sandbox characteristics, adapter negotiation, and the hook surface required by the guard. claim-plane doctor codex remains an equivalent explicit form. Hook interception is an integration boundary, not a substitute for the brokered reference-monitor boundary: runtime hook coverage and timeout behavior remain properties of Codex itself. Claim Plane therefore keeps broker capabilities, repository identity, admission, and verification as the authoritative core primitives.

The session-bound proposal protocol is documented by schemas/codex-intent-proposal.schema.json, the amendment ticket by schemas/codex-scope-amendment.schema.json, and verified completion by schemas/codex-completion.schema.json. The lifecycle bridge does not depend on MCP; MCP remains an optional interaction surface for status, explanation, and evidence.

To remove only the Codex bridge without disturbing other hooks:

claim-plane disconnect codex

To clear Claim Plane-owned local state while preserving repository files, unrelated hooks, and .claim-plane/config.yaml:

claim-plane reset

Use claim-plane reset --remove-config only when the project enrollment itself should also be removed.

If .codex/config.toml explicitly sets [features] hooks = false, enrollment fails rather than overriding the project's Codex policy. If inline Codex hooks already exist in that file, Claim Plane leaves them untouched and reports that Codex will merge both project-local hook sources.

ChangeIntent

A contract must name the concept it governs. An unrelated shared contract cannot make a semantic overlap safe.

{
  "intent_id": "rate-limit-metrics",
  "task_id": "issue-142-metrics",
  "owner": "agent-metrics",
  "base_revision": "main",
  "base_commit": "<40-character-git-commit>",
  "dependencies": ["rate-limit-core"],
  "operations": [
    {
      "access": "write",
      "kind": "file",
      "identifier": "src/rate_limit/metrics.py"
    },
    {
      "access": "extend",
      "kind": "concept",
      "identifier": "RequestThrottler"
    },
    {
      "access": "read",
      "kind": "contract",
      "identifier": "allow",
      "signature": "allow(request)->RateLimitDecision",
      "subject_concept_id": "RateLimiter"
    }
  ],
  "preserves": [
    "contract:RateLimiter::allow=allow(request)->RateLimitDecision"
  ],
  "acceptance": [
    "pytest tests/rate_limit/test_metrics.py"
  ]
}

Admit it atomically:

claim-plane \
  --db .claim-plane/plane.db \
  --semantic \
  --lexicon examples/rate-limiter/lexicon.yaml \
  admit examples/rate-limiter/intents/metrics.json

Generate a compact context pack:

claim-plane --db .claim-plane/plane.db context rate-limit-metrics

The pack includes only the admitted surfaces, canonical concepts, contracts, dependencies, acceptance criteria, current notices, and worker rules.

Adaptive scope

Operations may be marked as committed or contingent:

{
  "access": "write",
  "kind": "file",
  "identifier": "src/click/shell_completion.py",
  "commitment": "contingent"
}

Committed operations participate in admission immediately and grant mutation authority. Contingent operations are planning hints: they do not reserve write ownership during initial admission. Before the first mutation, the scope must be promoted and re-admitted atomically. A failed promotion leaves the current intent unchanged.

claim-plane --db .claim-plane/plane.db \
  promote-scope worker-intent src/click/shell_completion.py --mode write --region lines:20-24

A governed broker performs the same promotion automatically when a worker first attempts to mutate a predeclared contingent path. Broad contingent globs are narrowed to the concrete path being requested rather than promoted as one broad write reservation. Contingent surfaces may be inspected read-only before promotion, and those possible read premises still participate in coordination against active writers.

Admission semantics

Unknown overlapping writes fail closed. A broad scope such as src/** conflicts with a concrete write to src/core.py. Two writers may share one file only when their declared regions are disjoint and their actual Git hunks remain inside those regions.

Amendments and live dependency invalidation

A producer can amend an admitted intent with an optimistic version check:

claim-plane --db .claim-plane/plane.db amend updated-core-intent.json --expected-version 1

When an admitted producer changes a contract, Claim Plane:

1. records a new intent version;
2. marks affected dependent intents as stale;
3. creates structured coordination notices;
4. exposes those notices in the worker context pack;
5. propagates staleness transitively to downstream consumers whose producer outputs are no longer trustworthy;
6. requires amendment and re-admission before any stale worker continues.

claim-plane --db .claim-plane/plane.db notices rate-limit-metrics
claim-plane --db .claim-plane/plane.db ack-notice 1

This is advisory coordination with an enforceable stale state, not a distributed source-code lock.

Brokered execution boundary

Trusted sessions prove that recorded events were not altered. Brokered mode additionally makes the control plane perform the operation itself. Start a broker outside the worker sandbox:

export CLAIM_PLANE_BROKER_TOKEN="random-worker-token"
export CLAIM_PLANE_OBSERVATION_KEY="ci-observation-key"
export CLAIM_PLANE_BROKER_KEY="separate-broker-attestation-key"

claim-plane --db .claim-plane/plane.db broker-serve worker-intent worker-session \
  --root ../worker-worktree \
  --socket /tmp/claim-plane-worker.sock

Tool adapters call the broker instead of reading the repository directly:

claim-plane broker-call read_file \
  --socket /tmp/claim-plane-worker.sock \
  --path src/config.py

claim-plane broker-call replace_lines \
  --socket /tmp/claim-plane-worker.sock \
  --path src/core.py --start-line 40 --end-line 55 \
  --content "..."

# `extend` is append-only
claim-plane broker-call append_file \
  --socket /tmp/claim-plane-worker.sock \
  --path docs/notes.md --content "New section\n"

# `rename` must declare rename_to/target/to in ChangeIntent metadata
claim-plane broker-call rename_file \
  --socket /tmp/claim-plane-worker.sock \
  --path src/old.py --target-path src/new.py

On Linux, a proxy-only worker can be started with no repository mount:

claim-plane broker-run \
  --socket /tmp/claim-plane-worker.sock -- \
  your-agent-runtime

The worker sees the broker socket and a minimal runtime namespace, not the repository or the host home directory. This boundary is only non-bypassable when the agent runtime has no alternate filesystem mount, shell escape, or privileged host channel. See docs/BROKERED_RUNTIME.md.

On macOS and in long CloudStorage/pytest paths, Claim Plane automatically maps an overlong Unix-socket path to a deterministic private path under /tmp; the server, client, and broker-run resolve the same path transparently.

For build and test workflows, Claim Plane exposes only named commands from a JSON allowlist. Commands run against an immutable snapshot rather than the mutable broker root:

{
  "unit-tests": {
    "argv": ["python", "-m", "pytest", "-q"],
    "timeout_seconds": 300
  }
}

claim-plane --db .claim-plane/plane.db broker-serve worker-intent worker-session \
  --root ../worker-worktree --socket /tmp/claim-plane-worker.sock \
  --commands broker-commands.json

claim-plane broker-call run_command \
  --socket /tmp/claim-plane-worker.sock --name unit-tests

Governed admission and immutable base pinning

A branch name is planning metadata, not an execution guarantee. Claim Plane uses governed admission by default, so an unpinned intent is rejected before a worker starts. Pin it first:

claim-plane pin-intent intent.json --repo . --out intent.pinned.json

A pinned intent contains both:

{
  "base_revision": "main",
  "base_commit": "a81f42c..."
}

Integration fails closed when the base repository, an intent, or a worker repository does not contain the same exact commit. If base_revision is already a full object ID, Claim Plane normalizes it into base_commit. For migration-only local experiments, pass the global --exploratory flag or open Plane with governance="exploratory".

Trusted observed read/write evidence

Claim Plane can store runtime accesses inside the control-plane database rather than trusting an editable worker-owned trace file. A trusted monitor or MCP proxy starts a session, records accesses with a server-held HMAC key, and seals it after execution:

export CLAIM_PLANE_OBSERVATION_KEY="secret-from-ci"

claim-plane --db .claim-plane/plane.db observe-start worker-session worker-intent \
  --monitor-id mcp-proxy --key-id ci-observer --coverage tool_proxy

claim-plane --db .claim-plane/plane.db observe-record worker-session \
  --key-env CLAIM_PLANE_OBSERVATION_KEY \
  --mode read --kind file --identifier src/config.py --tool read_file

claim-plane --db .claim-plane/plane.db observe-seal worker-session \
  --key-env CLAIM_PLANE_OBSERVATION_KEY

Attach the sealed session to a worker and require trusted evidence:

{
  "workers": [
    {
      "intent_id": "rate-limit-metrics",
      "repo_path": "../worktrees/rate-limit-metrics",
      "observation_session_id": "worker-session"
    }
  ],
  "observation_policy": {
    "mode": "trusted",
    "require_complete": true,
    "allowed_coverages": ["brokered_proxy", "tool_proxy", "os_monitor"]
  },
  "observation_key_env": "CLAIM_PLANE_OBSERVATION_KEY"
}

Each event includes a sequence number, previous hash, event hash, and HMAC. Sealing authenticates the complete session summary. Integration rejects missing, incomplete, tampered, incorrectly bound, or worker-owned file traces under trusted policy. The guarantee is complete relative to the declared trusted monitor boundary; Claim Plane still cannot observe tools that bypass that monitor unless an OS-level monitor supplies the session.

Legacy record-access JSONL traces remain supported in optional and required modes for migration.

For the strongest tool-mediated mode, attach a session created by broker-serve and use:

{
  "observation_policy": {
    "mode": "brokered",
    "require_complete": true,
    "allowed_coverages": ["brokered_proxy"]
  }
}

brokered mode verifies that every accepted event was produced by the intent-enforcing Claim Plane broker. The deployment is non-bypassable only when the worker has no alternate repository mount or privileged channel.

Integration verification

Collect a manifest from a Git worktree:

claim-plane --db .claim-plane/plane.db collect-git rate-limit-core --repo . --out manifest.json
claim-plane --db .claim-plane/plane.db verify-manifest manifest.json

Or collect and verify in one step:

claim-plane --db .claim-plane/plane.db verify-git rate-limit-core --repo .

Acceptance commands are never executed implicitly. They run only when explicitly enabled:

claim-plane \
  --db .claim-plane/plane.db \
  verify-git rate-limit-core \
  --repo . \
  --run-acceptance \
  --acceptance-timeout 300

The verifier checks:

• changed files are inside admitted write surfaces;
• real Git hunks stay inside declared line regions;
• required exact writes are present;
• the work is based on the admitted revision;
• observed typed signatures match concept-bound contracts;
• structured preserve policies still hold;
• acceptance commands were run and passed when required;
• deprecated or alias terminology did not enter changed text in semantic mode;
• candidate manifests do not contain overlapping hunks or incompatible contracts.

Generate a focused repair plan:

claim-plane --db .claim-plane/plane.db repair-manifest manifest.json

Acceptance sandbox and evidence attestation

Repository-tree immutability remains the default. For OS-level isolation, configure a backend:

{
  "worker_sandbox": {
    "backend": "auto",
    "strict": true,
    "allow_network": false
  },
  "integration_sandbox": {
    "backend": "auto",
    "strict": true,
    "allow_network": false
  }
}

auto uses Bubblewrap on supported Linux hosts or sandbox-exec where available. Strict mode fails closed instead of silently falling back. The default tree backend proves repository-tree immutability but is not a full operating-system security boundary.

Optional HMAC evidence attestation uses a key supplied only through the environment:

{
  "evidence_signing_key_env": "CLAIM_PLANE_SIGNING_KEY",
  "evidence_key_id": "ci-prod"
}

Verify later with:

claim-plane verify-evidence evidence.json evidence.sig.json \
  --key-env CLAIM_PLANE_SIGNING_KEY

Dependency graph

Every explicit or inferred premise is stored as a directed dependency. Claim Plane rejects a proposed admission or amendment when it would create a cycle. The graph can be inspected in producer-first order:

claim-plane --db .claim-plane/plane.db graph

The graph response includes nodes, typed edges, producer states, cycle evidence, and a topological order. A producer amendment invalidates only directly affected resource premises on the first hop; once a consumer becomes stale, its outputs are treated as untrusted and invalidation propagates transitively.

Verified integration pipeline

Claim Plane verifies several agent worktrees as one immutable integration attempt. It does not collect a manifest and later re-read a mutable worktree. Instead, for every worker it:

1. seeds a temporary Git index from the admitted base commit;
2. captures tracked changes and non-ignored untracked files into an immutable tree;
3. creates one synthetic snapshot commit and one binary patch;
4. collects the manifest from a detached worktree at that exact commit;
5. runs worker acceptance on the detached snapshot;
6. fails closed if acceptance mutates the snapshot;
7. applies the persisted, hash-verified patch bytes in dependency order;
8. runs integrated acceptance and proves the composed tree did not change;
9. creates a verified result commit, result patch, and canonical evidence bundle.

{
  "run_id": "rate-limit-feature",
  "base_repo": ".",
  "base_revision": "main",
  "base_commit": "<git-sha>",
  "workers": [
    {
      "intent_id": "rate-limit-core",
      "repo_path": "../worktrees/rate-limit-core"
    },
    {
      "intent_id": "rate-limit-metrics",
      "repo_path": "../worktrees/rate-limit-metrics",
      "repair_command": "codex exec --full-auto 'Apply the repair plan at {repair_plan}'"
    }
  ],
  "integration_commands": ["pytest -q"],
  "max_attempts": 2,
  "require_clean_worker_acceptance": true,
  "require_clean_integration_commands": true,
  "result_ref": "refs/claim-plane/runs/rate-limit-feature"
}

Run it with:

claim-plane --db .claim-plane/plane.db integrate integration-run.json

Each attempt stores worker.patch, manifest.json, their SHA-256 files, result.patch, evidence.json, and deterministic reports under .claim-plane/runs/<run_id>/. The result includes the verified tree and commit hashes. result_ref is optional and, when supplied, must live under refs/claim-plane/.

Repair commands receive CLAIM_PLANE_REPORT, CLAIM_PLANE_REPAIR_PLAN, CLAIM_PLANE_INTENT_ID, CLAIM_PLANE_REPO, CLAIM_PLANE_ATTEMPT, and CLAIM_PLANE_MERGE_ERROR. The runner never silently expands an intent; the external worker must repair within the admitted surface or submit an amendment.

Structured preserve policies

Claim Plane enforces deterministic policies with explicit prefixes:

path-unchanged:src/public_api/**
contract:RateLimiter::allow=allow(request)->RateLimitDecision

Unstructured prose remains useful worker guidance, but it is not treated as a machine-enforced guarantee.

Model routing

Claim Plane does not call a model provider. It returns a transparent risk-based recommendation:

claim-plane --db .claim-plane/plane.db route rate-limit-core

A cheaper worker is only a cost optimization. The same integration gate applies to every tier, and failed work should escalate to the configured fallback tier.

MCP

claim-plane-mcp \
  --db .claim-plane/plane.db \
  --semantic \
  --lexicon lexicon/lexicon.yaml

Primary tools include:

• admit_change_intent
• amend_change_intent
• promote_contingent_scope
• get_worker_context
• list_active_intents
• list_coordination_notices
• acknowledge_coordination_notice
• heartbeat_intent
• verify_change_manifest
• verify_git_worktree
• plan_targeted_repair
• recommend_worker_tier
• get_dependency_graph
• run_integration
• record_observed_access
• verify_evidence_bundle

The MCP process is only a transport adapter. Protocol decisions remain deterministic library code.

Agent Lexicon boundary

Agent Lexicon answers:

Which canonical project concept does this name or text surface refer to?

Claim Plane answers:

Who intends to read or mutate that concept, on which revision, under which contract, and may the work proceed concurrently?

The Integration Verifier answers:

Did the resulting code and documentation respect those declarations, and what is the smallest repair when they did not?

Project layout

src/claim_plane/
  connectors/     project-local coding-agent enrollment and lifecycle adapters
  coordination/   sound pre-write admission and bounded context packs
  core/           protocol models, storage boundary, registry, semantic bridge, plane facade
  integration/    immutable snapshots, verification, evidence, integration, repair
  routing/        transparent risk-based model-tier recommendation
  mcp/            stdio MCP adapter
  git/            legacy hook adapter
examples/          runnable overlapping-task scenario
schemas/           intents, manifests, integration runs, and observation traces
docs/              architecture, protocol, execution, storage, integration, benchmark, releasing
benchmark/         deterministic protocol suite and adapter-driven A/B/C harness
papers/            publication index, citation metadata, and paper-to-reproduction links
experiments/       reproducible research studies and model-specific evaluation code
  cooperbench/      frozen Planner v1, paper reproduction, confirmatory runner, analysis, and Linux research image

Reproducible research environment

The CooperBench studies can run directly on a host Python environment or inside the pinned Linux research image under experiments/cooperbench/docker/. The container fixes the Python base image, uv version, locale, timezone, and Git identity used by the research runner while leaving claim-plane itself free of runtime container dependencies.

./scripts/cooperbench-docker.sh build
./scripts/cooperbench-docker.sh environment
./scripts/cooperbench-docker.sh prepare /path/to/CooperBench
OPENROUTER_API_KEY=... ./scripts/cooperbench-docker.sh reproduce /path/to/CooperBench

The larger frozen-plan study is also CLI-native. It first gold-validates and freezes the exact 30-pair set, then freezes Planner v1 once, then runs nine resumable 10-pair shards covering coder seeds 101, 202, and 303:

python -m experiments.cooperbench confirmatory prepare --cooperbench /path/to/CooperBench
OPENROUTER_API_KEY=... python -m experiments.cooperbench confirmatory freeze-plans \
  --cooperbench /path/to/CooperBench
OPENROUTER_API_KEY=... python -m experiments.cooperbench confirmatory run \
  --cooperbench /path/to/CooperBench --seed 101 --shard 1
python -m experiments.cooperbench confirmatory status
python -m experiments.cooperbench confirmatory aggregate
python -m experiments.cooperbench confirmatory verify-analysis

Aggregation is intentionally strict: it requires all nine completed shards and the full 360-row pair/seed/arm matrix before writing final analysis artifacts. The output includes arm, feature-pair, and repository-task cluster summaries, task-cluster bootstrap confidence intervals, failure and coordination-mechanism summaries, cost accounting, canonical JSON/CSV results, and a SHA-256 publication manifest.

The CooperBench checkout is mounted read-only in the research image. Repository caches, worktrees, checkpoints, results, and analysis artifacts are persisted under .claim-plane/docker-research/. Protocol artifacts record the exact pair set, benchmark provenance, Planner v1 policy identity, frozen plan fingerprints, and shard identities without persisting API keys.

Current limits

Claim Plane remains an alpha coordination kernel.

• It consumes structured intents; it does not yet generate the task graph.
• Built-in source extraction is Python-first.
• Line-region admission is supported; stable AST-node ownership across edits is future work.
• Documentation semantic checking is surface-oriented, not a full code-to-doc factual verifier.
• SQLitePlaneStore is a single-host backend. The OS lock is derived from Git's canonical common directory, so separate local databases cannot choose independent lock namespaces. Multi-host deployments still require one network-authoritative registry such as PostgreSQL plus distributed leases and fencing.
• The verified pipeline includes non-ignored untracked files, but ignored build/cache artifacts are intentionally excluded.
• Result commits are created as immutable Git objects; publishing a branch or PR remains an explicit caller action unless a namespaced result_ref is configured.
• Observation guarantees cover only tool/MCP accesses emitted to the trace; bypassed reads remain unobserved.
• The default tree sandbox detects repository mutations but does not isolate network or the host filesystem; strict OS isolation requires an available supported backend.
• HMAC evidence provides shared-secret authenticity, not public-key identity or hardware attestation.
• The router is deterministic and heuristic, not learned.
• Claim Plane has not yet demonstrated lower total cost to clean merge on large real repositories. The repository includes the frozen Planner v1 policy, an executable reproduction of the published six-pair CooperBench mechanism check, the frozen-plan 30-pair × 3-seed runner, and deterministic publication aggregation. Confirmatory conclusions remain unpublished until the full study is completed and the resulting analysis is reviewed.

The comparative evaluation requirements are documented in docs/BENCHMARK.md, and the study infrastructure is described in experiments/cooperbench/README.md.

License

Apache-2.0.