# Record, do not publish This file is a hook: a small program that runs at the end of a turn and only records. ## When to use Use this at the named moment "end of turn," when a harness wants a durable line that the turn ended. The hook reads one JSON object from standard input and writes one JSON object to standard output. The harness may append that line to a log. The hook itself does not choose a destination, open a network connection, or touch the publish gate. ## When not to Do not hang this program on a moment where the job is to publish, send mail, delete files, or decide that the work succeeded. Those acts need their own gates and their own roles. Do not treat a successful record as a successful task. The record says the turn ended. It does not say the specimen is good. ## The specimen The artifact is this program. ```python #!/usr/bin/env python3 """End-of-turn hook. Records that a turn ended. It does not publish, send, delete, or decide success.""" import json import sys from datetime import datetime, timezone FORBIDDEN = ("publish", "send", "delete", "succeeded") def main() -> int: try: event = json.load(sys.stdin) except json.JSONDecodeError: print(json.dumps({"ok": False, "error": "stdin is not JSON"})) return 2 if not isinstance(event, dict): print(json.dumps({"ok": False, "error": "event must be an object"})) return 2 if event.get("action") != "record": print(json.dumps({"ok": False, "error": "this hook only records"})) return 2 for name in FORBIDDEN: if event.get(name): print(json.dumps({"ok": False, "error": "refusing to " + name})) return 2 record = { "event": "turn_ended", "turn_id": str(event.get("turn_id", "")), "at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), } print(json.dumps(record)) return 0 if __name__ == "__main__": raise SystemExit(main()) ``` What it accepts: an object whose `action` is `record`. It may carry `turn_id`. It prints one object with `event` set to `turn_ended`, the turn id, and a time, then exits 0. What it refuses: a missing or non-object payload, any action other than `record`, and any true `publish`, `send`, `delete`, or `succeeded` field. On a refusal it prints an error and exits 2. It never prints `turn_ended` on a refusal, so a log of `turn_ended` lines cannot be read as a series of publishes or successes. The program has no network client and no delete call. Adding either one makes it a different program and no longer this specimen. ## How a stranger checks it Save the program as `record_hook.py`. From a shell, run these two observations. First, a plain record: ```bash printf '%s' '{"action":"record","turn_id":"turn-1"}' | python3 record_hook.py ``` The process exits 0. The printed JSON has `"event": "turn_ended"` and `"turn_id": "turn-1"`. It has no field that says the work succeeded. Second, a record that also asks to publish: ```bash printf '%s' '{"action":"record","turn_id":"turn-1","publish":true}' | python3 record_hook.py ``` The process exits 2. The printed JSON has `"ok": false` and an error that refuses to publish. It does not contain `turn_ended`. Repeat the second shape with `send`, `delete`, and `succeeded` set true, one at a time. Each exits 2. A hook that performs any of those actions, or that exits 0 while refusing, is a broken copy.