Add a Go Guardian reference implementation

[President]

Closes #87. A Guardian written in Go. It is in reference-implementations/agt-go/, next to the TypeScript Guardian.

I compared the two Guardians on the same sessions

The policy files are the same. Both Guardians read the AGT Rego files in this repository. By default the Go Guardian runs them with the AGT runtime itself: AGT's Rust library, linked through its C ABI (cgo), built from source at the commit agt-native.lock pins. A test requires that commit to be the one agt/agt.lock pins for the policy bundle. EVALUATOR=go builds without cgo and runs the same files with the OPA Go library instead.

I wrote 49 test sessions and recorded the TypeScript Guardian's answers to them. Then I sent the same steps to the Go Guardian, signed, the way an agent sends them, once with each evaluator.

Compared	Sessions	Steps	Different
disposition, reason codes, policy references, reasoning, modifications	49	53	2, both declared

Two declared exceptions, both in docs/differences.md. When the engine fails, both Guardians deny with evaluation_failed, and each writes its own reasoning. And in two sessions the policy target is not a string: the Go Guardian denies it, as the TypeScript fix in #229 does, while the recording still holds the old ALLOW. The test fails once a new recording carries that fix, so the exception cannot outlive it.

The recorded file also stores the Git object IDs of the TypeScript paths that decide an answer: the Guardian and bridge sources, mapping.yaml, the policies, agt.lock, and the bridge's package.json, which pins the AGT SDK. The test TestRecordingIsCurrent compares them with the current ones. Object IDs depend only on content, so a squash merge does not change them. If someone changes that code, this test fails, and the sessions have to be recorded again with scripts/record-ts-cases.sh.

What it does

cmd/guardian is a program. You run it next to an agent. make run starts it with guardian.yaml. It uses AGT as its policy engine. make agt-native builds AGT's library and fetches opa; docs/building.md covers Linux, macOS and the Windows cross-build. Each decision under AGT runs one opa process, so make load measures latency and memory under concurrent clients; docs/load.md has the results behind the shipped limits.max_engine_calls. The HMAC secret file holds base64 of at least 32 bytes, under a configured key_id; the audit logs rotate by size; docs/configuration.md lists every setting, and docs/conformance.md maps each expectation of #256 to its tests.

guardian is also a Go library. You give it four things: the policy engine, the keys, the session storage, and the place to write the audit log. CONTRIBUTING.md leaves the policy engine and the signature algorithm to deployments. The library treats storage and the audit log the same way, so it takes each of the four as an interface. examples/custom-engine is a second Go module. It gives its own four and answers a step.

What checks each claim

Claim	What checks it
ACS-Core is met	docs/conformance.md has one row per item. Each row names its tests. make docs-check fails if a named test does not exist.
The specification decides	The schemas inside the module are compared byte for byte with the files in specification/v0.1.0/. The test reads those files by relative path, so if the specification changes, the test fails.
Signatures are correct	A second verifier reads every response. It was written separately from the signing code and has its own RFC 8785 canonicalizer. It refuses a deny that was changed to an allow. It also refuses a response signed with the key of another session.
The canonical form is RFC 8785	It is checked against the vectors published by the author of RFC 8785, and against the first 5000 ES6 number vectors.
The two Guardians meet	The TypeScript conformance runner sends requests over HTTP to the Go Guardian while it runs. This happens every time the checks run.

docs/conformance.md says what it claims and what it does not claim. ACS v0.1.0 has no certification, so the claim is a self-declaration, and each row names the test that covers it. docs/differences.md lists every difference from the TypeScript Guardian.

What I ran

uv run pytest -v passes, 913 tests. uv run mkdocs build --strict passes.

make check in the module runs gofmt, go vet, Staticcheck, govulncheck, the tests with the race detector, the examples/custom-engine module, the Codex and OpenCode adapter tests, the shared conformance check against a Guardian that is running, the coverage check, and make docs-check. It passes. Coverage of the protocol packages, the evaluators, the host adapter and the test Observed Agent, with the AGT evaluator built in, is 85.9%. The floor is 80%.

Two defaults you may ask about

on_decision_failure. The library keeps the default from §6.4, which is proceed. The guardian.yaml in this repository sets deny. So the Guardian you can run here blocks the step when it cannot decide.

Two Codex settings in make codex-example. -s workspace-write stops Codex from asking the person about each command, so the Guardian is the one that decides. Codex also asks once whether it may run the hook file of this project, and --dangerously-bypass-hook-trust skips that question. Both settings apply only to the Codex program that this command starts. examples/codex/README.md says what each one opens.

Examples

examples/codex/ and examples/opencode/ show that a host uses the decision the Guardian sends. make codex-example and make opencode-example start the real Codex and OpenCode programs. make check does not start them. It sends recorded host events to the same adapter code. When reference adapters for these hosts are added, these examples can point to them.

Files outside the new directory

There are seven. Two are under .github/: the Go job, .github/workflows/reference-implementation-go.yml, which also runs weekly so govulncheck sees new advisories, and the gomod entries in .github/dependabot.yml. The agt/README.md change updates its count of test files, rewords the two sentences around it, and tells a TypeScript contributor when to re-record the answers the Go Guardian replays.

The other four add one check to the TypeScript conformance runner. The check sends signed requests over HTTP to any Guardian and reads the answers. It works for any Guardian, not only this one. That is why it sits next to the runner and not inside the Go module.

• packages/conformance/src/external-guardian.ts is the check.
• packages/conformance/test/external-guardian.test.ts is its test.
• packages/conformance/src/main.ts calls the check and prints whether it ran.
• package.json adds the conformance:guardian script.

[President]

@afogel @rocklambros Following today's call I reorganised the docs so the review can go in two steps.

1. Agree on the architecture: docs/architecture.md. It shows the parts, the four interfaces, and a diagram for each path a request takes.
2. Then review the code against it, in the order at the end of that page.

No code changed. Happy to answer questions while you go through it.

[shivang-sec]

I completed an independent substantive review of the Go Guardian against the ACS v0.1.0 requirements and existing TypeScript Guardian behavior. I checked the handshake/envelopes, duplicate request_id handling, chain hashing, all five dispositions, MODIFY/ASK/DEFER behavior, replay/skew handling, HMAC, session and chain handling, intent immutability, decision honoring, system/ping, wrapped MCP, PolicyEngine/delegate_to, hook-specific behavior, failure/state consistency, concurrency, TypeScript↔Go parity, external Guardian wire behavior, AGT bridge parity, ACS-Core vectors, and the existing #160–#167 regression areas.
I also checked the PR CI; all checks are passing. I did not identify a new substantive finding; the behaviors I reviewed were either conformant or already covered by existing tests/findings.
Conclusion: no new finding from my review.

[Mayur021]

Not a review of the Go implementation, I have not read it at that depth. But I did check it against the six reference-Guardian bugs in the #160 to #167 range, and each one has a named mechanism here.

Capability enforcement returns -32003, and the handshake narrows the client's methods_implemented to what this Guardian actually evaluates, with a later step on an unnegotiated method refused as not negotiated (#160). The JSON-RPC boundary is validated before the envelope is interpreted or a signature is checked, returning -32600 with invalid_jsonrpc_request, so a JSON-RPC-level failure no longer arrives as an envelope error or as a deny (#163). Step traffic on a session that has not completed handshake/hello is refused the same way (#164). transports_supported is read rather than ignored: no overlap with the transport this Guardian serves is a SESSION_REFUSED with transport_unsupported, instead of asserting http regardless (#165). A step naming an agent other than the one that opened the session is denied with agent_id_not_bound (#166). And steps/sessionStart dispatches against its own payload rather than falling through to method-not-dispatched (#167).

Worth adding that the wire here is authenticated. Anything other than system/ping is rejected unsigned, and hmac_signer.go derives a per-session key with HKDF-SHA256 and compares with hmac.Equal, which is #70. It also writes down the HKDF parameter choice that section 10 leaves open, which is part of what #118 asks for.

All of those are filed against the TypeScript reference, so they stay open on it. But a second implementation that does not reproduce them is useful evidence for what the reference should be doing, and every claim above is cheap to re-check from the name.

[President]

Merged integration (with #21) into this branch and updated the code for it:

1. updated our copy of hooks/subagent-stop.json: final_chain_hash is optional now
2. Codex/OpenCode adapters: if a MODIFY can't be applied (§6.5) or is broken (§6.3), they deny it and write it to the audit log
3. docs: removed the "open PR Set the ACS-Core floor: MODIFY and system/ping to SHOULD, Wrapped MCP and subagentStart as conditional MUSTs #21" notes, now they point to the spec sections

The Guardian works the same as before.

[Mayur021]

Re-checked the eight against 2b8ccf5 after the merge, since my earlier note named code at 158243d. All still hold: -32003 for the unnegotiated method and for a session lookup no handshake negotiated, -32600 with invalid_jsonrpc_request ahead of the envelope and the signature, the transport refusal, agent_id_not_bound, steps/sessionStart in the method table, and hmac.Equal over the HKDF-derived key.

On the section 6.5 change, the postCompact exception does not bite here. RefuseModification always answers DENY, which would be wrong at postCompact where DENY is not a legal disposition and the client is meant to keep the original summary. But the Codex adapter wires only steps/toolCallRequest and the OpenCode one adds steps/toolCallResult, so that hook never reaches it. Worth a comment at the call site if either adapter grows a compaction hook later, because the rule reads naturally as universal and the exception is one paragraph away from it.

One thing the merge changed in this PR's favour. The acs-core row #21 landed now names replay protection and a baseline HMAC-SHA256 signature in the mandatory column. Those are the two things this tree has and the TypeScript reference discloses as absent, so the floor moving today made the gap between them wider rather than narrower.

[President]

@Mayur021 @artmaro - pushed an update:

1. postCompact (Mayur's note): fixed in code, not only a comment. At the 5 hooks where DENY is not allowed (the action already happened), the adapter now lets it through and writes the refusal to the audit log. This replaces "they deny it" from my comment on 5 Oct.
2. Real AGT (Evgeniy's ask): the Guardian now decides with Microsoft's AGT library (same version the TS reference pins), called through its C ABI. Our Go evaluator stays as an option (EVALUATOR=go, builds without cgo) - both run the same recorded cases and must match.
3. Go 1.27.2 + x/net v0.60.0 - fixes GO-2026-6605 and GO-2026-6617.
4. Merged latest integration. CI runs on Linux amd64/arm64 and both Macs.

[rocklambros]

@President, a heads-up about your embedded spec copy. This PR is based on db5c89e, which is older than #63. The copy of trace/otel-mapping.json and trace/ocsf-mapping.json under internal/schema/specification/ therefore already differs from integration. TestSchemasMatchSpecification will fail the next time this PR's CI runs. The green checks shown now come from the old base.

Three more spec PRs touch the same files: #258 is open, #261 is open, and the #228 change is waiting on those two. Each one changes the copy again. Please rebase on integration, run cd reference-implementations/agt-go && go generate ./internal/schema, and push. If any of the three lands after you, I'll run the same command in that PR, so the order doesn't matter.

[rocklambros]

@President, I went through the commits from 9 October, since every review on this thread so far was done on 5 October against 2b8ccf52. That means fee41d41 (proceed where DENY is not allowed) and 470dd21a (AGT through the C ABI) haven't had a review yet. I merged this branch onto current integration (185ef4e) and ran the Go tests there with Go 1.27.2. Here's what needs to change before it can merge.

1. The embedded spec copy fails on the merged tree. TestSchemasMatchSpecification reports that trace/ocsf-mapping.json and trace/otel-mapping.json differ, because PR #63 changed both. This is the same ask as my earlier comment: rebase on integration, run cd reference-implementations/agt-go && go generate ./internal/schema, and push. After go generate, every package and go run ./cmd/docs-check passed for me.

2. TestRecordingIsCurrent will go red on integration after every TypeScript Guardian merge. agtbridge/recorded_cases_test.go:139-145 compares the recording with git log -1 --format=%H for the TS paths. We squash-merge into integration, so even if a TS author re-records inside their own PR, the squash creates a new SHA and the test fails right after merge. I checked this by adding a no-op commit under agt/packages/guardian/src on the merged tree, and the test failed. Four open PRs touch that path today (PR #244, PR #246, PR #229, PR #112). Please record tree IDs instead of a commit, for example git rev-parse HEAD:reference-implementations/agt/policy for each path, both in scripts/record-ts-cases.sh and in the test. Tree IDs are content-addressed, so they survive a squash.

3. opa_timeout can equal decision_timeout, and guardian.yaml ships both at 5s. AGT runs one opa process per decision and cannot be interrupted (agteval.go:279-281), so when OPA is slow the agent's 5s deadline expires before AGT's own fail-closed deny arrives. A deployment that negotiated proceed then runs the tool ungoverned. validate() in cmd/guardian/main.go already enforces write_timeout > decision_timeout at line 290. Please add the same kind of check for the agt evaluator (opa_timeout must be less than decision_timeout), set opa_timeout: 4s in guardian.yaml, and add a row to evaluator_test.go for it.

4. At hooks where DENY is not allowed, a failed decision plus a failed audit write now proceeds with no record anywhere. That's in internal/hostadapter/client.go:155-157, and client_test.go asserts it as post_compact_audit_unwritten. ALLOW is the right answer at postCompact, but §6.4 says the bypass "MUST be recorded". Please print one JSON line to stderr when recordAuditEvent fails, and extend that test to check for it. In the same commit, the §6.3 row in docs/conformance.md still says "Met", even though an invalid MODIFY at those five hooks now gives ALLOW and not DENY. I think your reading is right, but it's an interpretation, so mark the row that way and add a line to docs/differences.md. I'll open a spec issue to put the postCompact exception into §6.3.

5. The PR body describes the code from before 9 October. It says the Go Guardian uses the OPA Go library, but the default is now evaluator: agt through cgo, and EVALUATOR=go is the fallback. It also says five files sit outside the directory, but there are six (agt/README.md changed). The 279 tests and the 87.5% figures are old too. Reviewers judge the design from the body, so please update it.

These aren't blockers, but they'd be nice in this PR or a follow-up:

• Add a test that agt/agt.lock and agt-native.lock name the same AGT ref. Right now each evaluator only checks its own lock file, so an AGT bump can leave the default evaluator behind.
• scripts/check-coverage.sh leaves out agtbridge/agteval and internal/hostadapter, so the 80% floor measures the non-default path.
• max_engine_calls: 256 made sense in-process. Under agt each slot is an OS process, so a lower default for agt would be safer.
• refusalAt depends on the Decision lines in hooks.md, but method_test.go:50 only checks the count. A test that reads the Decision lines from docs/spec/instrument/hooks.md would catch a disposition change.

I also checked a few things that came out clean: AGT reads the OPA env vars once at build time, an unknown evaluator value fails validate(), and AGT's FFI wraps every call in catch_unwind.

[rocklambros]

@President, one more thing I forgot in the review, and it isn't a blocker. Once this merges, nothing will propose updates for the Go module. .github/dependabot.yml only covers github-actions and uv, and the Go workflow has no schedule:, so govulncheck runs only when someone touches the path. You found GO-2026-6605 and GO-2026-6617 by hand. Please add gomod entries for /reference-implementations/agt-go and /reference-implementations/agt-go/examples/custom-engine, using the same weekly schedule and cooldown: default-days: 7 as the existing entries. It's a .github/ change, so I'll approve that part.

[github-actions]

This pull request's description says it closes #87, which is on the project roadmap. When it merges, GitHub closes that issue and the roadmap counts it as delivered. Please confirm the change delivers the whole issue before merging.

[President]

@rocklambros thanks for the review! Everything is in commit e233a35. Answers in your order:

Schema copy is out of date

• I merged the latest integration into the branch and ran go generate. The copy matches the spec again. I used a merge, not a rebase, so the commits you already reviewed did not change.
• [Bug]: acs.decision trace event cannot carry reason_codes, policy_references, cited_provenance_ids, or chain_hash, so replay from the trace alone is not possible #228: agreed, whichever PR merges second runs go generate.

Review

1. Schema copy: done, see above.
2. TestRecordingIsCurrent breaks on squash merges: fixed. The test now compares the content of the TypeScript files that decide the answers, not a commit hash. A squash merge keeps the content, so the test passes. I re-recorded the 49 sessions; the answers did not change.
   • Export Guardian traces as OTLP to a file and over HTTP #244, fix(agt): bind session state to declared identity before evaluation #246, fix(agt): implement ACS-Core wire safeguards #229 and Batch Guardian log writes and drain them on shutdown #112 change those files, so after this PR merges they will need a re-record. agt/README.md explains how.
3. opa_timeout equal to decision_timeout: fixed. The Guardian refuses to start under agt unless opa_timeout is shorter. guardian.yaml now uses 4s. Tests cover both cases.
4. No audit record when the decision and the audit write both fail: fixed. The record now goes to stderr as one JSON line, with the final decision and the error. The §6.3 row in docs/conformance.md now says "one case by interpretation (§6.3 needs the same no-DENY hook exception that §6.5 has for postCompact #270)".
5. PR description: updated.

Non-blockers:

• AGT pinned in two lock files: a new test checks that both pin the same commit.
• Coverage: now counts every package except commands, examples and test helpers. 85.9%.
• max_engine_calls: I measured it with a new make load. At 256, slow answers reach the 5s timeout. At 32, all answers arrive within 1.5s. guardian.yaml now uses 32. Numbers are in docs/load.md. The load test also found a bug, fixed with a test: an engine slot was freed too late, so a step could be refused as busy when nothing was running.
• refusalAt vs hooks.md: a new test reads the Decision lines in hooks.md and checks that our table allows DENY at the same hooks.
• Thanks for checking the env vars, the evaluator validation and catch_unwind.

Dependabot

• Added Go updates for both modules: weekly, 7-day cooldown.
• Dependabot does not update Go itself, so the Go workflow also runs every Monday and govulncheck catches new Go advisories.
• Removed fetch-depth: 0, nothing needs Git history now.

Also in this commit

• [Proposal] Clarify request_id_ref semantics and ACS-Core HKDF parameters #118 / Fix the HMAC key derivation, define key_id, and record an unresolved request_id_ref #272: key_id is set in config with no default. An unknown key_id is refused.
• Align expectations for Guardian reference implementations (#252) #256: every expectation is mapped to a test in docs/conformance.md. Added audit log rotation, tested under load.
• Fixes that follow other issues: [Bug] §6.4's mandatory fail-open audit event has no conformant shape, so the decision-failure rate is unmeasurable #37 (record every failed decision), [Bug] Raw envelopes reach disk before redaction runs, with no file mode set #71 (audit file permissions), [Bug] §3 forward compat accepts any matching major version, which under 0.x accepts every 0.y release #196 (version check), fix(agt): implement ACS-Core wire safeguards #229 (a command that is not a string is denied), Egress annotator reports the wrong host when the URL contains U+FEFF or a no-break space #268 (URL parsing).
• [Bug] §6.4 conflates Guardian refusal with decision failure; refusals are attacker-reachable and should fail closed #32 is still open. Until it closes, the host denies a tampered or invalid Guardian answer even when the posture is proceed. The docs mark this as our interpretation.

[President]

@rocklambros one more commit after my reply: c6e9db2 - merged integration after #275 (schema copy regenerated, TS cases re-recorded, no answer changed), and an empty AGT reason now names no rule, same as #275 does in TS.

[President]

@rocklambros - one more commit, 6e02186:

1. Same issue I raised in Batch Guardian log writes and drain them on shutdown #112, found in our own audit log: a stalled disk could hold ~4 GiB in the queue. Now it is bounded in bytes too (audit.max_queue_bytes), and every lost record is counted.
2. Removes agtbridge.test - a test binary I committed by mistake. make check now refuses binary files.