The journey of a rule that got promoted

The rule this page follows is one sentence: money is integer cents, never float. That rule is a good candidate for exactly three reasons. If your rule cannot make all three claims, leave it as prose and spend the effort where it matters.

1. Consequential Being wrong costs money, and it costs it silently. A float that drifts a hundredth of a cent does not raise, does not fail a test, and does not appear in a log. It appears in a reconciliation report six weeks later.
2. Recurrent Different people and different agents have violated the rule more than once, in the same module. A rule broken once is an incident. A rule broken four times is a rule the prose is not carrying.
3. Decidable A machine can settle it. "No float in the money module" is a predicate over a syntax tree. "Use ports and adapters" is not, and no amount of promotion will make it one.

That third test is the one that disqualifies most candidates, and it is worth being blunt about. No gate can decide the design rules that matter most: layering, dependency direction, and where business logic may live. Those rules stay in prose, and the code the agent imitates carries them, along with the humans who review it. Promotion is not a general answer to rule-following. Instead, treat it as a narrow tool for the small set of invariants that are both expensive and mechanical.

The predicate, once

Everything below mounts this same function. It parses a source file, walks the tree, and returns a list of strings. It knows nothing about agents, tools, graphs, or models, which is why you can mount it in five places unchanged.

import ast

ALLOW = "money-gate: allow"          # the sanctioned escape, per line

def check(source: str, filename: str = "<source>") -> list[str]:
    """Return one message per float-shaped money expression. Empty list = clean."""
    lines = source.splitlines()
    problems = []

    def allowed(node) -> bool:
        line = lines[node.lineno - 1] if node.lineno <= len(lines) else ""
        return ALLOW in line

    for node in ast.walk(ast.parse(source, filename)):
        if allowed(node):
            continue
        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Div):
            problems.append(f"{filename}:{node.lineno}: `/` yields a float; use `//`")
        elif isinstance(node, ast.Call) and getattr(node.func, "id", None) == "float":
            problems.append(f"{filename}:{node.lineno}: float() in a money path")
        elif isinstance(node, ast.Constant) and isinstance(node.value, float):
            problems.append(f"{filename}:{node.lineno}: float literal {node.value!r}")

    return problems

The rule itself is one paragraph, and a capable model reading it writes // most of the time. Most of the time is the operative phrase, which is what the next four rungs are for. What owning the harness changes is not the sentence, it is that you get to choose when it is present.

from langchain.agents.middleware import wrap_model_call
from langchain_core.messages import SystemMessage

MONEY_RULE = (
    "Money is integer cents. Never float, never Decimal, never a string. "
    "Division is `//`. If you need a fraction of a cent you need a different "
    "function and a conversation, not a `/`."
)

@wrap_model_call
def inject_money_rule(request, handler):
    """Append the rule to the system message, but only when it is relevant."""
    if not touches_money(request.messages):
        return handler(request)                # spend the budget elsewhere

    base = request.system_message
    text = base.content if isinstance(base, SystemMessage) else (base or "")
    joined = f"{text}\n\n## Money\n{MONEY_RULE}".strip()
    return handler(request.override(system_message=SystemMessage(content=joined)))

A charter file is unconditional: every rule pays for itself in context on every turn, including the turns about CSS. Assembling the prompt in code lets a rule cost nothing until it is relevant. In practice, that saving is how you keep a growing rule set from crowding out the task. The win is small, and it is all rung 1 gains from being in a custom harness.

What rung 1 buys

• Universality. It applies to every task, including the ones you did not anticipate. A gate only fires where you mounted it; prose reaches everywhere the prompt goes.
• The why. A gate says no. Prose says why, and the why is what stops the agent from working around the no.
• Zero maintenance drift. A sentence cannot break when you rename a module.

What it cannot buy

• A guarantee. The rule competes for attention with everything else in the prompt, and it loses that competition on long tasks.
• Reach past the context window. If the rule is not in what the model read, the rule does not exist for that turn.
• Any force at all against the code. If the tree is full of /, imitation beats instruction, and the rule loses to the surrounding code every time.

Look at two tools that do roughly the same job. One needs every rung above it. The other needs none of them.

@tool
def write_file(path: str, content: str) -> str:
    """Write content to a path in the working tree."""
    # `content` is a string, so any rule about what may be inside it
    # has to be enforced somewhere else. This tool forces rung 3.

@tool
def set_price(sku: str, cents: int) -> str:
    """Set a product's price, in integer cents."""
    # There is no float-shaped argument to pass. The violation this
    # page is about cannot be expressed. No middleware, no ledger,
    # no retry loop, nothing to keep true as the code changes.
    if cents < 0:
        raise ValueError("price cannot be negative")

A narrow tool is enforcement that costs nothing to run and cannot drift out of sync with the rule. It produces a validation error the model can act on, without any code of yours firing. Before you write a gate, ask whether the tool that permits the violation needed to be that wide. Often the honest answer is that write_file exists because it was easy, not because the agent needs arbitrary writes.

Where the ceiling is

1. Coercion A schema is not a proof. cents: int rejects 1080.5, but validation silently coerces a whole-valued float like 1080.0 to 1080. The coercion is harmless here and would not be in every domain. Check what your validator does, rather than assuming.
2. Irreducible width Some tools have to take arbitrary text. No schema can express "valid money code" for a coding agent that edits source. Rung 3 exists for that case.
3. Not retrofittable Narrowing a tool changes the agent's whole vocabulary and every prompt that assumed the old one. Cheap when you are designing the surface, expensive once a system depends on it.

LangChain's agent middleware wraps the tool-call boundary. A decorated function receives the request and a handler, and decides whether to call it. Refusing means returning a different ToolMessage instead of invoking the handler. The reason travels back to the model as an ordinary tool result, so the model keeps working with the specifics.

from langchain.agents import create_agent
from langchain.agents.middleware import wrap_tool_call
from langchain_core.messages import ToolMessage

from gate import check, guards
from ledger import record
from rung2_tools import write_file

@wrap_tool_call
def money_gate(request, handler):
    """Refuse a write that puts a float in a money path."""
    call = request.tool_call                   # {"name", "args", "id"}
    if call["name"] != "write_file":
        return handler(request)

    path = call["args"].get("path", "")
    if not guards(path):
        return handler(request)

    problems = check(call["args"].get("content", ""), path)
    if problems:
        record("blocked", rule="money-cents", path=path, detail=problems)
        return ToolMessage(
            content=(f"REFUSED by money-gate: {'; '.join(problems)}. "
                     "Money is integer cents. Use `//`, not `/`."),
            tool_call_id=call["id"],
            status="error",
        )

    record("passed", rule="money-cents", path=path)
    return handler(request)                    # clean; let the write happen

agent = create_agent(model="claude-opus-5",    # reads ANTHROPIC_API_KEY
                     tools=[write_file], middleware=[money_gate])

Read the refusal branch again, because the whole rung is in it. The gate does not warn the model, or ask it to reconsider, or add a line to a system prompt hoping it lands. It returns before handler(request) is ever called. There is no write to undo, because there was no write. The bad state never existed.

What promotion bought

from typing import Annotated, TypedDict
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import AnyMessage, add_messages

from gate import check
from ledger import record

MAX_ATTEMPTS = 3

class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]
    draft: str            # the candidate source
    problems: list[str]   # why the gate refused, fed back to the writer
    attempts: int

def write(state: State) -> dict:
    """Ask the model for money.py. state["problems"] is the feedback channel."""
    ...

def gate(state: State) -> dict:
    problems = check(state["draft"], "money.py")
    record("blocked" if problems else "passed", rule="money-cents",
           path="money.py", detail=problems)
    return {"problems": problems, "attempts": state["attempts"] + 1}

def route(state: State) -> str:
    if not state["problems"]:
        return "accept"                       # clean
    if state["attempts"] >= MAX_ATTEMPTS:
        return "give_up"                      # fail closed, do not ship
    return "write"                            # retry with the reason in state

builder = StateGraph(State)
builder.add_node("write", write)
builder.add_node("gate", gate)
builder.add_node("give_up", lambda s: {"messages": ["money-gate: unresolved"]})

builder.add_edge(START, "write")
builder.add_edge("write", "gate")
builder.add_conditional_edges("gate", route, {
    "accept": END,
    "write": "write",
    "give_up": "give_up",
})
builder.add_edge("give_up", END)

graph = builder.compile()

Three things changed, and only one of them is about enforcement.

1. The loop is bounded An agent left to recover on its own can retry the same wrong idea until it exhausts a budget. MAX_ATTEMPTS is a number, in your code, that a persuasive model cannot renegotiate.
2. Failure is a route Giving up is a node, not an exception. It can notify, open a ticket, hand to a human, or write a record. Compare the factory's governance gates, which are the same idea at a larger grain.
3. The loop is legible Someone can read the graph and see exactly how many times a violation can recur before the system stops. At rung 3 that behavior existed, but only in the agent's judgment.

A subagent is a context boundary. Work happens in its own window and only a summary returns to the planner. That boundary is a mount point: gate what the subagent returns, and a violating result never enters the planner's history. The planner cannot later imitate a mistake it never saw.

from deepagents import create_deep_agent

from rung2_tools import write_file
from rung3_middleware import money_gate       # the same gate object, unchanged

money_writer = {
    "name": "money-writer",
    "description": "Writes and edits anything under the money module.",
    "system_prompt": (
        "Money is integer cents. Never float. Division is `//`. "     # rung 1 is still here
        "A money-gate refusal names the exact line; fix that line."
    ),
    "tools": [write_file],
}

agent = create_deep_agent(
    model="anthropic:claude-opus-5",           # reads ANTHROPIC_API_KEY
    tools=[write_file],
    subagents=[money_writer],
    middleware=[money_gate],
)

Notice what did not disappear. The system prompt still carries the rule in prose, because rung 1 never stopped being useful. A gated agent that has not been told the rule burns turns rediscovering it by trial and error. The rungs accumulate; they do not replace. So by rung 5 the harness states the same invariant in prose and enforces it at the tool boundary. It also bounds the retry in the graph and records every firing in the ledger. Each of those four mounts does a different job.

The ledger, which is the actual point of rung 5

Every firing appends one line. The ledger is deliberately boring, and nothing else on this page tells you whether the work above was worth doing.

{"ts":"2026-08-18T14:02:11Z","rule":"money-cents","outcome":"blocked","path":"billing/money.py",
 "detail":["billing/money.py:14: `/` yields a float; use `//`"],"run":"a41f"}
{"ts":"2026-08-18T14:02:19Z","rule":"money-cents","outcome":"passed","path":"billing/money.py","run":"a41f"}
{"ts":"2026-08-18T16:40:03Z","rule":"money-cents","outcome":"allowed","path":"billing/report.py",
 "detail":["line 88 carries `# money-gate: allow`"],"run":"b07c"}

1. blocked The gate refused. A rule with a healthy block rate is doing work. A rule that has never blocked anything is a candidate for demotion.
2. passed The gate ran and found nothing. Counting the passes is what turns "it feels like this fires a lot" into a rate you can act on.
3. allowed Someone took the money-gate: allow escape, and that line is the most valuable one in the file. A rising allow rate means the rule no longer matches the code, so the rule is what needs fixing.

Read the ledger quarterly. It takes ten minutes and answers a question the team is otherwise guessing at.

That second row is the one worth internalizing, because it is the one people resist. A gate that has not blocked anything in a quarter is not proof the gate is working. But the same silence is equally consistent with the gate being unnecessary. To tell the two apart, remove the gate and watch. Demotion is cheap and reversible. The sentence stays in the charter, and the predicate stays in the repo. Re-promoting is a three-line change you have already done once.

Where this page sits

There is deliberate overlap with two other write-ups here. They are not three points on one ladder; they are three different questions about whose code the constraint lives in.

1. Guardrails Constraining a stock coding agent. Five guardrails covers someone else's agent. You shape it through the surfaces it exposes: its charter, its rules, its hook contract. You are a configurer.
2. This page Building a coding agent of your own. No hook contract to conform to, because the loop is yours. The constraint is a branch in your code, and the engineering is choosing which of five mount points it belongs at.
3. The factory Running any coding agent. A lights-on factory sits above both: it takes a tracker card and returns a merged pull request. The factory does not care whether the agent inside is stock or custom. Its gates are at the grain of whole jobs, not single tool calls.

The rungs on this page therefore have no equivalent in the other two. A stock agent gives you rung 1 and a hook, and nothing between them. A factory gates the job, not the write_file call inside it. Owning the loop is what puts tool schemas, tool-call interception, graph topology, and the subagent boundary on the table at all.