Gait — Signed Proof and Fail-Closed Control for Production AI Agent Tool Calls

1# Gait — Signed Proof and Fail-Closed Control for Production AI Agent Tool Calls
2 
3## Overview
4 
5Use Gait when an AI agent can cause real side effects and you need deterministic control plus portable proof.
6 
7Gait is not an agent framework, not a model host, and not a dashboard. It is an offline-first Go CLI that sits at the tool boundary.
8 
9Capture every prod agent tool call as a signed, offline-verifiable pack. Enforce fail-closed policy before high-risk actions execute. Turn incidents into CI regressions in one command.
10 
11Docs: [clyra-ai.github.io/gait](https://clyra-ai.github.io/gait/) | Install: [`docs/install.md`](docs/install.md) | Homebrew: [`docs/homebrew.md`](docs/homebrew.md)
12 
13Managed/preloaded agent note: managed agents can use Gait at the tool boundary, but Gait does not host the model or replace your agent runtime.
14 
15## Integration First (New or Existing Agent Flows)
16 
17The integration contract is simple:
18 
191. normalize a tool call into intent
202. call Gait for a verdict
213. execute real side effects only on `allow`
224. keep the signed trace/artifact
23 
24```python
25def dispatch_tool(tool_call):
26    decision = gait_evaluate(tool_call)
27    if decision["verdict"] != "allow":
28        return {"executed": False, "verdict": decision["verdict"]}
29    return {"executed": True, "result": execute_real_tool(tool_call)}
30```
31 
32Pick the adoption lane that matches your stack:
33 
34- Inline runtime wrapper (any language): call `gait gate eval` in your dispatcher before tool execution.
35- MCP sidecar/transport lane: `gait mcp proxy` (one-shot) or `gait mcp serve` (long-running) at the boundary.
36- Python SDK lane: use `sdk/python/gait` for ergonomics; it is intentionally a thin subprocess wrapper over the local Go `gait` binary.
37 
38If you do not want Python subprocess boundaries, call `gait` directly from your runtime or use the MCP sidecar path.
39 
40Start here:
41 
42- Blessed lane: [`examples/integrations/openai_agents/`](examples/integrations/openai_agents/)
43- Quickstart script: `examples/integrations/openai_agents/quickstart.py`
44- Integration boundary guide: [`docs/agent_integration_boundary.md`](docs/agent_integration_boundary.md)
45- Integration checklist: [`docs/integration_checklist.md`](docs/integration_checklist.md)
46- MCP capability matrix: [`docs/mcp_capability_matrix.md`](docs/mcp_capability_matrix.md)
47- Python SDK contract: [`docs/sdk/python.md`](docs/sdk/python.md)
48 
49## When To Use Gait
50 
51- Tool-calling AI agents need enforceable allow/block/approval decisions.
52- You need signed, portable evidence artifacts for PRs, incidents, or audits.
53- You want offline, deterministic regressions that fail CI with stable exit behavior.
54- You run multi-step jobs and need checkpoints, pause/resume/cancel, and inspectable state.
55 
56## When Not To Use Gait
57 
58- No local Gait CLI or Gait artifacts are available in the execution path.
59- Your workflow only needs prompt orchestration without tool-side effects or evidence contracts.
60- You only need hosted observability dashboards and do not need offline verification or deterministic replay.
61 
62## Try It (Offline, <60s)
63 
64### Fast 20-Second Proof
65 
66```bash
67# Install (checksums at docs/install.md)
68curl -fsSL https://raw.githubusercontent.com/Clyra-AI/gait/main/scripts/install.sh | bash
69 
70# Create a signed pack from a synthetic agent run
71gait demo
72 
73# Prove it's intact
74gait verify run_demo
75 
76# Turn it into a CI regression gate — one command
77gait regress bootstrap --from run_demo --junit ./gait-out/junit.xml
78```
79 
80No account. No API key. No internet. You now have a verified artifact and a permanent regression test.
81 
82## Dev vs Prod
83 
84Development quickstart:
85 
86- `gait demo`
87- `gait verify run_demo`
88 
89Production hardening baseline:
90 
91```bash
92mkdir -p .gait
93gait policy init baseline-highrisk --out .gait/policy.yaml
94cat > .gait/config.yaml <<'YAML'
95gate:
96  policy: .gait/policy.yaml
97  profile: oss-prod
98  key_mode: prod
99  private_key_env: GAIT_PRIVATE_KEY
100  credential_broker: env
101  credential_env_prefix: GAIT_BROKER_TOKEN_
102  rate_limit_state: ./gait-out/gate_rate_limits.json
103 
104mcp_serve:
105  enabled: true
106  listen: 127.0.0.1:8787
107  auth_mode: token
108  auth_token_env: GAIT_MCP_TOKEN
109  max_request_bytes: 1048576
110  http_verdict_status: strict
111  allow_client_artifact_paths: false
112 
113retention:
114  trace_ttl: 168h
115  session_ttl: 336h
116  export_ttl: 168h
117YAML
118gait doctor --production-readiness --json
119```
120 
121Use production mode when gating real side effects in shared or customer-facing environments.
122 
123Local UI playground: [`docs/ui_localhost.md`](docs/ui_localhost.md) | Launch with `gait ui`
124 
125## See It
126 
127### Simple End-To-End Scenario
128 
129![Gait simple end-to-end tool-boundary scenario](docs/assets/gait_demo_simple_e2e_60s.gif)
130 
131Video: [`gait_demo_simple_e2e_60s.mp4`](docs/assets/gait_demo_simple_e2e_60s.mp4) | Scenario walkthrough: [`docs/scenarios/simple_agent_tool_boundary.md`](docs/scenarios/simple_agent_tool_boundary.md) | Output legend: [`docs/demo_output_legend.md`](docs/demo_output_legend.md)
132 
133See: [2,880 tool calls gate-checked in 24 hours](docs/blog/openclaw_24h_boundary_enforcement.md)
134 
135## What You Get
136 
137**Signed packs** — every run and job emits a tamper-evident artifact (Ed25519 + SHA-256 manifest). Verify offline. Attach to PRs, incidents, audits. One artifact is the entire proof. Export OTEL-style JSONL and deterministic PostgreSQL index SQL with `gait pack export`.
138 
139**Fail-closed policy enforcement** — `gait gate eval` evaluates a structured tool-call intent against YAML policy before the side effect runs. Non-allow means non-execute. Signed trace proves the decision. Script mode supports deterministic step rollups, optional Wrkr context enrichment, and signed approved-script fast-path allow.
140 
141**Incident → CI gate in one command** — `gait regress bootstrap` converts a bad run into a permanent regression fixture with JUnit output. Exit 0 = pass, exit 5 = drift. Never debug the same failure twice.
142 
143**Durable jobs** — dispatch long-running agent work that survives failures. Checkpoints, pause/resume/stop/cancel, approval gates, deterministic stop reasons, and emergency preemption for queued dispatches. No more lost state at step 47.
144 
145**Destructive safety boundary** — enforce phase-aware plan/apply behavior (`plan` stays non-destructive, destructive `apply` requires approval), plus fail-closed destructive budgets and bounded approval token scopes (`max-targets`, `max-ops`).
146 
147**Deterministic replay and diff** — replay an agent run using recorded results as stubs (no real API calls). Diff two packs to see what changed, including context drift classification.
148 
149**Voice agent gating** — gate high-stakes spoken commitments (refunds, quotes, eligibility) before they're uttered. Signed `SayToken` capability + callpack artifacts for voice boundaries.
150 
151**Risk ranking** — rank highest-risk actions across runs and traces by tool class and blast radius. Offline, no dashboard.
152 
153## Additional Adapters
154 
155[LangChain](examples/integrations/langchain/) · [AutoGen](examples/integrations/autogen/) · [AutoGPT](examples/integrations/autogpt/) · [OpenClaw](examples/integrations/openclaw/) · [Gastown](examples/integrations/gastown/) · [Voice](examples/integrations/voice_reference/)
156 
157## CI Adoption (One PR)
158 
159```bash
160gait regress bootstrap --from run_demo --json --junit ./gait-out/junit.xml
161```
162 
163- exit `0` = pass, exit `5` = regression failed
164- Template: [`.github/workflows/adoption-regress-template.yml`](.github/workflows/adoption-regress-template.yml)
165- Drop-in action: [`.github/actions/gait-regress/README.md`](.github/actions/gait-regress/README.md)
166- GitLab/Jenkins/Circle: [`docs/ci_regress_kit.md`](docs/ci_regress_kit.md)
167- Canonical copy-paste guide: [`docs/adopt_in_one_pr.md`](docs/adopt_in_one_pr.md)
168- Threat model: [`docs/threat_model.md`](docs/threat_model.md)
169- Failure taxonomy and exits: [`docs/failure_taxonomy_exit_codes.md`](docs/failure_taxonomy_exit_codes.md)
170 
171## Contract Commitments
172 
173- **determinism**: verify, diff, and stub replay produce identical results on identical artifacts
174- **offline-first**: core workflows do not require network
175- **fail-closed**: high-risk paths block on policy or approval ambiguity
176- **schema stability**: versioned artifacts with backward-compatible readers
177- **stable exit codes**: `0` success · `1` internal/runtime failure · `2` verification failure · `3` policy block · `4` approval required · `5` regress failed · `6` invalid input · `7` dependency missing · `8` unsafe operation blocked
178 
179Normative spec: [`docs/contracts/primitive_contract.md`](docs/contracts/primitive_contract.md) | PackSpec v1: [`docs/contracts/packspec_v1.md`](docs/contracts/packspec_v1.md) | Intent+receipt: [`docs/contracts/intent_receipt_conformance.md`](docs/contracts/intent_receipt_conformance.md)
180 
181Hardening: [`docs/hardening/v2_2_contract.md`](docs/hardening/v2_2_contract.md) | Runbook: [`docs/hardening/prime_time_runbook.md`](docs/hardening/prime_time_runbook.md)
182 
183## Documentation
184 
1851. [`docs/README.md`](docs/README.md) — ownership map
1862. [`docs/concepts/mental_model.md`](docs/concepts/mental_model.md) — how Gait works
1873. [`docs/architecture.md`](docs/architecture.md) — component boundaries
1884. [`docs/flows.md`](docs/flows.md) — end-to-end sequences
1895. [`docs/durable_jobs.md`](docs/durable_jobs.md) — durable job lifecycle and differentiation
1906. [`docs/contracts/primitive_contract.md`](docs/contracts/primitive_contract.md) — normative spec
191 
192Public docs: [clyra-ai.github.io/gait](https://clyra-ai.github.io/gait/) | Wiki: [github.com/Clyra-AI/gait/wiki](https://github.com/Clyra-AI/gait/wiki) | Changelog: [CHANGELOG.md](CHANGELOG.md)
193 
194## Developer Workflow
195 
196![CI](https://github.com/Clyra-AI/gait/actions/workflows/ci.yml/badge.svg)
197![CodeQL](https://github.com/Clyra-AI/gait/actions/workflows/codeql.yml/badge.svg)
198![Intent+Receipt Conformance](https://github.com/Clyra-AI/gait/actions/workflows/intent-receipt-conformance.yml/badge.svg)
199 
200```bash
201make fmt && make lint && make test
202make test-e2e
203make test-hardening-acceptance
204make test-uat-local
205```
206 
207Push hooks: `make hooks` | Full gate: `GAIT_PREPUSH_MODE=full git push` | Branch protection: `make github-guardrails`
208 
209Contributor guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
210 
211## Command Surface
212 
213```text
214gait demo                                         Create a signed pack offline
215gait tour                                         Interactive walkthrough
216gait verify <run_id|path>                          Verify integrity offline
217gait verify chain|session-chain                    Multi-artifact chain verification
218gait job submit|status|checkpoint|pause|resume     Durable job lifecycle
219gait job stop|approve|cancel|inspect               Emergency stop, approval, and inspection
220gait pack build|verify|inspect|diff|export         Unified pack operations + OTEL/Postgres sinks
221gait regress init|bootstrap|run                    Incident → CI gate
222gait gate eval                                     Policy enforcement + signed trace
223gait approve-script                                Mint signed approved-script registry entries
224gait approve                                       Mint signed approval tokens
225gait list-scripts                                  Inspect approved-script registry status
226gait delegate mint|verify                          Delegation token lifecycle
227gait report top                                    Rank highest-risk actions
228gait voice token mint|verify                       Voice commitment gating
229gait voice pack build|verify|inspect|diff          Voice callpack operations
230gait run record|inspect|replay|diff|receipt        Run recording and replay
231gait run session start|append|status|checkpoint|compact  Session journaling
232gait run reduce                                    Reduce runpack by predicate
233gait mcp proxy|bridge|serve                        MCP transport adapters
234gait gateway ingest                                Ingest MCP gateway logs into signed policy-enforcement proof records
235gait policy init|validate|fmt|simulate|test        Policy authoring
236gait doctor [--production-readiness] [adoption]    Diagnostics + readiness
237gait keys init|rotate|verify                       Signing key lifecycle
238gait scout snapshot|diff|signal                    Drift and adoption signals
239gait guard pack|verify|retain|encrypt|decrypt      Evidence and encryption
240gait trace verify                                  Verify signed trace integrity
241gait incident pack                                 Build incident evidence pack
242gait registry install|list|verify                  Signed skill-pack registry
243gait migrate                                       Migrate legacy artifacts to v1
244gait ui                                            Local playground
245gait version                                       Print version
246```
247 
248All commands support `--json`. Most support `--explain`.
249 
250## Feedback
251 
252Issues: [github.com/Clyra-AI/gait/issues](https://github.com/Clyra-AI/gait/issues) | Security: [`SECURITY.md`](SECURITY.md) | Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md) | Code of conduct: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
253