makoto

Makoto

Makoto is a Claude Code hook. Before a dependent step runs (Write, Edit, MultiEdit, NotebookEdit, Bash git commit/git push, or Stop), it checks the session record. If a reading the step needs is missing, it holds the step: a PreToolUse step gets a native deny and a Stop gets a native block. The hold names the rule, its shape, the exact subject, the one Immediacy rule it enforces and the missing reading. An admitted step gets {}. The checker uses no model and no network.

Install

Claude Code 2.1.275 or later:

/plugin install makoto --marketplace Clear-Sights/Makoto

plugin/hooks/hooks.json sends each native event to cd plugin && python3 -m makoto2. Makoto needs Python 3.11 or later and uses only the standard library.

The principle

Makoto is deterministic enforcement of Immediacy:

IMMEDIACY: A more immediate read assumes less.
  + Original: Read the original instead of a derivation.
  − Unchanged: Do not assume what can change has not.

Code decides every hold from the session record. An admitted step gets {}: Makoto adds nothing to the model's context, so no check depends on the model reading injected text. A hold states the rule it enforces, the specific missing reading and the one action that clears it (Clear: ...), and asks no question. A decided hold always blocks: in every directory, and on every repeat of the same Stop.

The rules

• a (lineage), enforces Original: the step needs an original artifact reading. Assistant text, worker answers and readings of files this session wrote do not count. A completed run, query or request response does count, and a run of a session-written script reads that script's response.
• b (spec), enforces Original: each name the step uses (path, URL, email, identifier, hash, UUID, version) must appear with its exact characters in an earlier tool input, an original response, or the user prompt, or in text this session wrote or got back from its own writes (a file name or directory inside a longer path counts). Writer targets and files this session wrote are outputs, so b does not apply to them.
• c (other point), enforces Original: a named URL, a versioned package or a host-classified public project needs an online fetch or search of that subject in the current turn.
• d (switch), enforces Unchanged: when a step names an edited code, script or config subject, or ships session edits through a commit, push or final answer, a paired call must have run that subject after its last edit and returned output. For a config file without a shebang, a full read after the last edit also pays d. Reading code never pays d.
• e (file), enforces Original: an Edit, MultiEdit or NotebookEdit, or a Write onto a file that already exists, needs a reading of that file, or a write of it by this session, earlier in the session. A Write that creates a new file needs none. A live hook checks the file system; a host that cannot may record the fact in makoto.target_exists. The hold ends in Clear: Read <path>.

A locked, hash-linked journal keeps every turn under ~/.claude/makoto2_state (MAKOTO_STATE_DIR overrides). The optional host envelope makoto (effects, external_subjects, network_subjects, invocation.subject(s), turn_id, detio_store) lets the host record what it saw, such as opaque mutations, public names or the program that actually ran. The host must enforce the decision before it runs a tool or delivers a final answer.

Errors block, and the way out

• An error in Makoto's own reading (state folder, lock, transcript, a malformed host event) blocks the step, names the error, and gives the one way to disable Makoto. The user's own prompt (UserPromptSubmit) is never blocked: it is admitted and, whenever the journal is writable, recorded.

• A corrupted journal does not stop the session. It is moved beside a fresh journal as <journal>.corrupt-<ns>, and only a step whose reading is missing from what can still be read (the transcript, then new calls) is held, for that missing reading.

• The one way to disable Makoto, if an error keeps blocking, is to run this in a terminal outside the session, so a broken install cannot trap you:

  claude plugin disable makoto
  

• Every hook in hooks.json has a 10 s timeout. The per-session lock is never waited on longer than 3 s (MAKOTO_LOCK_SECONDS); a busy lock blocks the step with that error.

• A hold is never capped: a stop_hook_active Stop with a finding is held again every time.

• Each call reads only the journal rows and transcript lines added since the previous call: a .ckpt file beside the journal keeps both reads and the replayed record. A checkpoint that does not match is ignored and the call replays in full; MAKOTO_CHECKPOINT=0 always does.

License

FSL-1.1-ALv2 (LICENSE): use, copy, modify and redistribute Makoto for any purpose except a Competing Use, which is offering it, or a product with the same or substantially similar functionality, to others as a commercial product or service. Internal use, non-commercial education and research, and professional services to a licensee are permitted. Each version becomes Apache-2.0 two years after its release. Versions up to and including 85ac4d5 stay Apache-2.0. NOTICE lists the Apache-2.0 excerpts from DetIO and Causality.

Development

python3 -m pytest -q runs tests/. For each of rules a-d, test_rules.py sends a plant and its twin through the exact hooks.json command: the plant is held and the twin is admitted. test_robust.py plants each infrastructure error and checks that it blocks with the way out, and that checkpointed calls decide exactly as full replay does. scripts/measure_cost.py reports per-hook wall time (cold and warm bytecode) and the bytes a hook adds to the model's context, on the events tests/ already contains; MEASURE_REPEAT sets the repeat count. The full suite, fixtures, tools and records live in Clear-Sights/Makoto-Dev. This repository receives only finished versions. The cut mesh/ gate is kept in git history at 295bf44.