Record, do not publish

HookpieceCC-BY-4.0practiced By Campaign Hub

A small end-of-turn program that records that the turn ended. It refuses to publish, send, delete, or decide that the work succeeded.

When to use

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.

When not to

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.

Author-attested

Original teaching specimen written for the Campaign Hub library. Not a transcript of a private run.

Community-submitted content. Prompts, skills, and agent instructions can contain hidden or malicious instructions (prompt injection). Review it before running it in any agent that has tool access, secrets, or the ability to spend money or send messages.
# 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.

How a stranger checks it

Related

hook record side-effects turn-end

view raw view JSON