Governed Agent Autonomy Patterns

GAAP is a Rust library and CLI that evaluates normalized plan, permission, tool-trust, verification, runtime, mutation, and completion decisions for an agent run.

The current executable slice provides the integrity coordinator, frozen contracts, and a deterministic Rust runtime that calls explicit adapter ports before protected effects. A separate MCP stdio client executes external tools through that runtime. A stable-v1 ACP client mediates delegated agent filesystem operations through the same runtime. A separate attestation adapter signs and verifies retained evidence. The Goose reference can select a local OCI profile for protected effects and independent verification. Provider-specific integrations, durable recovery and production isolation remain pending.

The Rust module is the implementation under test. The conformance protocol and fixture corpus live in the separate run-invariant repository. GAAP doesn't import or vendor RunInvariant.

Implemented and tested now:

• a Rust RunCoordinator with one public evaluation interface;
• plan approval bound to the exact subject digest;
• deny precedence and explicit approval for risky or unknown actions;
• capability approval bound to an exact capability digest;
• independent, subject-bound, evidence-bearing verification;
• fail-closed usage accounting and bounded overage approval;
• separate mutation and completion authorization;
• a language-neutral RunInvariant process adapter;
• a 35/35 black-box conformance packet for the frozen protocol;
• provider-neutral Agent Run Request and Terminal Run Receipt Rust types;
• RFC 8785 canonical request and receipt-body digests;
• fail-closed policy, lifecycle, evidence, subject-freshness, and usage validation;
• provider-neutral Protected Effect Request and Result Rust types with typed filesystem, process, network, and external-service scopes;
• parent-bound request digests and sealed, replay-resistant result digests;
• fail-closed decision/status, observed-identity, drift, evidence, and non-execution invariants;
• a Rust gaap::runtime engine around RunCoordinator with narrow agent, executor, and verifier ports plus explicit port usage accounting;
• runtime-only support for trusted capabilities, permission policy, overage approvals, verifier identities, and effect usage estimates without changing the frozen 0.1.0 contracts;
• deterministic protected-effect execution through test executor ports, one-shot ask blocking, duplicate-effect rejection, unknown-outcome separation, interruption evidence, and stale-verification rejection;
• a separate MCP stdio client with exact capability approval, bounded transport and retained invocation evidence;
• a separate ACP v1 client with session ownership, delegated filesystem effects, host metering and strict protocol checks;
• a pinned real Goose conversation through ACP/MCP with per-effect gates and independent verification;
• offline DSSE/in-toto signing with explicit trust and retained content;
• a local OCI profile with explicit image, mounts, environment, network and resource limits, plus retained runtime and cleanup evidence;
• generated Draft 2020-12 JSON Schemas; and
• Agent Run terminal examples plus completed/executed, denied, awaiting-authority, failed, interrupted, stale-subject, schema-drift, and unknown-outcome Protected Effect examples.

Not implemented yet:

• OpenAI, Anthropic or other provider-specific integrations;
• production Protected Effect executor adapters, retry orchestration, reconciliation, or persistence;
• repository mutation interception;
• approval persistence, revocation, or delegated authority;
• production sandbox isolation, provider billing meters or durable evidence ledgers; and
• crash recovery or resumable run state.

The conformance packet proves normalized decision compatibility for the frozen cases. It doesn't prove those missing runtime properties or certify GAAP for production use.

GAAP pins Rust 1.96.0. Install Rust with rustup, then run:

git clone https://github.com/nnennandukwe/governed-agent-autonomy-patterns.git
cd governed-agent-autonomy-patterns
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
cargo build --locked
cargo run --locked --example generate-contract-artifacts -- --check

The generated-history guide covers the independent Agent Run model, named regressions, minimized JSON replay, deeper exploration and source mutants. Ordinary CI uses bounded deterministic histories; this sampled exploration complements RunInvariant's public black-box corpus.

Schemas and examples are registered in one typed catalog. To intentionally reconcile all managed artifacts under schemas/ and examples/contracts/, run cargo run --locked --example generate-contract-artifacts, review the diff, then rerun the command with --check.

Inspect the CLI:

cargo run --locked -- --help

RunInvariant 0.2.0 starts GAAP as an opaque child process. Clone both repositories into the same parent directory:

git clone https://github.com/nnennandukwe/run-invariant.git
git clone https://github.com/nnennandukwe/governed-agent-autonomy-patterns.git
cd governed-agent-autonomy-patterns
cargo build --locked
cd ../run-invariant
node bin/run-invariant.js subject -- \
  ../governed-agent-autonomy-patterns/target/debug/gaap run-invariant

The expected bounded result is:

Subject: gaap 0.1.0 (rust)
Subject conformance: 35/35 cases

RunInvariant sends case IDs, gate names, and normalized inputs without case titles or expected decisions. GAAP rejects unknown subject schemas, decision protocol digests, and fixture digests. Its response is bound to the exact input bytes with request_sha256.

The committed packet is derived output. CI recomputes it using the pinned RunInvariant commit and fails if the packet changes.

The RunCoordinator is the deep module at the integrity seam. The RunInvariant adapter and the bounded runtime call the same interface; neither provider-specific message types nor transport details enter the coordinator.

The runtime owns lifecycle advancement around the coordinator: plan, authorize mutation, execute through explicit adapters, account for resources, obtain independent verification for the current artifact digest, and authorize completion only if no later mutation invalidated that evidence. Future adapter slices can bind that runtime to providers, sandboxes, persistence, and ThreadLoop without changing the frozen 0.1.0 contracts.

Architecture decisions:

• 0001: Own the agent loop
• 0002: Use an external conformance seam
• 0003: Freeze the Agent Run contract as canonical evidence
• 0004: Separate Protected Effect contracts from execution
• 0005: Add a bounded Agent Run engine
• 0006: Add the MCP client and map conference reuse
• 0007: Add the ACP client and mediate delegated effects

The normative contract guide is Agent Run Contract 0.1.0. Contract receipts are content-addressed; the separate attestation adapter below adds authenticated producer evidence without changing those contracts.

The inner effect boundary is defined by Protected Effect Contract 0.1.0. Its validators check contract consistency; they don't replace RunCoordinator or grant effect authority.

The implementation is accompanied by material that can be used independently:

• Plan
• Permission
• Tool trust
• Verification
• Runtime accountability
• Governed publish pipeline
• Scorecard
• Diagrams

The retired Node/TypeScript harness, BoundaryBench, and exploratory pilot remain available from the legacy-ts-boundarybench-v0.1.0 tag. BoundaryBench's frozen conformance history now lives in RunInvariant.

The harness engineering review is the shared, dated research snapshot for GAAP, ThreadLoop, and RunInvariant. The adoption decision tracker records candidate owners, prerequisites, proposed experiments, and follow-up issues. Research candidates require an explicit decision before entering a repository roadmap.

GAAP is licensed under the Apache License 2.0.

The ACP adapter pins the official Rust SDK 3.3.0 and stable protocol v1. One session belongs to one accepted Agent Run. Delegated file reads and writes pause until the engine's gates admit their exact protected effect; the host executor and independent verifier supply outcome evidence. Permission prompts don't authorize ambient agent execution, terminal capabilities aren't advertised, and draft-v2 features aren't enabled.

This profile requires a trusted local agent that delegates filesystem access over ACP and a host meter for model usage. It doesn't isolate the agent's own system calls or prove that arbitrary agents comply. See the compatibility and recovery policy in ADR 0007. The governed Goose reference below exercises real interoperability.

The MCP adapter discovers external tool descriptors and invokes an exactly approved tool through the existing GAAP executor port. It uses the official Rust SDK in a separate crate, explicit child environments, immutable effect bindings, host subject observation, and bounded stdio. Its deterministic subprocess tests also run through AgentRunEngine and validate the resulting receipts independently.

The initial profile pins MCP 2025-11-25 and rmcp 3.5.1. The local stdio execution profile doesn't provide OS isolation. The governed Goose reference exercises interoperability; durable reconciliation and ThreadLoop ingestion retain their own roadmap issues. The reuse mapping records which conference-demo patterns carry forward and which capabilities remain separate work.

The governed Goose reference drives a real, pinned Goose conversation through both official adapters with local deterministic provider fixtures, per-effect gates and independent shipping-code verification.

The attestation adapter carries full run/effect ledgers in a versioned in-toto Statement and DSSE envelope. Offline consumers use explicit signer and policy trust, frozen contract validation and retained content bytes. The Goose reference emits public-key fixtures for controller integration tests; signing alone doesn't authorize a lifecycle transition.

The Linux gVisor profile selects pinned runsc through the same neutral SandboxAdapter. Its required Linux CI lane exercises actual isolation, failure paths and signed Goose evidence; host configuration and runtime trust remain security-critical.