Governed CLI for AI agents: epistemic operations + verifiable receipt chains.
Agents spend fewer tokens rediscovering state and more tokens reasoning.
Ableman Constitutional Systems — ableman.research@gmail.com
Most agent tooling evolved from Unix ergonomics. Tools are organized around filesystem operations:
read write grep find edit
AbleTools is organized around epistemic operations:
orient identify seek claim refute surface posture
Conventional tools return raw output. AbleTools returns governed semantic receipts that allow agents to reason over state transitions without repeatedly consuming the full underlying artifacts.
The agent loop changes:
Traditional AbleTools
Agent Agent
↓ ↓
tool call tool call
↓ ↓
large raw output semantic receipt
↓ ↓
reason reason
↓ ↓
tool call again (rediscovery) tool call (new work)
↓ ↓
large raw output again semantic receipt
The receipt is a stable address. The agent cites it, reuses it across sessions, and audits it later. Raw output is transient — once the context window moves on, it is gone.
Demonstrated across 80 constitutional analyses of production software systems, 722 gate tests passing. See the CSoftA corpus.
AI agents waste compute and tokens in two recurring ways:
- State rediscovery — re-running operations to find out what was already known, because prior results were not addressed and stored.
- Verbose raw output — tool calls that return more text than the agent needs to reason, forcing downstream re-parsing and re-summarization.
AbleTools replaces verbose, Unix-shaped tool output with compact, receipt-bearing operations. Every operation produces a receipt ID. Claims reference those receipts, creating an auditable chain from assertion → evidence → operation.
Unix tools return text. AbleTools returns addresses.
Unix: find /corpus -name "*.py" → /long/path/file1.py
/long/path/file2.py
... (80 lines)
AbleTools: able_seek --name "*.py" → seek:corpus:80files:hash:a4f19c3e
The AbleTools output is a stable reference. The agent can cite it in a claim, reuse it next session, and audit it later. The Unix output is transient text — once the context window moves on, it is gone.
Governed — every operation produces a receipt and can be audited later. The receipt is constitutive of the operation: a tool invocation that cannot write its receipt does not complete.
A receipt is not a log entry. It is a structured reference to what happened, what changed, and what state was produced.
Hashing a file:
hash:METHODOLOGY.md sha256:de07d9c1f4389e09f8c5688ceb2768bf
The agent knows the file identity without re-reading it. If the hash changes next session, the agent knows state changed.
Navigating a corpus:
manifest:vault-constitutional-analysis 13files [7md 6py] hash:2b9d628b
File count, type breakdown, and a content fingerprint — in one addressable reference. The agent does not re-scan the directory.
Session posture:
posture:10523r:0i:high:148c
Receipts, open issues, confidence tier, claims count. The agent knows its session state without querying four tables.
The receipt tells the agent: what artifact was involved, what state was observed, and what the fingerprint is — without re-reading the underlying content. That is what reduces repeated retrieval of unchanged state.
Operation runs → receipt written to ugk.db (GR:gov_<hex>)
↓
Claim made → linked to GR:gov_<hex> → stored in claims.db
↓
Session audited → full chain: assertion → evidence → operation
Without receipts:
Agent: "I found evidence that vault-system is ACTIVE."
No trail. No verification. If the session ends, the reasoning is gone.
With receipts:
Claim: "vault-system: audit device present, ACTIVE governance confirmed"
→ evidence: GR:gov_5bf69122213b
→ operation: seek:csofta:1files:hash:a4f19c3e
→ hash: hash:METHODOLOGY.md:sha256:de07d9c1
Every conclusion is tied to the operation that produced its evidence. The investigation is an auditable graph, not a conversation thread.
python acis doctorExpected output on a clean install:
acis doctor — 11 OK / 0 FAIL
OK manifest.json readable: 67 tools declared, 55 functional
OK ugk.db accessible: 0 receipts
OK claims.db accessible: 0 claims
OK governance.kernel importable: ok (lite mode — null_kernel active)
OK null_kernel importable: ok
OK mcir verify: INTACT Chain intact — 44 events verified.
OK compute smoke
All checks passed. Session is operational.
In corpus-oriented workflows, tools that return structured semantic references produce substantially less output than their Unix equivalents. Measured on the 80-system CSoftA corpus, identical navigation tasks, same file tree:
| Operation | AbleTools | Unix equiv | Reduction |
|---|---|---|---|
able_manifest vs find -type f |
79 chars | 938 chars | 92% smaller |
able_where vs grep -rn |
312 chars | 2,947 chars | 89% smaller |
able_hash vs sha256sum |
60 chars | 101 chars | 41% smaller |
able_seek vs find -name |
5,020 chars | 6,600 chars | 24% smaller |
| 5-op navigation aggregate | 5,543 chars | 10,663 chars | 48% smaller |
These measurements reflect receipts reducing repeated retrieval of
unchanged state. The compression works because each tool produces a
structured output_ref that carries the semantic meaning of the
operation without the content.
Compression targets verbose raw output that wastes tokens. Expansion
targets sparse raw output that loses meaning. able_posture is
intentionally larger than a raw sqlite query because it adds
interpretation — receipt count, open issues, confidence tier, claims
count.
able_posture — session state at a glance:
posture:10523r:0i:high:148c
WARNINGS: 130 claims without gap analysis
One addressable reference. No table queries.
able_seek — find files, get an address:
root:csofta 1files
vault-constitutional-analysis/impl/ear_adapter_vault.py
Navigation output structured as a stable reference.
able_claim — make a receipted assertion:
python acis claim \
--scope scp_42b02f4cee3d \
--claim "vault-system: audit device present, ACTIVE governance confirmed" \
--evidence "GR:gov_5bf69122213b" \
--gap-checked \
--intent synthesizeThe claim is not made until the evidence receipt exists.
- Long-running coding agents that lose context across tool calls and need persistent, addressable state
- Multi-session agent workflows where an agent needs to resume from exactly where it left off
- Agent observability and audit systems where every tool call needs to be inspectable after the fact
- Autonomous research pipelines — corpora, evidence graphs, governed analysis at scale
- LLM tooling platforms building an agent infrastructure layer that needs verifiable, addressable operations
Portable — no external services, no cloud dependency, no configuration step beyond extraction:
tar xzf abletoolslite_v0.1.0.tar.gz
cd abletoolslite
python acis doctorOr install as a package:
pip install .
python acis doctorRequires Python 3.10+. Runs on Linux, macOS, and Windows PowerShell.
# Orient to current session state
python acis orient --intent orient
# Navigate
python acis seek --name "*.py" --root . --intent orient
python acis manifest --root . --intent inspect
python acis hash myfile.py --intent orient
# Make a receipted claim
python acis scope --corpus my-corpus --intent synthesize
# Returns: scope:scp_<id>
python acis claim \
--scope scp_<id> \
--claim "my-system passes governance gate" \
--evidence "GR:gov_<receipt-id>" \
--gap-checked \
--intent synthesize
# Record a gate test result
python acis gate record \
--system my-system \
--fingerprint abc123def456 \
--passed 9 --total 9 \
--intent synthesize55 functional tools across 16 families. Every tool requires
--intent <value> — the declared intent is part of the receipt.
Full documentation in SKILL.md. Full catalog in the appendix below.
67 tools are declared in the manifest. 55 are functional in this distribution.
12 tools are not available in Lite:
11 require a Constitutional Meaning Base (CMB) spine:
able_receipt_diff, able_trace, able_replay, able_pressure,
able_census, able_metabolize, able_gc, able_weather,
able_delete, able_operator, able_preconditions
These perform corpus mutation, semantic graph traversal, and receipt diffing over a CMB substrate. They return a clear error if invoked.
1 is pending its release gate:
able_publish
governance/ugk.db — one row per tool invocation:
op_id— receipt ID (reference asGR:gov_<hex>)op_name— tool nameintent— declared intentstatus— OPEN | COMPLETED | FAILEDtimestamp— ISO 8601 UTC
governance/claims.db — analytical claims with evidence chains
governance/mcir.db — MCIR provenance chain (44 events, pre-verified)
- CMB-coupled tools available when a spine is present (
able_trace,able_census,able_pressure) able_publishcompleting its release gate- Expanded
able_computesurface for corpus analysis workflows - MCP server wrapper for direct integration with Claude and other agents
AbleTools is local-only. It makes no network calls, connects to no
cloud services, and sends no telemetry. All state is written to SQLite
files in the governance/ directory.
Mutation verbs (able_exec, able_remove, able_create,
able_patch, able_commit, able_mkdir, able_copy, able_link)
execute real filesystem and shell operations. They are not sandboxed.
Each mutation requires a declared --intent and writes a receipt, but
the receipt does not prevent the operation — it records it.
What the receipt chain gives you: an auditable log of every operation that ran, with declared intent and output reference. What it does not give you: sandboxing, rollback, or permission enforcement.
Recommended practice for agent use:
- Run AbleTools in a directory the agent is authorized to modify
- Review
acis audit --intent verifyafter any session involving mutation verbs - Do not run with elevated privileges unless required by the task
The governance database (ugk.db, claims.db) is local SQLite. It
is not encrypted. Do not store sensitive data in claim text or
evidence references.
The CSoftA corpus demonstrates AbleTools in production use across 80 constitutional analyses of production software systems — Vault, Kubernetes, PostgreSQL, GitHub Actions, and 76 others. Every analysis was produced using AbleTools. Every gate test produces a JSON receipt. The methodology is published and independently verifiable.
https://github.com/AblemanMosaic/CSoftA-Canonical
- 80 systems analyzed, 722 gate tests passing
- Session hash
c2e4a49a6a18be8f5fb91b34430438a7covers all 80 fingerprints - Methodology paper: https://doi.org/10.5281/zenodo.20472195
- Governance remediation recommendations: CLOSING_THE_GAP.md
Ableman Constitutional Systems
ableman.research@gmail.com
https://github.com/AblemanMosaic
Code (.py files): Apache License 2.0
Documentation (.md files): CC BY-ND 4.0 International — see LICENSE-DOCS.md
© Ableman Constitutional Systems
| Family | Tools |
|---|---|
| Navigation | able_seek, able_view, able_where |
| State | able_hash, able_manifest, able_stat, able_env, able_state |
| Transition | able_change, able_compare, able_lineage, able_timeline |
| Evidence | able_claim, able_scope, able_gap, able_refute, able_bundle |
| Governance | able_audit, able_conform, able_policy, able_posture |
| Mutation | able_commit, able_copy, able_create, able_exec, able_mkdir, able_patch, able_remove, able_link, able_distill |
| Memory | able_archive, able_bridge, able_extract, able_memory |
| Semantic | able_anchor, able_index, able_resolve, able_surface, able_zoom |
| Projection | able_orient, able_project, able_render |
| Metacognitive | able_budget, able_delegate, able_identify |
| Diagnostics | able_test |
| Compute | able_compute |
| Environmental | able_fetch, able_watch |
| Paper pipeline | able_canon, able_lint |
| Gate tests | able_gate |
| Other | able_condex, able_read, able_mcir |