Precondizioni programmatiche

Picture a customer support agent with a process_refund tool. The model is smart, but it is also probabilistic. Roughly 9 times out of 10 it follows your instruction to verify the customer first. The tenth time, under an unusual prompt or a confusing conversation, it refunds an unverified stranger.

For a financial action, a 90% success rate is a liability, not a feature. This lesson is about closing that 10% gap with a programmatic precondition: a deterministic code-level gate that blocks the refund until identity is verified — every single time.

There are two ways to enforce a rule in an agent:

• Prompt guidance — "Always verify the customer before refunding." This is ~90% reliable. The model decides whether to comply.
• Programmatic enforcement — a hook or code check that runs deterministically. This is 100% reliable. The model cannot override it.

The exam rule of thumb: when failure has financial, legal, or safety consequences, you do not trust a prompt. You reserve hard code for guarantees, and let the model make the open-ended decisions.

A programmatic precondition is a fact that must be established in verified state before a sensitive action is allowed to proceed. For our case: the refund is blocked until get_customer has returned a record with a verified identity.

This is not the model promising it checked. It is your code observing the actual tool results and refusing to run process_refund unless the verification fact is genuinely present. The guarantee comes from the data, not from the model's narration.

To gate a tool you must know where in the loop to intervene. Each turn: you send the full message history, inspect stop_reason, and if it is tool_use you run the requested tool, append the result, and loop again until end_turn.

The precondition lives in that "run the requested tool" step. When the model asks for process_refund, your code inspects accumulated state before executing it. The model proposes; your code disposes.

The precondition needs a source of truth. Keep a small server-side state object that records what has actually been established this conversation — not what the model said it did.

When get_customer returns, your dispatcher reads the real payload and sets a flag only if the record is genuinely verified. This state is the gatekeeper's evidence.

Now wire the precondition. When the model requests process_refund, your code checks state["identity_verified"] first. If the fact is not established, you do not call the refund backend — you return a structured tool result telling the model why it was blocked and what to do next.

Crucially, you return this as a normal tool result the model can read and act on, not a thrown exception that crashes the loop.

A generic failure like "Operation failed" blocks recovery — the model cannot tell why it failed or what to do next. A structured error enables intelligent routing.

Include: isError: true, an errorCategory (transient / validation / business / permission), isRetryable, a human-readable message, and ideally the attempted action. Here the category is permission and isRetryable is false until the precondition is satisfied — so the model knows to go verify first rather than blindly retry the refund.

The dispatcher check above is one form of precondition. The exam also expects you to know hooks for the same job. An outgoing-call hook intercepts a tool invocation and can block a policy-violating action — for example, a refund over $500, or any refund on an unverified account.

Hooks are 100% deterministic; prompts are ~90% probabilistic. A PostToolUse hook can also intercept a tool result before the model ever sees it. Either way, the guarantee is enforced in code the model cannot talk its way around.

Real policy is often compound: block the refund unless identity is verified AND the amount is within the allowed threshold. Both checks are deterministic preconditions; neither belongs in a prompt.

The verification check guards who; the threshold check guards how much. A violation of either returns a structured, actionable result — escalate to a human for the threshold case, or send the model back to verify for the identity case.

A precondition is a correctness guarantee — it ensures a specific fact holds before a specific action. Do not confuse it with the loop's safety net.

• You still terminate on stop_reason, never by parsing text for words like "done" or "verified".
• Iteration caps are a safety net against runaway loops, never the primary stop mechanism — and never the way you enforce business policy.

The precondition is surgical: it gates one action on one verified fact, deterministically, while the model keeps driving the conversation.

One more architectural trap. A verification precondition is a blocking, time-sensitive check — the refund cannot proceed until it resolves in the live conversation.

That rules out the Message Batches API: it is 50% cheaper but has a window of up to 24 hours, no latency SLA, and no multi-turn tool calling. Batch is for overnight audits and reports, never for an inline guard a customer is waiting on. Run preconditions synchronously in the agentic loop.

Key takeaways for programmatic preconditions:

• Money, legal, safety → deterministic. Prompts are ~90%; hooks and code preconditions are 100%.
• Gate on verified facts, not narration. Track real state from get_customer; block process_refund until identity_verified is true.
• Intercept in the loop. Check before executing the tool the model requested; use a hook to block policy violations like refunds over $500.
• Fail with structure. Return isError, errorCategory, isRetryable, and a clear message so the model can recover.
• Stay synchronous. Terminate on stop_reason, never iteration caps or text parsing — and never the Batch API for blocking checks.