Closeout

Draft 0.1

Adopt the runner

The reference runner is the Rust crate in this repository, version 0.1.0, edition 2024. From a checkout:

cargo test
cargo run --quiet -- validate
cargo run --quiet -- run --gate beforePR --base <base> --head <head> --json

Exit 0 means accepted. Exit 1 means a requirement failed. Exit 3 means acceptance is blocked. Exit 2 means the invocation is invalid.

Decide

closeout decision \
  --gate beforePR \
  --base <base-commit> \
  --head <candidate-commit> \
  --candidate-session <id> \
  --candidate-model <id> \
  --json

--candidate-session, --candidate-model, and --candidate-provider are the candidate identity used for independence. An empty value does not satisfy a flag set to true.

Record a review

closeout evidence add \
  --gate beforePR \
  --item <qualified-id> \
  --base <base-commit> \
  --head <candidate-commit> \
  --session <reviewer-session> \
  --model <reviewer-model> \
  --findings findings.json

findings.json is an array of finding objects. The command writes the next attempt. It does not decide acceptance.

Read the policy from origin/main

validate, run, decision, and evidence add read .agents/closeout.yaml from the commit at refs/heads/main on the remote origin. The runner fetches that ref and checks it against the remote again. A local edit of main, of the work tree, or of the origin/main ref does not change the policy.

Try a draft

closeout try \
  --gate beforePR \
  --base <base> \
  --head <head>

Put the draft at ~/.agents/closeout.yaml. Imports and skills in that file resolve from the home directory. try prints the result and does not write a decision file.

Seal a report

closeout keygen --pgp --out keys
closeout run \
  --gate beforePR \
  --base <base> \
  --head <head> \
  --format markdown \
  --pgp-key keys/closeout-public.asc
closeout verify \
  --pgp-key keys/closeout-private.asc \
  --head <head> \
  report.asc

run encrypts the markdown with the public key. verify decrypts it with the private key and reprints the decision. The public key can seal any report. The private key is what reads the body. A hook does not treat a sealed file in the workspace as acceptance.

Verify on a pull request

Copy examples/github/verify-sealed.yml to .github/workflows/verify-sealed.yml. Store the private key in the CLOSEOUT_PRIVATE_KEY secret. The agent writes closeout-report.asc at the pull request head.

The workflow file comes from the default branch. The job reads that one report, installs closeout from the same branch, and runs verify --require-accepted for the pull request head. The sealed decision's policy digest has to match origin/main. The job leaves the pull request's own code unexecuted. When the check passes, it comments:

Closeout verified the sealed report for <head>.

The proof check is valid and the decision is accepted.

The comment includes the decision the private key decrypted. A failed check leaves no comment.

Share verification artifacts in Kyoto

Kyoto publishes a real file through attach_artifact, keeps a copy with the session and displays a clickable attachment in chat during the turn. Useful verification files include screenshots, interaction videos, Markdown reports and actual terminal transcripts. Attach the observations that support the response. Ordinary answers can remain in chat.

For a public Closeout decision, run the reference runner against the committed candidate. Keep its actual exit status and decision, including failed or blocked outcomes. Its command records retain the candidate, policy, producer and attempt identities.

mkdir -p .closeout
closeout run \
  --gate beforePR \
  --base <base-commit> \
  --head <candidate-commit> \
  --json > .closeout/decision.json

Then create a portable copy of the recorded evidence and referenced files. The archive retains the paths relative to .closeout/.

tar -czf /tmp/closeout-evidence.tar.gz .closeout

Call attach_artifact with /tmp/closeout-evidence.tar.gz and share a short response that matches the recorded decision. The archive preserves the original records and log bytes. Its attachment hash verifies the downloaded archive; each evidence reference identifies its own file bytes. A client opens active HTML content through an explicit external action.

Plugins

The plugins call the closeout binary. They do not contain a second copy of the policy. CLOSEOUT_BIN selects the binary. CLOSEOUT_BASE selects the base revision. When it is unset, the hook uses the same commit for base and head.

Claude Code reads .claude-plugin/marketplace.json. The plugin is plugins/claude. Its Stop and TaskCompleted hooks run hooks/consult.mjs.

Codex reads .agents/plugins/marketplace.json. The plugin is plugins/codex. Its Stop hook runs the same consult script.

OpenCode loads a JavaScript file from .opencode/plugins/. The file in this repository is plugins/opencode/closeout.js. On session idle it can nudge the session at most three times for one head. It does not write an accepted decision.

If stop_hook_active is set, or CLOSEOUT_HOOK=0, the consult script exits 0 and does not treat that silence as acceptance. A missing binary blocks the hook. A repository with no policy file is left alone.