The execution protocol

The six states Madebook can put an agent in, exactly what each one means, and the rules that decide which one you get.

Every reply Madebook sends to an agent carries a field called next_action. It holds one of six states. This page is what each state means, and what makes Madebook choose it.

The protocol matters to you even if you never read a raw API response, because it is why a session stopped, why it kept going, and why you were or were not interrupted.

Why it is six states and not a boolean

Before this existed, the agent-facing API answered with stop: true. That one boolean fused three completely different situations:

  • "You broke a rule that has an obvious compliant fix — fix it."
  • "A person has to decide this, and you may keep working on the rest."
  • "Stop, now, everything."

An agent reading one boolean cannot tell those apart. It either freezes on all three or ignores all three. Both failures are expensive and neither is the agent's fault.

Two principles decide where the line falls:

Do not interrupt a person because an AI made a mistake. Interrupt a person when the AI cannot safely resolve the situation itself. A deviation from a rule that names a compliant alternative is a fix, not a question — the answer is already written down, it just was not followed.

Blocking is scoped. Freezing a whole session over one pending decision wastes every step that does not depend on it. A gate names what is blocked and what is still allowed, and the agent works the rest of the plan.

Nothing in the protocol calls a model, and nothing in it trusts the agent's own account of whether it behaved. Every input is a row Madebook computed or a person set.

The six states

They are listed most severe first. That order is the precedence: when several are true at once — and they often are — the agent is told the most severe one, and the rest are carried alongside in also so nothing is silently dropped.

State What the agent is told to do
HARD_STOP Stop this session's work entirely and report. Do not attempt a workaround, and do not try to satisfy the rule by hiding what tripped it.
BLOCKED The named scope cannot proceed. Work the allowed scope or stop.
DECISION_REQUIRED A person must decide. Do not decide it yourself and do not implement the blocked scope. allowed_scope says what you may still work on.
REMEDIATE Something is wrong and you are authorised to fix it. You are given the instruction and the files. Fix it, then report again.
CONTINUE_WITH_WARNING Keep working. Something raised the risk or will need a person before merge. It does not need you to stop.
CONTINUE Nothing is in your way.

Every reply also carries reason (one sentence), reasons (every reason at the chosen state), also (the reasons at lower states), blocked_scope, allowed_scope, the open decisions, and the open remediations.

What produces each state

HARD_STOP

One thing only: an open policy violation with severity critical.

A high severity violation is serious and produces a remediation. critical is the category your organization defined as "never, under any circumstances", and an agent that works around one is worse than an agent that stops.

The reason names the policy, what matched, and the detail — for example: "Secrets in source was violated by AWS_SECRET_ACCESS_KEY. Found in config/deploy.sh. This is a critical control: stop, and do not work around it."

BLOCKED

Two causes.

  1. A person pulled the brake. Someone used the pause control on the session. The reason quotes the pause reason if one was given, and blocked_scope is all work in this session.
  2. The execution plan is not approved. The mission is high-risk and its plan is still proposed. blocked_scope is any code change; allowed_scope is reading the repository and revising the plan.

DECISION_REQUIRED

An open decision gate on this session. A gate is opened by the agent itself, through the MCP, when the mission, the architecture rules, the decisions and the policies together do not determine the answer — because answering would mean making a product, architecture, security or governance decision that is not the agent's to make.

Each gate carries a reference (DEC-001, DEC-002, …), a title, the question, an optional proposal, and the two scope lists. Up to 20 entries are kept in each scope list.

Gates opened by a person do not exist. A gate an agent did not open is just a conversation.

REMEDIATE

Three causes, and all three share one property: the correct answer is already written down.

  1. An open remediation request with severity required. These come from a reviewer asking for a fix, or from a rule.
  2. An architecture deviation from an enforced rule — but only when the rule was derived with confidence of 70% or more and is marked enforced. The reason names the compliant alternative: "redux-toolkit departs from this workspace's approach. Use React Query — chosen for server state in 31 of 34 components." Below 70% confidence, or where the rule is advisory rather than enforced, the same deviation produces CONTINUE_WITH_WARNING instead and says so: "(React Query, inferred with 55% confidence — advisory)". A rule Madebook inferred with low confidence is not something to hold an agent to as if it were law.
  3. A violated mission contract clause. The mission's own words disagree with what was built, and the agent has the mission, so it can act on it.

CONTINUE_WITH_WARNING

Things that are true, relevant, and not a reason to stop:

  • An open remediation request whose severity is not required.
  • The change's risk band has reached high or critical. The reason names the score, the band, and the gate the change will need before it merges.
  • A collision. Another session is building against a symbol this one just changed. The reason says so and adds: "Madebook is re-briefing it; you do not need to stop." Stopping the session that made the change is the wrong end — it did nothing wrong. The session building on the old shape is the one that needs the re-brief, and Madebook handles that side.
  • A policy action of block_merge fired. Nothing stops the agent writing the code; it will not ship until the policy's conditions are met.

CONTINUE

Nothing above fired.

Decisions: how one is resolved

A decision gate sits open until a person answers it in the workspace's Attention view. Resolving one takes two things:

  • a resolution — what was decided;
  • an instruction — what the agent should do next.

The instruction is the part that matters. A resolution without one tells the agent that something was decided and nothing about what to do about it, which is how a resumed session repeats the same mistake.

Nothing polls

A decision resolved at 14:02 does nothing until the agent reads it. The agent does not wait on it and there is no endpoint that blocks until an answer arrives.

Instead, the resolution is handed over once, on the agent's next brief, with the instruction attached — and that read stamps a delivered_at time. That timestamp is what makes "Madebook decided and the agent was never told" a different, visible state from "the agent was told and ignored it".

The same mechanism delivers new remediation requests: an open request becomes delivered the moment the agent picks it up.

The protocol text the agent is given

Madebook does not assume the client knows any of this. The whole protocol is included in every brief, in words, not left to the client's system prompt — because a client that does not know the state machine will read next_action: BLOCKED and carry on, and Madebook has no way to stop it from the outside. Restating it every time is the only enforcement an out-of-process agent can actually be given.

Four instructions in that text are worth knowing as an operator, because they shape how your agents behave:

  • Plan before you implement. Read the mission, the rules, the decisions and the repository, then propose an execution plan. On a high-risk mission the plan waits for a lead and no code change is accepted until it is approved.
  • Fix what you can; ask about what you cannot. If the planned implementation conflicts with a rule and there is an obviously compliant alternative, take the alternative and say what changed.
  • Do not poll. Continue the allowed scope and re-brief when the answer is needed.
  • Do not declare the mission complete. The agent reports implementation complete with the evidence it produced. Madebook decides whether the evidence gate is satisfied; the pull request and a person decide whether it ships.
← PreviousEvidence and gatesNext →The attention queue