{"slug":"record-dont-publish","title":"Record, do not publish","description":"A small end-of-turn program that records that the turn ended. It refuses to publish, send, delete, or decide that the work succeeded.","body":"# Record, do not publish\n\nThis file is a hook: a small program that runs at the end of a turn and only records.\n\n## When to use\n\nUse 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.\n\nThe 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.\n\n## When not to\n\nDo 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.\n\nDo not treat a successful record as a successful task. The record says the turn ended. It does not say the specimen is good.\n\n## The specimen\n\nThe artifact is this program.\n\n```python\n#!/usr/bin/env python3\n\"\"\"End-of-turn hook. Records that a turn ended. It does not publish, send, delete, or decide success.\"\"\"\n\nimport json\nimport sys\nfrom datetime import datetime, timezone\n\nFORBIDDEN = (\"publish\", \"send\", \"delete\", \"succeeded\")\n\n\ndef main() -> int:\n    try:\n        event = json.load(sys.stdin)\n    except json.JSONDecodeError:\n        print(json.dumps({\"ok\": False, \"error\": \"stdin is not JSON\"}))\n        return 2\n    if not isinstance(event, dict):\n        print(json.dumps({\"ok\": False, \"error\": \"event must be an object\"}))\n        return 2\n    if event.get(\"action\") != \"record\":\n        print(json.dumps({\"ok\": False, \"error\": \"this hook only records\"}))\n        return 2\n    for name in FORBIDDEN:\n        if event.get(name):\n            print(json.dumps({\"ok\": False, \"error\": \"refusing to \" + name}))\n            return 2\n    record = {\n        \"event\": \"turn_ended\",\n        \"turn_id\": str(event.get(\"turn_id\", \"\")),\n        \"at\": datetime.now(timezone.utc).strftime(\"%Y-%m-%dT%H:%M:%SZ\"),\n    }\n    print(json.dumps(record))\n    return 0\n\n\nif __name__ == \"__main__\":\n    raise SystemExit(main())\n```\n\nWhat 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.\n\nWhat 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.\n\nThe program has no network client and no delete call. Adding either one makes it a different program and no longer this specimen.\n\n## How a stranger checks it\n\nSave the program as `record_hook.py`. From a shell, run these two observations.\n\nFirst, a plain record:\n\n```bash\nprintf '%s' '{\"action\":\"record\",\"turn_id\":\"turn-1\"}' | python3 record_hook.py\n```\n\nThe process exits 0. The printed JSON has `\"event\": \"turn_ended\"` and `\"turn_id\": \"turn-1\"`. It has no field that says the work succeeded.\n\nSecond, a record that also asks to publish:\n\n```bash\nprintf '%s' '{\"action\":\"record\",\"turn_id\":\"turn-1\",\"publish\":true}' | python3 record_hook.py\n```\n\nThe process exits 2. The printed JSON has `\"ok\": false` and an error that refuses to publish. It does not contain `turn_ended`.\n\nRepeat 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.\n","kind":"hook","stratum":"piece","license":"CC-BY-4.0","shot":"na","tags":["hook","record","side-effects","turn-end"],"author_name":"Campaign Hub","author_url":"https://campaignhub.fyi/about","source_url":null,"provenance":"Original teaching specimen written for the Campaign Hub library. Not a transcript of a private run.","maturity":"practiced","audience_role":"runtime","safety_class":"public_teaching","harness":["generic"],"use_when":"Use this hook at the end of a turn when the harness needs a record that the turn ended and must not gain a side effect from that moment.","avoid_when":"Do not use this hook to publish, send, delete, approve, or mark success. Do not point it at a network call. Recording is the whole job.","eval_checks":[{"id":"HOOK-1","text":"A record event prints one turn_ended object and exits 0. An event that also asks to publish exits 2 and does not claim success.","how_checked":"Run the program twice as the check section states. The first exit code is 0 and the JSON event is turn_ended. The second exit code is 2 and the error refuses to publish."}],"published_at":"2026-09-24T21:59:21.000Z","updated_at":"2026-09-24T21:59:21.000Z","sensor":null,"edges":[{"from":"record-dont-publish","to":"human-publishes","kind":"cites","title":"A person publishes"}]}