Your AI agent edits your code.
Your auditor will want proof of what it did.
The Audit chain is that proof.

What Audit does

The Audit chain is the forensic record of everything an AI agent does on your code. Every meaningful action, every file read, every diff written, every diagnostic run, every tool called, is captured as an entry in a cryptographically-linked chain. Each entry is Ed25519-signed with your device key. Each entry is anchored to RFC 3161, a legally-recognised time source. The whole chain can be verified, offline, on an air-gapped machine, by any third party who has a copy of the database. Hunk-level attribution down to the diff range. Six months from now, when someone asks *"which agent wrote this line, when, and was the record actually intact?"*, you have the answer, and they can verify it themselves without trusting you.

How it actually works

Twira's audit chain is the *forensic record* of everything an AI agent does on your code. Every meaningful action, every file read, every diff written, every diagnostic run, every tool called, is captured as an entry in a cryptographically-linked chain. Each entry is signed. Each entry is anchored to a legally-recognised time source. The whole chain can be verified, offline, on an air-gapped machine, by any third party who has a copy of the database. Six months from now, when someone asks *"which agent wrote this line, when, and was the record actually intact?"*, you have the answer, and they can verify it themselves without trusting you.

What is in every entry, 20 columns per action. Each audit entry captures the full forensic context of one action. The audit_events table carries twenty columns covering identity, content state, position in the chain, and cryptographic linkage:

• Who acted, agent_id (claude / gemini / codex / human), model_id (e.g. claude-opus-4-7), session_id.

• What happened, event_type (file_write / tool_use / approval / compliance_check), tool_name, file_path.

• What changed, content_hash_before, content_hash_after, diff_hash (SHA-256 of the patch).

• Where exactly, line_start, line_end, hunk_header (hunk-level granularity, not file, not commit; the actual diff range).

• Repository context, git_head (SHA at time of action), source (call site that wrote the event).

• Chain position, id, parent_event_id, previous_hash, chain_hash.

• Honesty signal, capture_fidelity enum, one of observed (direct capture from the hook), inferred (reconstructed from context), or declared (human-claimed without direct proof). A regulator can see at a glance how much each entry is worth as evidence.

• Time, created_at (ISO 8601 UTC).

Chain integrity, SHA-256 Merkle linkage. Each entry's chain_hash equals SHA-256(previous_hash ‖ canonical_json(this_entry)). The first entry hashes its canonical JSON alone (genesis). Tamper a single field in any entry and that entry's hash changes; the next entry's previous_hash no longer matches; every subsequent hash in the chain breaks. The whole chain falls apart at the first byte of tampering, you cannot quietly edit history. Canonical JSON ordering is deterministic (alphabetical field sort), so the same entry produces the same hash on every machine, every time. No ambiguity in verification.

Signing, Ed25519 device key. Manifests are signed with an Ed25519 device key generated on first run and stored under <data_dir>/. The public-key fingerprint is recorded with every signature. Anyone with the public key plus the signed manifest can verify (a) the manifest came from this specific device, and (b) the manifest has not been altered since signing. Standard public-key cryptography, the same primitive used in SSH, TLS, and code signing. Signature workflow: build canonical manifest JSON → strip the signature and extension fields → sign that canonical form → store the 64-byte signature plus key fingerprint alongside. Verification does the same canonicalisation on the receiving side and checks the signature.

RFC 3161 timestamping, legally-defensible time. Hashes alone prove that something happened in a certain order. They do not prove when. Twira solves that with RFC 3161 Time-Stamping Authority anchoring, the same standard the legal community already accepts for digital signatures, e-invoicing, and court-admitted electronic documents. A background scheduler creates checkpoints automatically: every 15 minutes by default, or whenever 100 new events have accumulated, whichever comes first. Each checkpoint sends the current chain tip hash to a TSA, receives a DER-encoded signed timestamp token in response, and stores that token in audit_chain_checkpoints alongside the merkle root. The TSA token cryptographically binds "this hash existed by this UTC time" and is countersigned by a trusted authority. Forging it would require breaking the TSA's signing key, which is not a thing one does.

Hunk-level attribution, line-range granularity. Most version-control tooling attributes at file or commit granularity. Twira goes one level finer: every entry records line_start, line_end, and hunk_header. When someone asks "who decided this specific block of code?", the chain answers at the line range, not just "some commit touched this file". A three-tier resolver provides fallback: (1) line-level match in the audit table, (2) file-level latest event, (3) declared or unattested status if no audit activity exists. Coverage percentages are computed per file. This is what makes the chain useful for merge disputes, code-review accountability, and AI-versus-human attribution in regulated environments.

Verification, fully offline, no Twira infrastructure. This is the property that matters most to compliance buyers and auditors: the chain verifies itself. A third party with a copy of audit.db plus the verifier code can iterate every entry in order, recompute every hash, validate every Ed25519 signature, and check every TSA token, without any network access, without any call to our servers, without trusting us at all. The verification is a pure cryptographic computation. This matters in two scenarios: (a) air-gapped environments where outbound network is forbidden by policy (defence, healthcare, finance); (b) adversarial verification, your auditor, regulator, or insurer doesn't have to take your word for it; they verify themselves on their own machine. CLI: twira audit verify returns { valid, broken_at, event_count }. Dashboard equivalent: POST /api/v1/audit/verify/:session_id.

What triggers an audit write. Three trigger paths, all automatic, you do not write to the chain manually:

• MCP post-tool hook, fires after every tool invocation by an AI agent. Captures tool_name, the output, the diff hash, capture_fidelity = "observed".

• Git hooks, pre-commit validates audit state before the commit lands; post-commit records the human commit with author metadata.

• Dashboard actions, any state-changing call through the dashboard backend writes through the same AuditStore::append_audit_event path, so dashboard activity is part of the same forensic record.

The CLI command twira audit is read-only, it inspects, verifies, and exports; it does not write. The audit chain is written by the tools the agent uses, never by the agent narrating about itself.

Provenance manifest, the export artefact. When you run twira audit export --bundle, the output is a JSON-LD provenance manifest plus the underlying signed entries. The manifest records per-file attribution with a fidelity status drawn from a wider five-value set than the per-event column, Observed (audit event found for this file), Inferred (reconstructed from context), Declared (human claim, no direct audit), Unattested (audit was active but no event matched the file), or Unknown (file unreadable). The manifest is signed with the device key and includes the merkle root of the chain tip plus the latest TSA timestamp. Hand the bundle to an auditor, regulator, insurer, or customer asking compliance questions. They verify it on their own machine.

Append-only, the honest DSAR limitation. The audit chain cannot delete individual entries. This is by design: deletion would break the merkle linkage and invalidate the chain. If you need GDPR right-to-erasure for content the agent saw, that work happens upstream at the AI Compliance Proxy, where personal data is redacted before it ever reaches the model or the audit log. The audit chain itself records that an action happened; it does not store the personal data the action involved. For long-running deployments, archive old sessions to cold storage (with their signed manifests intact for later verification) and keep only recent activity in the active audit.db. Retention and archival replace deletion.

Audit vs Compliance Proxy, two different questions answered by the same Pro subscription. The audit chain records what the agent did, every action, every diff, every tool call, hunk-level attribution, signed and Merkle-linked. The AI Compliance Proxy controls what data crosses to the LLM provider, wire-layer redaction, reversible token substitution, provider-key custody. Both are part of Twira Pro. You typically use both: the chain says "this agent called this tool with this redacted payload at this time and got this response"; the proxy ensures the payload was redacted before the call. Together they answer both what-happened and what-data-was-involved.

What standards and controls this contributes to. Twira's audit chain is one control an organisation can use to evidence specific framework requirements. We do not certify your organisation against any standard, your auditor does that against your full control environment. With that caveat, here is the honest map:

• ISO/IEC 27001:2022, A.8.15 (Logging) + A.5.28 (Collection of evidence). Direct fit. A.8.15 requires logs of activities, exceptions, and faults that are "produced, stored, protected, and analysed", the cryptographic chain is the protected property. A.5.28 covers the preservation of evidence, append-only plus signed manifests is exactly that.

• ISO/IEC 42001:2023, A.6.2.8 (Recording of event logs). The AI Management System standard explicitly requires event-log recording across the AI system lifecycle. This is the cleanest single map Twira offers.

• SOC 2 (AICPA TSC), CC7.2 + CC7.3 + CC4.1. CC7.2 (anomaly detection on AI behaviour), CC7.3 (incident analysis), CC4.1 (control effectiveness). Auditors value evidence that cannot be retconned; a signed chain is unusually strong evidence for CC4.1.

• NIST AI RMF 1.0, MEASURE 2.8 (transparency + accountability) + MANAGE 4.1 (post-deployment monitoring). Voluntary US framework, increasingly used as a governance reference. Twira produces the artefacts these subcategories ask for.

• FedRAMP / NIST 800-53 Rev. 5, AU-2 (event logging) + AU-9 (protection of audit information from modification) + AU-11 (retention). AU-9 is the "integrity of audit info" control; cryptographic chaining maps to it almost exactly. Useful for US federal-sector teams adopting AI coding agents inside an authorisation boundary.

Sector-specific (when in scope only):

• HIPAA §164.312(b) Audit Controls, when AI agents touch systems handling electronic Protected Health Information. 6-year retention per §164.316(b)(2)(i).

• PCI DSS v4.0 Requirement 10.3, tamper-evident audit trails for code in the cardholder data environment. 12-month retention with 3-month immediate-access. The cryptographic chain is the canonical tamper-evidence mechanism Req. 10.3 calls for.

• SOX §404 IT General Controls, change attribution for code in public-company financial-reporting systems. Auditors typically want 12–18 months of continuous evidence; hunk-level attribution of which agent wrote which line is direct ITGC change-management evidence.

EU AI Act, the honest scope hedge. The Act's hard logging obligations (Articles 12, 19, and 26) apply specifically to providers and deployers of high-risk AI systems as defined in Annex III (biometrics, critical infrastructure, education, employment, essential services, law enforcement, migration, justice). Software development is not one of the eight high-risk domains. A Claude Code session on a generic codebase is not a high-risk AI system under the Act. Where Twira's audit chain does help: (a) when your deployed product is a high-risk AI system and AI agents touched its code, the chain is the evidence shape Article 26(6) deployer obligations require (6-month minimum retention); (b) as voluntary forward-positioning, when the Act's scope expands, you already have the evidence shape ready. Honest framing: "helps deployers of high-risk AI systems evidence Article 26(6) recordkeeping", never "makes you EU AI Act compliant", because the Act doesn't certify products this way, and the obligations don't bite for most engineering teams.

What we will not claim. These overclaims are off the table:

• ✗ "GDPR compliant", wrong product surface. GDPR's lawful-basis and data-protection obligations are about content. That work happens at the AI Compliance Proxy, not the audit chain. The audit chain is a recordkeeping control, not a data-protection control.

• ✗ "EU AI Act compliant", the Act doesn't certify products this way; the obligations don't bite for most users; we provide evidence shape, not legal opinion.

• ✗ "SOC 2 certified", companies are SOC 2 attested, not products. Twira provides evidence that supports your attestation.

• ✗ "Court-admissible", admissibility is jurisdiction-specific and case-by-case. "Cryptographically signed and verifiable offline" is the honest, defensible claim.

• ✗ Any claim that Twira satisfies a control on its own, it contributes evidence to a control the customer owns.

Tier, Pro. The audit chain is Pro-gated. The tamper-evident, cryptographically-signed activity record is the highest-value compliance-buyer surface Twira ships, alongside Lore, Masterplan, and the AI Compliance Proxy, all part of the Pro toolbelt. On Free, the audit chain does not run: no audit.db accumulates, no entries are written. The moment you upgrade (twira login), the chain starts from that point forward. There is no historical reconstruction; activity from before the upgrade is not retroactively recorded. Activate Pro before the work you want recorded, not after.

On Pro, the full surface: every meaningful agent action signed, linked, RFC 3161 timestamped; offline twira audit verify; hunk-level attribution; identity management; JSON-LD provenance manifest export; compliance-export bundle workflow (signed bundle plus JSON, CSV, and PDF); retention policies; at-rest encryption for the local audit database; auto-archival; and the dashboard surface (/api/v1/audit/* endpoints plus the browser inspector at /audit).

Setup. With Pro active, twira init creates <project>/.Twira/audit.db on the first audit-triggering action and generates the device key. Hooks are wired into your coding agent automatically. No further configuration required. Without Pro, all audit subcommands fail with the upgrade hint; the dashboard /api/v1/audit/* endpoints return HTTP 402 Payment Required with the same hint.

Footer disclosure for every compliance buyer: Twira's audit chain is one control among many. It does not by itself make any organisation compliant with any regulation or standard. Compliance is determined by your auditor against your full control environment. The audit chain provides the evidence shape, what your auditor does with that evidence is between you, your auditor, and your regulator.

What it isn’t

• ·Append-only, individual entries cannot be deleted (deletion would break the merkle linkage). GDPR right-to-erasure for personal data happens upstream at the [AI Compliance Proxy](/tools/gateway), before content reaches the chain.
• ·Provides *evidence shape*, not compliance certification. The chain contributes one technical control your auditor evaluates against frameworks like ISO 27001 A.8.15 or SOC 2 CC7.2. It does not by itself make any organisation compliant.
• ·Activates from Pro upgrade forward, no historical reconstruction. Activity from before the upgrade is not retroactively recorded.
• ·Not callable from the agent loop, by design. Writes happen via MCP `post-tool` hook, git hooks, and dashboard actions. The chain is written by the *tools the agent uses*, never by the agent narrating about itself.
• ·Court-admissibility is jurisdiction-specific. The honest claim is *"cryptographically signed and verifiable offline"*, not *"court-admissible"*.