Makoto: Claude Code Hook for Agent Action Verification

What changed

Makoto is a recently released Claude Code hook designed to enhance the reliability of AI agent actions. It operates by intercepting agent steps, such as writing, editing, or committing code, before they are executed. Makoto then scrutinizes the session's logged record to ensure that any information required for the step is present and accurate according to its defined principles of "Immediacy." These principles are:

• Original: Prioritize reading original data over derivations.
• Unchanged: Do not assume that data which can change has not.

If a step requires information that is missing or violates these immediacy rules, Makoto will block the action. For instance, if an agent claims to have tested code but the session record doesn't show a corresponding test execution, Makoto will prevent the step. The checker itself is deterministic, using no external models or network calls, and aims for zero false positives in its checks. It enforces rules related to data lineage (a), specification (b), external subject fetching (c), and state changes (d), as well as file existence for edits (e).

Makoto is installable as a plugin for Claude Code version 2.1.275 or later via the command /plugin install makoto --marketplace Clear-Sights/Makoto. It requires Python 3.11 or later and relies solely on the standard library. All session state is maintained in a locked, hash-linked journal located at ~/.claude/makoto2_state (configurable via MAKOTO_STATE_DIR). The plugin also supports an optional host envelope for recording observed data, such as opaque mutations or program executions.

Why it matters for builders

For AI builders developing agent-based systems, Makoto offers a robust mechanism for enforcing action integrity. It moves beyond simple warnings to actively block potentially erroneous or deceptive agent actions. By ensuring that agents operate based on verifiable, up-to-date information, Makoto helps to build more trustworthy and predictable AI systems. This is particularly important for agents involved in code generation, modification, or deployment, where factual accuracy and adherence to process are paramount.

Practical impact

Builders can integrate Makoto into their Claude Code workflows to add a layer of deterministic verification. To start using Makoto, ensure Claude Code version 2.1.275 or later is installed, then run the plugin installation command. Developers should familiarize themselves with the specific immediacy rules (a-e) to understand how Makoto enforces data integrity. For agents performing tasks like code commits or file edits, Makoto will automatically check for prerequisite actions like reading the latest version of a file or verifying that changes have been tested. If a violation occurs, the agent's step will be blocked, and Makoto will indicate the specific rule and missing information, providing a clear path to resolution.

Caveats and source limits

The source material indicates that while Makoto's checks are deterministic and aim for zero false positives, the overall effect of its dispatcher on a live session's outcome is unmeasured. The license is FSL-1.1-ALv2, permitting use for most purposes except offering it as a commercial product with similar functionality; it transitions to Apache-2.0 two years after release. Specific pricing for the plugin or any associated services is not provided. The source also does not detail independent benchmarks comparing Makoto's performance or overhead against other verification methods.