Build It So It Holds

Koko: Here is the one instinct this module is trying to install: a prompt is a request. A contract is something else. And the difference between those two things is where most agentic systems either hold or break. Everything we cover today is about understanding that gap and knowing how to close it.

Sam: And this is the architectural frame for the whole lesson, right — before we get into harness mechanics or trust boundaries, we need to know where the prompt actually sits inside a system.

Koko: Exactly. So let's start with how a system is actually structured. Four layers, innermost first. At the centre is the model itself. Around it is the instruction contract — the persistent, deliberate definition of what this thing is supposed to do. Third layer is context: what gets assembled and passed in for each individual call. And the fourth layer, the outermost one, is the harness — tools, schemas, loop bounds, hooks, state management, error handling. That is the layer where a system is actually made.

Sam: So when people talk about prompt engineering, they're really working on layer two. And context engineering is layer three.

Koko: Right. Both real and both important. But harness engineering — layer four — is where the system either holds under production conditions or it doesn't. Now, the instruction contract. It has eight fields, and a prompt that is missing any of them is a request, not a contract.

Sam: Can you run those eight?

Koko: Role and scope. The outcome and its target. The evidence the system may use. What it must never do — and we're going to come back to exactly how that prohibition is written. The thresholds it must honour. The tools it may call. The output contract. And the completion condition — what does done actually look like.

Sam: Eight fields. And the thing I notice from that list is that most of them are the client's, not the engineer's.

Koko: That is the sharpest way to say it, and it matters. Let's make it concrete. A procurement team is building an invoice-matching assistant. The role field names the organisation and the specific queue it is operating on. The outcome field carries the actual target: matched invoices released within the agreed number of days, at the stated exception rate — real numbers from the real case. The prohibition is the policy sentence itself. Not a paraphrase of it — the sentence. Something like: no release above the approval threshold without a named approver. And the output contract is a schema.

Sam: When you read those eight fields out loud for that case, seven of them come straight from the client. The engineer's contribution is the output schema.

Koko: That is the proportion. And it tells you something important about where the design work actually lives. It is not in the wording. It is in the elicitation — getting those seven fields out of the client and onto the page with precision.

Sam: The analogy I use for this is a brief to a contractor versus saying 'make the kitchen nice.' One is a wish. The other names the room, the budget, what may not be touched, what done looks like, and who signs it off.

Koko: That is exactly the analogy. A wish gets you something. A brief gets you what you specified. Now, the takeaway to carry into the room: structured is not correct. A response can match the output schema perfectly — every field present, right data types, clean JSON — and be wrong in every value. Which means validation has to be layered.

Sam: Shape first, then meaning, then consequence.

Koko: In that order. And every deterministic check runs before any judgment-based one, because deterministic checks are effectively free and they fail closed. You do not spend model calls or human review time on a response that fails a schema check.

Sam: The version of this I keep seeing in architecture reviews is teams treating the schema as the whole validation layer. The schema catches the missing field. It does not catch the confident wrong number.

Koko: That is the first failure mode, and it is plausible precisely because the schema did its job — shape is valid, so people assume meaning is too. The second one is subtler. It is the paraphrased prohibition. Someone rewrites the policy sentence in the instruction contract to make it read more naturally. And now the version the model is following is nobody's actual policy. It is a third document that nobody signed.

Sam: Quote it or link it. Do not restate it.

Koko: That is the rule. The policy field in the instruction contract takes the policy sentence verbatim. Because the moment you paraphrase it, you have introduced a gap between what the organisation agreed to and what the system believes it is operating under — and in a consequential process, that gap is where liability lives.

Koko: So here is the thing that changes how you read a bad output. Context is not a bucket you fill up. It is a supply chain with six distinct components: the instructions, retrieved knowledge, user and session state, tool results, examples and procedures, and the working memory of the run. Each one has to answer the same six questions — where does it come from, how is it selected, how fresh is it, what permissions gate it, what provenance travels with it, and how does it get compacted when the window starts to fill?

Sam: And that last one — compaction — is the one that bites you late in a session, not at the start.

Koko: Exactly. The constraint you stated in minute one can be quietly dropped by minute forty if the compaction rule does not protect it. Which brings us to a worked example worth sitting with.

Sam: The policy assistant scenario is a good one for this. Leave questions, multiple jurisdictions — the retrieval boundary alone is doing a lot of work.

Koko: Right. The retrieval boundary decides whether employee-relations case notes can even reach the model. That is a permissions question. Freshness decides whether last quarter's policy is what gets cited today. And compaction decides whether a long session eventually forgets the one constraint someone set at the very beginning of the conversation. Three different supply-chain questions, three different fixes. None of them are fixed by rewriting the prompt.

Sam: The way I think about it on a delivery team: if you can remove a component, re-run the evaluation, and nothing moves, it was never doing work. It was occupying window.

Koko: That is the deletion test, and it is exactly right. If removing it changes nothing, it was never context — it was weight. Now for the analogy, because this one is worth holding onto. Think about a restaurant. The menu is the prompt. But what actually reaches the plate depends on the suppliers, the cold chain, who is allowed in the walk-in, and what gets thrown out at close. A chef who rewrites the menu when the fish is off is solving the wrong problem.

Sam: And the kitchen staff have different access levels to the walk-in — that is the permissions layer sitting inside the supply chain.

Koko: Precisely. Which connects directly to configuration precedence, because that is how the access levels are set. The order is: the platform's floor, then the organization's policy, then the workflow, then the session, and only then the individual request. A lower layer can narrow a permission. It cannot widen one.

Sam: So a session-level setting can restrict what the workflow already restricted, but it cannot grant something the organization policy has not already allowed.

Koko: That is the rule. Narrowing is always available downward. Widening is not. The takeaway to carry into a design review: when output quality disappoints, locate the fault on a layer before you rewrite a sentence. Most persistent failures are supply-chain failures wearing a prompt costume. The fix is a boundary, a refresh, or a compaction rule — not different wording.

Sam: The version of this I keep seeing on teams is that someone spends half a day on prompt iteration and the problem was a stale retrieval index the whole time.

Koko: And that leads straight into the failure mode, because there is a specific and costly version of this mistake when things break at runtime. The failure playbook has eight shapes, and exactly one of them is answered by a retry — the transient failure. The other seven are budget, permission, safety, a schema break, a stale read, a wrong tool, and a run that finished without the outcome it was supposed to produce.

Sam: And the permission failure is the telling one, because retrying it gives you a second permission failure and a log that looks like persistence.

Koko: The misconception here is that retry is a safe default — that if something failed once, trying again is at worst neutral. It is not neutral. It generates a misleading log, it burns budget, and it delays the actual fix, which is probably a boundary or a credential. Name the shape of the failure first. Then choose the verb.

Koko: So the harness has six layers, and the model sits inside exactly one of them. Everything outside that layer — the tools, the identity, the approval chain — is the harness's job, not the model's. And that includes the tools themselves. A tool is not a function call you wrote in an afternoon. It is a product with a contract.

Sam: When you say contract, you mean the full specification — name, purpose, input schema, output schema, what permissions it holds, what it costs to call, how it behaves on error, and what class of consequence it can cause.

Koko: Exactly that. All eight of those. And the consequence class matters most. A tool that can only do one thing cannot be talked into doing another. That is not just a security property — it is a reliability property. The failure space physically shrinks.

Sam: The version of this I keep seeing on teams is the wide tool justified as convenient. One tool, update anything in the ledger, ship it fast. And then the prompt does the narrowing.

Koko: Right, and we are going to come back to exactly why that does not hold. But first, let's make the mechanism concrete. The deductions queue scenario from the notes is the clearest one.

Sam: Walk me through it.

Koko: You have a tool that writes off a deduction. It takes an identifier and an amount. It has a hard ceiling baked into its own code. Anything above that ceiling, it refuses — before the model is ever consulted. The model never even sees the question. Now compare that to a tool that can update anything in the ledger. You take those two designs to the controls team. Which one do they sign?

Sam: The first one, immediately. Because the ceiling is deterministic. It is not a request to the model; it is a wall in the code.

Koko: And that is the phrase worth keeping: a wall in the code, not a request to the model. Which brings me to the analogy. A valet key.

Sam: Starts the car, opens the driver's door.

Koko: That is it. It does not open the glove box. It does not open the trunk. Nobody has to trust the valet's character for that to hold, because the key physically cannot do those things. The trust is in the design of the key, not in a request you made to the valet before handing it over.

Sam: And the authority chain works the same way in the harness. It runs from a named human, through the workflow, to the identity the tool actually sees. It never runs from the model.

Koko: Never from the model. Every run carries its own workload identity, and that identity has exactly the authority that was granted to it by name — not by whatever the model concluded it should have. Security, authorization, approval, policy: all of that lives in deterministic code outside the model. The gap between what a model could do and what the design permits is closed by identity and code. Not by wording.

Sam: And this is where the decision rights from the earlier module become real. The decision rights were the columns — who can authorize what. The tool contract is where that actually gets enforced.

Koko: Exactly. The tool contract is where decision rights stop being a document and start being a constraint. So the instinct to carry into the room: when you are reviewing a tool design, ask whether every write path has a contract that names its ceiling and names its approver. If it does not, you do not have a tool — you have a wish.

Sam: The version of the failure I keep seeing, and I mentioned it earlier, is the wide tool with the careful prompt. It can update anything, but we told it to be careful.

Koko: The misconception there is that every word after 'anything' is a request. A request to a model. And requests can be misread, overridden by a later instruction, or simply ignored in an edge case you did not anticipate. There are eight critical-control gates at this stage of the harness, and the first of them is that no write path exists without a contract naming its ceiling and its approver. The prompt is not a ceiling. The prompt is a request. The ceiling is in the code.

Koko: Two protocols, two different jobs. One connects a model to tools — it answers the question, what can this agent reach out and touch? The other connects agents to other agents — it answers, who does this agent talk to? They are not interchangeable, and the confusion matters because if you treat the tool protocol as the agent protocol, you end up treating a calculator like a colleague. You assign it a plan, you wait for it to reason, and it does neither, because it is a tool.

Sam: The way I hold that distinction on a project is: the tool protocol is about capability, the agent protocol is about coordination. One extends what a single agent can do, the other changes how many decision-makers are in the room.

Koko: Exactly right. And once you know which protocol you are in, you need to know the shape of the loop that sits inside any agent using it. Five steps: observe, decide, act, check, continue. What matters most for delivery is that there is exactly one enforcement point in that loop — the hook. It runs before and after every action. It is deterministic, it can block, and it is where your evidence lives.

Sam: So the hook is the only place you can actually stop something from happening. Not the model's own judgment — the hook.

Koko: Right. The model decides, but the hook enforces. That is the line. Now, where patterns fit on the ladder from Part One. A single call is the bottom rung — one prompt, one response. Above that, a fixed workflow: steps in code, one model call in the middle, cheap, testable, deliverable in weeks. Above that, a bounded loop: the model decides what to gather next, but you have put a ceiling on iterations and a hook on every write. Only above that do you get to the manager and handoff modes.

Sam: And in the manager mode, the manager keeps the plan and delegates — it does not hand off the plan, it hands off the task.

Koko: Correct. Whereas a handoff passes a six-part packet and releases control entirely. The receiving agent gets everything it needs — context, constraints, the lot — and the sending agent is done.

Sam: Let me put a concrete case on that. Take a deductions review. Built as a fixed workflow: three steps in code, one model call in the middle to classify, done. Built as a bounded loop: the model decides which evidence to pull next, iteration ceiling in place, hook on every write. The second is only the right call if the first measurably fails the evaluation. That is the test I run in a design review — what would this lose if it were one agent, or one rung lower?

Koko: That is the collapse question. What would this lose if it were one agent? If the answer is nothing you can measure, you have not earned the added complexity. Think of a kitchen brigade. The head chef keeps the plan and calls the passes. A handoff is a plate leaving one station for the next with everything the next cook needs already on it — seasoning, timing, garnish. Nobody adds a station because it looks impressive.

Sam: And in practice, the instinct I try to hold is: start one rung lower than feels natural. Every added agent is another identity, another context boundary, another place a handoff packet can lose a field. Climb on evidence, not on ambition.

Koko: That is the takeaway. Start lower, climb on evidence. Now, two failure modes that sit right next to the correct moves. The first is the loop without a bound. It runs until the budget is gone, it narrates progress the whole way so it feels like it is working, and the only reason it did not act on iteration forty is the hook at the edge. Remove the hook and you find out. The bound and the hook are not optional finishing details — they are the structure.

Sam: The version of this I keep seeing on teams is that the bound gets set generously at the start and then nobody revisits it. It drifts up. And then the loop is functionally unbounded in production.

Koko: The bound has to be a design decision, not a default. Second failure mode: the handoff that passes a summary instead of the full packet. The receiving agent inherits the conclusion and none of the constraints. It does not know what was ruled out, what the guardrails were, what the original brief said. It reasons from the summary and confidently goes somewhere the sender would never have gone.

Sam: Losing the constraints is worse than losing the content. You can reconstruct context, but if the receiving agent does not know what it cannot do, the handoff is broken from the first step.

Koko: The packet is the handoff. Not the summary of the packet — the packet.

Koko: Every run has states, and two of them are terminal. That is the fact we close on. A run is created, it runs, it waits — for a person, for a tool, for a clock — it resumes, and then it either completes with the outcome or it stops without it. Two ways out. That is it.

Sam: And waiting is not one of the two exits. That is the thing I always have to say out loud in a design review, because teams read a parked run as something broken.

Koko: Exactly. A run parked on a named approval is behaving correctly. And when it resumes — after the platform restarts, after the approver finally clicks — it resumes from where it stopped, not from the beginning.

Sam: Which is the whole point of durable execution. The state is persisted, not held in memory that can evaporate.

Koko: Right. Now let's walk it through the scenario we've been building toward. Procurement invoice, end to end, five stages. Stage one: intake reads the document into the schema. Stage two: matching compares it against the purchase order and the goods receipt. Stage three: assessment decides whether it clears the thresholds. Stage four: approval — anything above the ceiling routes to the named approver and the run waits. Stage five: release performs the one write to the ledger. Then notification goes out.

Sam: Notification after the write. That ordering is doing a lot of work.

Koko: It is, and we'll come back to it. But first — every stage in that pipeline has a contract. The write has a ceiling. And the run can be resumed at any stage if the platform is restarted underneath it. Nothing in that pipeline assumes a clean, uninterrupted world.

Sam: The analogy I reach for is certified mail. The letter is not lost because the recipient was out. It is held, it is signed for, and there is a record of every hand it passed through.

Koko: That is a good one. The run is not lost because the approver was in a meeting for two days. It is held at stage four, it has a record, and it resumes the moment the signature lands.

Sam: And the takeaway from the state model is: design the two terminal states before you design the happy path.

Koko: Say why.

Sam: Because a system that cannot express 'stopped without the outcome' has nowhere to put a failure. So it reports every failure as a success in a different shape. You see a green status, the ledger disagrees, and you find out in the reconciliation run three days later.

Koko: That is exactly it. Now — the failure mode we close the whole lesson on. And this one is specific. Notification before the action. The message goes out saying the invoice was released. The write then fails. Every downstream reader — the supplier, the finance team, the ERP — now believes something the ledger does not. The record and the world have separated, and you sent the signal that told everyone to trust the record.

Sam: The version of this I keep seeing on teams is that the notification feels like confirmation, so it gets moved up. It feels like closure for the user. And it is, which is exactly why it is dangerous — it is closure before the consequential thing actually happened.

Koko: Write, then notify. That is the sequence. The notification is not a step in the action — it is evidence that the action completed.

Sam: And if the write fails, the notification never goes.

Koko: Correct. Silence is better than a lie. Alright. Here is what this half of the course leaves behind in the room with you. An instruction contract — so the model knows what it is operating and what it is not. A context map — so you know what you are handing in and what it costs. A tool contract per write — ceiling, idempotency key, fail-closed default. A pattern chosen one rung below instinct — not the most impressive shape, the right one. And a run lifecycle with two ways to end, where waiting is a state and stopping without the outcome is something the system can say out loud.

Sam: Part Three is where you test whether any of it actually holds.

Koko: That is exactly right. Part Three is where a listener proves any of this is true — in production, under load, with real data and a real approver who is late. The method, the prioritization gates and scoring model, the workflow moves and the sorting lab — all of that is on the course page at KokoAI Academy, at koko knows dot A I. Everything you need to keep going is there. And you are more ready for that next step than you were an hour ago. That is not nothing.