Skip to content

Workload bundle schema

A workload bundle is the declarative operational profile for a mast deployment: one YAML file naming the specialists, tool catalog, budget, HITL policy, and edge trigger for one named workload. Bundles live at .agents/workloads/<name>.yaml (see .agents/ discovery) or in a workload directory passed to --workload=<path>.

This page documents the v0.1 subset — exactly the fields the shipped loader parses. The canonical full schema lives in docs/orchestration-design.md; fields beyond this subset (planner review knobs, isolation scope, bundle learning) land with their subsystems.

name: gke-triage
description: Autonomous triage of GKE cluster incidents.
mode: single_session
tool_catalog:
mcp:
- server: gke
tools:
- name: list_clusters
mutating: false
specialists:
- triage-classifier
- CrashLoopBackOff
- ImagePullBackOff
- _fallback
budget:
max_wallclock_seconds: 300
max_turns: 20
max_cost_usd: 5.00
hitl:
require_approval: true
safety:
watchdog: enforce
builtin_tools:
web_search: true
prompt_cache:
ttl: 5m
planner:
enabled: false
edge_trigger:
http:
path: /inject
auth: bearer
scheduled:
interval: 15m
jitter: 45s
prompt: Sweep every namespace for pods in CrashLoopBackOff and report what you find.
a2a:
expose: true
skill_name: incident-triage
skill_description: Investigate GKE pod-failure incidents.
auth:
scopes: [incident-triage.invoke]
agui:
expose: true
endpoint_path: /agui/incident-triage
description: Investigate GKE pod-failure incidents.
session_model: per_thread
state_projection: [plan, phase]
emit_reasoning: false
run_queue:
depth: 3
auth:
scopes: [incident-triage.run]
FieldTypeNotes
schema_versionintWhich bundle schema this file is written for. Currently 1, and omitting it means 1 — every bundle written before the key existed loads unchanged. A version this mast does not speak is a load error naming both numbers. See schema_version: below.
namestringRequired. Unique per deployment; used as the workload metric label.
descriptionstringHuman-readable; used in operator UIs and logs.
modestringsingle_session (default) or multi_session. Multi-session is vocabulary-only in v0.1 — declared intent, honored when the multi-session substrate lands (v0.2).
tool_catalog.mcp[].serverstringMCP server references, by name from the deployment’s mcp.json (HTTP or local stdio). Intersected against per-specialist tool allowlists at dispatch time.
tool_catalog.tools[].namestringTool name a per-tool policy override applies to. Names must be unique.
tool_catalog.tools[].mutatingboolOverrides the tool’s mutation classification for the recorded-effect outbox. This override is read before every other source, including an MCP server’s own readOnlyHint, so it is how you pin a tool your server classifies differently. Below it, an MCP tool is read-only if its server says so and mutating otherwise — including when the server publishes no annotation, which is indistinguishable on the wire from publishing false. Omitted means no override. Every applied override is audit-logged at startup.
tool_catalog.tools[].preconditionblockOptional. The re-read that decides whether an approval of this tool’s call is still fresh when the call finally fires — see precondition: below. Only consulted for calls covered by a change_set grant; a call the operator is answering right now needs no freshness check.
tool_catalog.tools[].precondition.readstringRequired in the block. The tool to re-read with. It must be declared mutating: false in the same catalog — a freshness check that changes the cluster is not a check — and since an unlisted tool is mutating by default, an undeclared read fails at startup rather than at the incident.
tool_catalog.tools[].precondition.argsmapFixed arguments for the read, e.g. {namespace: prod}.
tool_catalog.tools[].precondition.args_frommapArguments taken from the change itself: {name: deployment} reads the read’s name from this call’s deployment. This is what lets each call in a set be checked against its own object.
tool_catalog.tools[].precondition.fieldslist of stringsDotted paths into the read’s result that must not have moved. Omitted means the whole result is digested. For an MCP tool every path starts output. — that is how a structured MCP result arrives.
tool_catalog.tools[].captureblockOptional. What to record before a call to this tool changes anything, so that “how do I undo this” has an answer in the transcript — see capture: below. Consulted on every path a mutating call can take to the tool, not only the gated ones.
tool_catalog.tools[].capture.readstringRequired in the block. The read-only tool that records the prior state. Same rule as a precondition read, for a sharper reason: mast refuses to start rather than run a recording that changes what it records. It also may not be the changing tool itself — by the time that has run there is no prior state left to read.
tool_catalog.tools[].capture.argsmapFixed arguments for the read.
tool_catalog.tools[].capture.args_frommapArguments taken from the change: {name: deployment} reads the read’s name from this call’s deployment.
tool_catalog.tools[].capture.fieldslist of stringsDotted paths into the read’s result to record. Omitting them records the whole result — the opposite of a precondition’s default, and deliberately so: a capture that kept too little cannot restore, and the cost of keeping too much is a bigger row.
tool_catalog.tools[].capture.revertblockOptional. The call that puts the captured state back. Omitting it is honest rather than incomplete — the record still carries the old value, and mast sessions show says in as many words that this workload declares no way back.
tool_catalog.tools[].capture.revert.callstringRequired in the block. The tool that performs the undo — often the changing tool itself. It must be classified mutating: a call that changes nothing cannot undo a change, and offering one as a way back during an incident is worse than offering none.
tool_catalog.tools[].capture.revert.argsmapFixed arguments for the revert call.
tool_catalog.tools[].capture.revert.args_from_changemapRevert arguments taken from the change — how the undo addresses the same object the change addressed.
tool_catalog.tools[].capture.revert.args_from_capturemapRevert arguments taken from the recorded state, by dotted path: the old values, going back. A revert that names none of these is refused at load, because it re-applies the change rather than undoing it.
specialists[]list of stringsSpecialist names; resolve against the config root’s specialists/*.specialist.md. A roster with a SingleTurn classifier plus a _fallback Task specialist enables graph dispatch.
dispatchstringThe root shape this roster is built for: coordinator, graph, fanout, bounded, or auto. Empty leaves the choice to the caller. auto never picks bounded — a cost ceiling is declared, never inferred. A shape is a property of the roster, not of how the daemon happened to be launched, so the bundle is where it belongs — --dispatch overrides it only when an operator actually typed the flag.
fanout.max_concurrencyintUnder dispatch: fanout, how many analyst branches run at once. 0 (omitted) means the default, 4; a negative value means unbounded. Ignored under any other dispatch.
budgetblockSee below.
hitl.require_approvalboolWhen true, every specialist result pauses on a durable RequestInput interrupt until an operator resumes with a verdict.
hitl.on_mutationstringWhat happens before a call that would change something: require_approval (the default — the call parks on a durable interrupt, with its arguments, and fires only once an operator approves it), apply (run it, unattended), or dry_run (never run it; report what would have happened). Because this defaults to gating, a bundle that says nothing about mutation does not get to write; unattended writes have to be asked for. The block may also be spelled hitl_policy:; setting both is an error. See the write gate for the verdict an operator sends back.
hitl.change_set_ttldurationHow long an approval given with scope: change_set authorizes the set’s remaining calls for. Default 10m — far longer than an approve-then-execute round trip, far shorter than the span over which an operator forgets what they approved. It is the backstop, not the check: what an approval is really bounded by is the precondition: the tool declares.
safety.watchdogstringThe runaway-loop posture this workload ships with: warn (log only), feedback (mast’s default when nothing declares one — tell the model on its next turn, and end a turn whose model keeps repeating one call after being told), or enforce (also cancel the turn in flight and refuse every later turn until an operator resets). Unset is not warn: it means leave it to the host, which is what keeps --watchdog able to override a bundle in both directions. Precedence is --watchdog > safety.watchdog > the default, and the daemon logs which won at startup. Declare enforce on a workload whose tool loop is bounded by construction; see where the posture comes from.
builtin_tools.web_searchboolThe provider’s server-side web search, run inside the vendor’s infrastructure. Omitted means off, on every provider. See builtin_tools: below — this is reach the permissions gate cannot see, so mast makes you ask for it.
builtin_tools.url_contextboolThe provider’s server-side URL fetch-and-ground. Omitted means off. Gemini only; no Anthropic equivalent, and a bundle that asks for it on Claude gets nothing rather than an error.
builtin_tools.code_executionboolSandboxed code execution on the provider’s servers. Omitted means off. Gemini only.
prompt_cache.enabledboolClaude prompt caching. Omitted means on; false turns it off. Anthropic only; see prompt_cache: below.
prompt_cache.ttlstringBreakpoint lifetime: 5m (default) or 1h. Any other value refuses the bundle. A 1-hour write bills at 2x base input against 1.25x, so it pays only when turns are routinely more than five minutes apart.
planner.enabledboolv0.1 scaffold: switches the root agent to the supervisor-body planner with the bundle’s specialists as its invoke_specialist roster (--dispatch is then ignored). The planner’s run_shape_* vocabulary tools return not_implemented until v0.2.
edge_trigger.http.path, .authstringsInformational, and not wired — the inject server declares its routes globally and reads nothing from the bundle; per-workload path prefixes come later. Declaring a path does not create one: POST your envelope to /inject. A bundle that declares one is warned about at startup, and the declared path answers 404 naming the real route. See a declared path is not a route.
edge_trigger.scheduled.intervaldurationRequired in the block. How often the workload wakes itself, with nothing calling in — 15m, 1h, 24h. Minimum 1s. A malformed or missing value is a load error naming the file, because a cadence that fails to parse at runtime is a workload you believe is running and that never wakes up. See scheduled: below.
edge_trigger.scheduled.jitterdurationOptional random offset added to each fire, drawn afresh every time. Defaults to a tenth of the interval, capped at 30s; 0s is honored as a declaration. Must be shorter than the interval. It is not decoration: N replicas started by one rollout otherwise wake on the same second.
edge_trigger.scheduled.promptstringWhat the workload is being woken up to do. Delivered as prose after the wake-up envelope, so it reaches the roster as you wrote it. A schedule with no prompt runs the roster against the envelope alone, which is a workload guessing at its own job.
monitor.collect[].toolstringRequired in each entry. A wired tool mast runs on its own behalf at the top of each scheduled cycle, before the model is woken; the results arrive in the wake-up envelope under collected. Requires an edge_trigger.scheduled block — a collection with no cadence never runs. No tool named here may be reachable from any specialist’s allowlist, and the daemon refuses to start if one is. See monitor: below.
monitor.collect[].argsmapLiteral arguments for the call, e.g. {transitions: "new,escalated,resolved"}. There is no args_from: a collection call is not about any particular object, so there is nothing to map arguments from.
monitor.collect[].asstringThe key this call’s result is filed under in the envelope. Defaults to the tool name; needed only when one workload collects from the same tool twice. Two entries filed under one key is a load error.
monitor.transitions_fromstringOptional. Names the monitor.collect key whose result carries the run-to-run classification — what is new, escalated, resolved since the last cycle. That result is parsed into the envelope’s transitions block instead of being passed through raw. Must name a key some collect entry files a result under, or it is a load error. It names where the classification comes from, never what it may say: mast has no vocabulary of transition classes. See transitions_from: below.
monitor.notify.conversationstringRequired when a notify: block is present. Where a speaking cycle posts — the conversation id switchboard knows, e.g. #sre-oncall or a platform id. Requires an edge_trigger.scheduled block, for the same reason collect does: a cycle speaks at the end of a cycle, so with no cadence it never speaks. The ingress URL and its bearer token are the daemon’s (--notify-url, MAST_NOTIFY_TOKEN), not the bundle’s — deployment facts, so one bundle moves between staging and production unedited. See notify: below.
monitor.notify.digest_afterdurationOptional deadman. After this long with nothing sent, the next cycle speaks whether or not anything changed. Omitted or 0s = no deadman, and the workload may stay silent indefinitely. Wall-clock, not a count of quiet cycles: a monitor that has been quiet for a week is otherwise indistinguishable from one that died a week ago.
monitor.ack.toolstringOptional. The wired tool an operator’s acknowledgement is forwarded to, which arms POST /monitor-ack on the daemon; without the block that route answers 404. Unlike collect and notify it needs no cadence — an ack arrives from an operator, not from a cycle. Fenced like a collect tool (reachable from no roster), and refused if it is also a collect tool: a cycle that acked what it just classified would suppress findings nobody asked to suppress. See ack: below.
monitor.ack.argsmapLiteral arguments merged under the two mast supplies from the request itself, subject_key and ack_by. Deployment policy goes here — which cluster, how long a suppression lasts. Pinning either reserved name is a load error: a bundle that named the acker would name them for everyone.
a2a.exposeboolOpt this workload into the A2A server surface (--a2a-listen). Default false — A2A exposure is an external contract, so it is never automatic.
a2a.skill_name, a2a.skill_descriptionstringsThe skill id/name and human-readable summary published on the agent card. skill_name defaults to the workload name; skill_description to the workload description.
a2a.input_schema, a2a.output_schemamapsA mast-side convention only: mast may validate inbound task inputs against them and fold them into the skill description. Spec AgentSkill has no schema fields, so they do not round-trip through the agent card as machine-readable schema.
a2a.auth.required, a2a.auth.scopesbool, list of stringsPer-skill auth policy. scopes are enforced per call when a token validator is configured (MAST_A2A_TOKEN): a caller whose token lacks a scope is refused 403. MAST_A2A_TOKEN is one token carrying every exposed skill’s scopes, so that 403 needs a host-supplied validator to become reachable — see scopes and the shared token.
agui.exposeboolOpt this workload into the AG-UI server surface (--agui-listen). Default false — like A2A, AG-UI exposure is a public turn-driving endpoint, so it is never automatic.
agui.endpoint_pathstringThe HTTP path the workload’s run endpoint is served at. Must start with /. Defaults to /agui/<name>.
agui.descriptionstringSurfaced in the /agui/agents.json discovery descriptor; defaults to the workload description.
agui.session_modelstringHow a run maps to a mast session: per_thread (default — one continuing session per AG-UI threadId, matching chat UX) or per_run (a fresh session per runId, for stateless one-shots). The daemon always derives and namespaces the session id; a client never supplies a raw one.
agui.input_schemamapA mast-side convention only: an optional JSON-Schema-shaped hint surfaced in the discovery descriptor so a client can render an input form. AG-UI’s RunAgentInput has no schema field, so it does not constrain the wire input.
agui.state_projectionlist of stringsAllowlist of runtime state keys published to the client as StateDelta patches. Empty (the default) publishes nothing. A key on the list is emitted as an RFC 6902 {"op": "add", "path": "/<key>", "value": …} whenever the run writes it; a key not on the list produces no operation at all, so a client cannot tell that it changed. Treat this as a publication decision, not a display preference: session state holds whatever the runtime put there, including approval grants and captured change sets, and the AG-UI client is a browser. An empty or duplicated entry is refused at startup; a key the workload never happens to write is accepted. The enabled list is advertised on the public discovery descriptor as capabilities.state_keys, so a client can lay out its panels before the first patch.
agui.emit_reasoningboolWhether this workload streams the model’s thinking to its AG-UI clients, as the spec’s REASONING_START / REASONING_MESSAGE_* / REASONING_END frames. Defaults to false, and false emits nothing at all — not an empty phase bracket, not a redaction marker, so a client cannot learn that the model deliberated. A chain of thought is not a draft of the answer: it is where the model talks itself out of things, and where a prompt injection shows its working. The answer is addressed to the user; the reasoning is addressed to nobody. Turning it on is a decision about a browser-reachable surface, and the daemon logs a warning at startup naming the workload. The provider’s thought signature is never published under either setting — it is a replay credential, not a thought — so a thinking block with a signature and no prose produces no frame. The setting is advertised on the public discovery descriptor as capabilities.reasoning, so a client knows before a run whether to render a “thinking” affordance at all.
agui.run_queue.depthintHow many runs may wait on one AG-UI thread while another is executing. Defaults to 3, so a thread admits four at once and the fifth is refused with 409 and a Retry-After before the stream opens — see run_queue: below. 0 is legal and means no concurrency: one run at a time per thread, the rest refused. A negative value is refused at startup.
agui.auth.required, agui.auth.scopesbool, list of stringsPer-endpoint auth policy. scopes are enforced per run when a token validator is configured (MAST_AGUI_TOKEN): a caller whose token lacks a scope is refused 403. The list is also published on the discovery descriptor, where it states this workload’s requirement — not a property of any token mast issues. MAST_AGUI_TOKEN is one token holding every exposed workload’s scopes, so on a daemon configured that way the 403 is unreachable: see scopes and the shared token.

schema_version: — and why an unknown key is refused

Section titled “schema_version: — and why an unknown key is refused”

The bundle is edited by operators who never import Go, so it versions on its own clock rather than mast’s (stability). The current schema is 1:

schema_version: 1
name: gke-triage

Omitting it means 1. Every bundle written before the key existed — including all of the examples on this page — keeps loading exactly as it did, and there is no migration to run. Write it down if you want the file to say out loud what it was written against; leave it out and nothing changes.

A version bump is for a key that changes shape or meaning, not for a key being added. builtin_tools: arrived in v0.8 and the schema stayed at 1, because an older mast reading a newer bundle is precisely the case strictness already catches, by name. What would move the number is budget: changing units, or hitl: changing what its default does.

A bundle declaring a version this binary does not speak is refused, and the error names both numbers, because the operator holding the file needs to know which of the two to change:

workload: "workload.yaml": bundle declares schema_version 2 and this mast
speaks 1; upgrade mast, or point it at a bundle written for schema 1.
Refusing rather than loading the keys it happens to recognise: this file
declares which tools may run without an operator

An explicit schema_version: 0 is also refused. Absent and 0 are different things: absent is a file written before the key existed, and a literal 0 is someone reaching for a version number and getting it wrong.

An unrecognised key is a load error, not a warning

Section titled “An unrecognised key is a load error, not a warning”

Misspell a key and mast refuses to start, naming the key:

workload: parse "workload.yaml": yaml: unmarshal errors:
line 8: field tool_catalogue not found in type workload.Bundle
An unrecognised key is refused rather than ignored, because a dropped key
in this file is a tool that silently stops being gated. Check the spelling
against the bundle reference; if the key belongs to a newer bundle schema,
the bundle should declare schema_version and this mast is too old to read it

This is stricter than most YAML config and it is deliberate. This is the only file in a mast deployment that can declare a tool safe to run without an operator, and mast’s own predicate is default-deny-unknown. The failure being designed against is a misspelled block — tool_catalogue:, hitl_polciy:, saftey: — that leaves a whole section of policy unapplied while the daemon logs a clean start and the workload runs all night. A WARN at boot is not a control; nobody is reading the log at the moment it scrolls past.

The strictness reaches nested keys too, which is where the sharper version of the same bug lives: mutatin: true on a catalog entry leaves the tool catalogued, so nothing looks missing, while the tool quietly reverts to default-deny-unknown.

The order matters when both go wrong at once. A real bundle from the future does not arrive carrying only a version bump — it arrives carrying the keys that motivated the bump. mast reads schema_version first, on its own, so what you are told is “this bundle is from a newer schema” and not “field quarantine_policy not found”, which reads as a typo in a key you copied out of correct documentation.

Specialist frontmatter is strict too, and has no version of its own

Section titled “Specialist frontmatter is strict too, and has no version of its own”

The same rule applies to the YAML frontmatter in a specialists/*.specialist.md file, for a reason specific to that file: tools: is the one key that fails in the unsafe direction. An absent tools: block means the specialist inherits every MCP server the workload wires, so a misspelled toosl: does not narrow the specialist to the servers its file carefully lists — it hands over the whole surface, and nothing downstream can tell that apart from an author who meant to inherit. (capability: is the milder case: absent resolves to read_only, so misspelling it fails toward the safe value.)

Frontmatter deliberately takes no schema_version of its own, and writing one is an error. A specialist is only ever reached through a bundle that names it, so the bundle’s version already governs the roster; a second independently-versioned artifact would multiply the compatibility matrix across every specialist file in the tree for a document that is mostly prose. If the frontmatter ever needs a breaking change, it rides the bundle’s version bump.

dispatch: fanout runs the whole roster against one incident at the same time and merges what comes back:

dispatch: fanout
fanout:
max_concurrency: 2
specialists:
- dns
- rbac
- quota
- _synthesis

Three constraints the loader enforces at startup, rather than letting a run discover them:

  • _synthesis is a reserved specialist name and is required. It is the one that receives every analyst’s finding and writes the single report an operator approves. A roster without it is refused; every other Task specialist in the roster is an analyst.
  • Analysts must be read-only. Every branch runs before the one approval gate, so a mutation in a branch is a mutation no operator was offered the chance to refuse. A roster whose analysts can reach a mutating tool is refused with the tool named — either drop it, or, if it really is read-only, classify it with tool_catalog.tools[].mutating: false. (request_operator_input passes the read-only check but still cannot be in a branch: a branch has no gate to pause on.)
  • Each analyst must name the tools it needs. A branch with no tool allowlist is refused rather than silently inheriting the catalog.

An analyst that returns nothing is reported to _synthesis as silent, not dropped. Approving the merged report finishes the run without re-running any analyst — including after the daemon restarts, since branch events are in the session log the run state is reconstructed from.

The shipped GKE triage bundle is not a fan-out roster — it carries a change executor, and a branch check refuses even a declared one, since a branch has no gate to pause on — so fan-out ships its own read-only example at examples/workloads/ns-audit.

dispatch: bounded is for the workload whose value is that it cannot get expensive: one cheap model call, a report forced to a schema, and a step count an operator can read off the meter rather than infer from how long the run took.

dispatch: bounded
specialists:
- incident-report
specialists/incident-report.specialist.md
---
description: Classifies one incident and returns the finding report.
mode: SingleTurn
tier: small
output_schema: ../schemas/finding.json
---

The roster is built as a single node with no orchestrator above it, so there is nothing in the shape that can delegate, retry, or take a second turn. The specialist’s reply is validated against output_schema: before the turn ends — a model that answers in prose fails the run instead of returning an unparseable paragraph that reads like success.

Four things are refused at startup, each naming what it found, because each one silently un-bounds the run:

  • A roster that is not exactly one specialist. The error prints the count and the names.
  • A specialist not in SingleTurn mode. A Task specialist runs a tool loop, which is however many calls it takes. A spec with no mode: at all is reported as Task (the default for a spec with no mode:) — the author wrote nothing and the default is what has to be named.
  • A specialist with no output_schema:. Without it, one call buys a paragraph nothing downstream can read.
  • planner.enabled: true. The planner is the orchestrator the shape is defined by not having.

dispatch: auto never infers this shape: a one-specialist roster is an ordinary coordinator, and imposing a cost ceiling the bundle did not ask for is not a favor. The worked example is examples/workloads/bounded-triage, on the same finding.json report contract the GKE triage bundle uses.

Everything after the frontmatter is sent to the model unchanged. There is no placeholder syntax, no escape sequence and nothing to quote: braces, ${...}, {{...}} and JSON all arrive as typed. The same is true of a coordinator’s instruction: in this file and of the planner’s prompt.

The optional marker is the one removal. {project?} was the supported way to ask for session state, and session state is no longer reachable from a prompt by any spelling. A specialist body that still contains one is refused at load, naming the file, every offending line and the key each one asked for — because the alternative is rendering {project?} as itself and saying nothing:

specialists: "Diagnose.specialist.md": a placeholder in the template body no longer
injects anything — mast sends instructions verbatim
line 4: {project?} → asked for session-state key "project"

{artifact.report?} is refused on the same grounds, though it never loaded anything in the first place: mast runs no artifact service.

To get a value in front of a specialist, put it in the request, or have the caller build the instruction with the value already in it.

A specialist declares whether it may change anything:

---
description: Applies one approved remediation and reports what it did.
capability: change_executor
---

The values are read_only and change_executor. read_only is the default, so a specialist that says nothing about capability gets the safe one.

Mast refuses to build a roster in which a read-only specialist can reach a mutating tool, naming the specialist, the tools, and the fix. Three shapes are refused:

  • it names a mutating tool in tools.mcp[].tools or tools.builtin;
  • it grants itself a whole MCP server (- server: gke with no tools:), since whatever that server adds later is unreviewed;
  • it declares no tools.mcp at all while the bundle ships a tool_catalog — inheriting the catalog inherits everything mutating in it.

Fix any of them by enumerating the read-only tools the specialist needs, by writing mcp: [] if it needs none, or by declaring capability: change_executor if it really is meant to change things. SingleTurn specialists are exempt; the mode carries no tools.

“Mutating” is the same test the write gate (hitl.on_mutation, above) and the effect log use — including its default-deny-unknown rule, so a tool your tool_catalog has not classified counts as mutating and will fail the roster rather than the incident. Classify the catalog with tool_catalog.tools[].mutating.

An allowlist is applied by dropping what does not match, so a name that matches nothing is not an error — it is a capability that quietly is not there. Both halves of an entry can go wrong that way, and mast answers each at the earliest point it honestly can.

A server the workload does not declare fails the roster at startup, naming the specialist, the name, and the servers tool_catalog.mcp does declare:

compose: specialist "stuck-pod" allows MCP server "loggging", which the
workload's tool_catalog.mcp does not declare (it declares "gke", "logging",
"monitoring"); the allowlist is applied by dropping what does not match, so
this grants the specialist nothing from it and would not have been reported
at run time. Fix the name, or add the server to tool_catalog.mcp

A tool the server does not serve cannot be checked that early: knowing what a server serves means calling tools/list, and mast’s toolsets are lazy so that a bundle still loads when a server is down. It is reported the first time that specialist’s toolset lists, once, at WARN:

WARN ALLOWLIST NAMES A TOOL THE SERVER DOES NOT SERVE — the specialist holds
fewer tools than its file says
specialist=scale-outage mcp_server=gke unmatched=list_datasets,query granted=1

Naming fewer tools than a server offers is the whole point of an allowlist, and is silent. Only naming more is the mistake. A bundle that declares no tool_catalog.mcp has not said what exists, so the startup half is skipped for it and only the warning applies.

Every change_executor in a roster is logged at startup, so the answer to “which specialists here can change my cluster” is one log line rather than an intersection of three files. The shipped GKE triage bundle logs exactly one.

This is a stronger guarantee than prompt wording. A diagnoser told “do not mutate anything” is one persuasive incident away from doing it; a diagnoser that holds no mutating tool has nowhere to go.

A specialist file may declare its own model in frontmatter, so a roster can run cheap analysts under a frontier synthesizer instead of billing every specialist at one tier:

---
description: Inspects pod state and returns a 3-bullet digest.
model: claude-haiku-4-5
---

Specialists that declare no model: inherit the process model (--model). An override is dispatched by model id, exactly like --model — the --provider alias only disambiguates the Anthropic backend — so an override may name a different provider than the parent. Resolution is memoized per model id, so eight specialists on one tier share one client.

Two behaviors worth knowing before you tier a roster:

  • A declared override that cannot be resolved fails startup. It is never quietly downgraded to the parent’s model, because a bundle that reads as tiered while running everything on one tier is worse than one that refuses to start. Credentials for every provider named in the roster must resolve at construction.
  • Offline fakes collapse overrides. Under --model=echo, scripted, or toolactor, every override resolves back to that fake, so a tiered bundle still runs credential-free in smoke and acceptance runs.

Naming a concrete model id binds the bundle to that provider. When what you mean is “this step is not worth the frontier model” rather than “this step needs Haiku specifically”, declare a tier instead.

A specialist may declare how much model it is worth and let the running provider answer with a concrete id:

---
description: Inspects pod state and returns a 3-bullet digest.
tier: small
---

The values are small, mid, and frontier. Mast resolves the tier against the provider it is actually running (internal/taskclass.ModelForTier), so the same bundle reads the same and costs the right thing on either backend:

tierGeminiAnthropic
smallgemini-3.5-flash-liteclaude-haiku-4-5
midgemini-3.5-flashclaude-sonnet-5
frontiergemini-3.8-flashclaude-opus-5

Which provider a tier resolves against is the one mast dispatches on: the --provider alias when you passed it, otherwise the root model id’s own prefix. A root model whose provider cannot be told from either — say a custom id under no known prefix — fails startup asking for --provider, rather than guessing a vendor and billing you for the guess.

Everything above holds for tiers too: an unresolvable tier fails startup instead of falling back to the parent’s model, resolution is memoized per resolved id (twelve tier: small analysts share one client), and offline fakes collapse every tier back to the fake so the bundle still runs credential-free. Each resolution is logged at startup with the tier and the id it became.

A spec may declare model: or tier:, not both — that is a load error naming the file, not a precedence rule. The two say different things, and a bundle that says both has not decided which it means.

The shipped ns-audit bundle is the worked example: four tier: small namespace analysts under one tier: mid synthesis step.

A specialist file may declare the shape of what it returns:

---
description: Diagnoses OOMKilled container terminations.
output_schema: ../schemas/finding.json
---

The value is a path to a JSON-Schema document (.json, .yaml or .yml), resolved relative to the specialist file’s own directory — so ../schemas/finding.json means the same thing whether the roster sits in a workload bundle or a shared config root.

It is a file reference rather than an inline block on purpose. A report shape is a contract between the specialist that produces it and every consumer that reads it; inlining it in one specialist’s frontmatter makes that contract private to that specialist, and a roster of a dozen diagnosers ends up with a dozen copies that drift. The shipped gke-triage-routed bundle points all twelve diagnosers at one schemas/finding.json.

A violation is a refusal, not a warning, and the shape is the same in both agent modes:

  • Task mode — the schema becomes the auto-injected finish_task declaration. A non-conforming call comes back to the model as a validation error naming the offending key, and the model can correct itself within its turn budget.
  • SingleTurn mode — the reply is validated on the way out. A violation refuses the delegation; the caller sees an error naming the key, with no result attached.

Either way non-conforming output never becomes the specialist’s answer, and the caller — not just a log line — learns that it was refused.

The document is read and checked when the roster loads, not when a specialist first runs, so a broken contract fails startup with the file named. Refused at load time: unknown keys (a misspelled propertys: would otherwise produce a schema that constrains nothing), a node with no type, an array with no items, an object with no properties, a required name that is not a declared property, and a top level that is not an object.

That last one is a mast restriction rather than an ADK one, because ADK’s two modes disagree about non-object schemas: Task wraps a scalar under a result key, while SingleTurn unmarshals the reply into an object before it consults the schema at all, so a scalar contract can never validate there. Rather than let one document mean two things, mast requires an object. A report contract is an object anyway.

Mast does not interpret the schema, with exactly one exception. There is no built-in report type; the shape belongs to the workload.

The one property mast reads: proposed_change

Section titled “The one property mast reads: proposed_change”

A report can carry the calls it recommends, not just prose describing them. Declare a proposed_change array and mast will check it:

"proposed_change": {
"type": "array",
"description": "The executable form of your recommendation …",
"items": {
"type": "object",
"properties": {
"tool": {"type": "string"},
"arguments": {"type": "string"}
},
"required": ["tool", "arguments"]
}
}

Every entry has to name a tool the workload declares in its tool_catalog and carry arguments that fit that tool’s own input schema. Both are checked at the moment the report is returned, before it becomes the specialist’s answer. A report naming an unknown tool, or arguments the tool would reject, comes back to the specialist as an error it can correct — the same refusal shape as a schema violation, not a failed run.

When the roster’s change executors have enumerated their MCP allowlists, the check narrows further: the entry has to name a tool one of them can actually run. This is the difference between a call this daemon holds and a call that will fire if an operator approves it, and the gap between the two is where an approval ends with nothing happening. An executor that took an un-enumerated grant has no finite surface to check against, so the narrower check is skipped; an executor whose declared surface is only tools.builtin has an empty one and every proposal is refused, which mast warns about at startup — built-in tools are a declaration, not a grant (see specialists).

arguments is a JSON object encoded in a string — "{\"namespace\":\"prod\",\"replicas\":2}", or "{}" for a tool that takes none. It has to be, because its keys are whichever tool the entry names and no report schema can declare them in advance; an object property with no declared properties is refused at load time (above) for exactly the reason that it would accept anything. Mast parses the string and validates it against the real tool’s real schema, which is a stronger check than the report schema could have made.

An empty list is a complete report. A specialist that cannot name an exact call — the fix needs a human decision, or a tool the workload was not given — returns [] and says why in its own escalation field. Nothing is recorded and nothing is refused. A roster that does not declare the property at all is unaffected.

What the property buys: under graph dispatch a finding whose change set the operator approved is handed to the roster’s change executor verbatim, so the call that fires is the call that was on screen. See approvals.

precondition: — what makes an approval stale

Section titled “precondition: — what makes an approval stale”

An operator answering scope: change_set authorizes calls that have not fired yet. What should void that authorization is the cluster changing underneath it — not a clock running out. But mast cannot work that out on its own: a tool is opaque to it, so it does not know which tool reads the object a write is about, or which of the write’s arguments names that object. The bundle knows both, so the bundle declares it:

tool_catalog:
tools:
- name: get_deployment
mutating: false # required: the read must be read-only
- name: scale_deployment
mutating: true
precondition:
read: get_deployment
args_from: {name: deployment} # the read's "name" <- this call's "deployment"
args: {namespace: prod} # …plus anything fixed
fields: [output.replicas]

The read runs twice: once when the operator answers, to snapshot the world they answered about, and once immediately before each granted call fires. If a declared field moved in between, the grant is voided and the call is re-parked with a question that names the field and both values — output.replicas was 1 at approval and is 5 now. Every field is reported, not the first, because an operator re-reading the question needs the whole delta.

Four things to know before writing one:

  • A precondition over the field the set itself rewrites invalidates its own set. The snapshot is taken once, at approval. So a two-call set that scales the same object to 2 and then to 3 has call 1 move what call 2 was checked against, and call 2 goes back to the operator. The fix is args_from: check each call against its own object, and a set that touches two Deployments works while a set that touches one twice, by design, does not.
  • The read must be declared mutating: false. An unlisted tool is mutating by default (default-deny-unknown), so a catalog that simply forgot to list the read fails at startup with the declaration named — not at 3am with a “freshness check” that was writing to the cluster.
  • fields: paths start output. for MCP tools. A structured MCP result arrives wrapped in an output property. A path that misses the wrapper matches nothing, every read digests identically, and the check silently compares nothing to nothing — which looks exactly like “the cluster never moves”.
  • Omitting fields: digests the whole result. That is right for a narrow read and wrong for a chatty one, where a timestamp or a resourceVersion in the payload makes every re-read look like drift. Narrow the read rather than filtering a wide one here.

A tool that declares no precondition is bounded by hitl.change_set_ttl alone, and the parked question says so in those words. If mast cannot evaluate a declared precondition at all, the set is not grantable: the question says the calls must be approved one at a time, and scope: change_set is refused rather than granted on a check that is not running.

capture: — what a change overwrote, and how to put it back

Section titled “capture: — what a change overwrote, and how to put it back”

mast can park a mutating call, run it, and record that it ran. Until it also records what was there before, an operator who approves a change and watches it make things worse has no way back except reconstructing the old state by hand, under time pressure, at 3am.

So the write gate takes a snapshot before the call fires — and, when the bundle can name one, the call that restores it:

tool_catalog:
tools:
- name: get_deployment
mutating: false # required: a recording must not change what it records
- name: scale_deployment
mutating: true
capture:
read: get_deployment
args_from: {name: deployment} # the read's "name" <- this call's "deployment"
fields: [spec.replicas] # what to keep
revert:
call: scale_deployment
args_from_change: {deployment: deployment} # same object…
args_from_capture: {replicas: spec.replicas} # …old value

mast sessions show then prints, beside the transcript:

Prior state captured:
Changed by: scale_deployment(deployment=api, replicas=10)
Captured: 2026-09-05T09:00:00Z by get_deployment(name=api)
spec.replicas = 3
Undo: scale_deployment(deployment=api, replicas=3)
(proposal, not a button: it goes through the write gate like any other change)
scale_deployment {"deployment":"api","replicas":3}

mast does not fire the undo. The recorded revert is a proposal. Running it sends it back through this same gate, with a person answering, because an automatic rollback is a mutating call nobody approved — decided by the component whose entire job is to not let that happen.

Five things to know before writing one:

  • It looks like a precondition: and it is not one. A precondition asks is the world still what it was when this was approved, so it wants the narrowest read that settles the question and keeps only a digest. A capture asks what was here before I overwrote it, so it keeps the values — they are what goes back into the revert. The defaults for fields: are opposite for exactly that reason.
  • The capture happens before the call, so a failure costs nothing. If the read fails, or the declaration cannot be honored, the call is refused and the cluster is untouched. That is the whole reason the work happens up front: the alternative is acting first and then finding out no record was taken, which leaves an operator believing in an undo that does not exist.
  • A revert whose arguments all come from the change is refused at load. It re-applies the change rather than undoing it, and it is shaped closely enough like an undo to be believed by whoever reads the record during an incident. At least one argument has to come from args_from_capture.
  • Omitting revert: is a complete declaration. Plenty of changes have no inverse a workload can name — delete_pod does not invert, and a patch inverts only over the fields it touched. The record still carries the old value, and the view says the undo is undeclared and names the tool, rather than going quiet in a way that reads as “an undo exists somewhere”.
  • A capture proves the record exists, not that the revert works. Nothing here executes a revert to check. A workload that wants that assurance has to exercise it.

A deployment that declares captures but has no seam to run reads still starts, and says so at startup — the declaring tools’ calls are then refused one at a time, with the reason. The failure that warning closes is a bundle author seeing a clean start and believing their changes became reversible.

edge_trigger.http is accepted, validated as a bundle field, and then read by nothing. The inject server’s route table is fixed at construction; no part of it consults the workload. This has been true since the spike, and the field’s own definition says so — but from outside, a field documented as informational used to be indistinguishable from one that works:

edge_trigger:
http:
path: /alert
auth: bearer
$ curl -X POST http://127.0.0.1:7777/alert
405 Method Not Allowed

405 reads as a verb mistake, so the time goes into the emitter rather than the bundle. Two things changed, neither of them a new capability:

  • Startup says it. A bundle declaring a path is warned about next to the write gate and watchdog posture:

    WARN edge_trigger.http IS NOT WIRED — the declared path serves nothing
    declared_path=/alert declared_auth=bearer endpoint="POST /inject"
  • The unmatched path says it. An unknown path now answers 404 and lists the routes this daemon actually serves; a known path with the wrong verb answers 405 naming the verb it wants (GET /inject → “takes POST, not GET”). Previously every unmatched GET was absorbed by the health route and answered 200 ok, which a relay reads as success.

The declaration is warned about rather than refused: it has always been inert, and failing a bundle that runs today over a field that never did anything would be a break with no safety behind it. Per-workload path prefixes remain deferred — the fix is to the honesty of the answer, not to the routing.

scheduled: — a workload that wakes itself

Section titled “scheduled: — a workload that wakes itself”

Every other way into a mast daemon needs something outside it: an inbound POST, an operator, or a cron entry holding your schedule on mast’s behalf. edge_trigger.scheduled lets the bundle hold it:

edge_trigger:
scheduled:
interval: 15m
jitter: 45s
prompt: Sweep every namespace for pods in CrashLoopBackOff and report what you find.

Four things to know before declaring one:

  • The cadence is anchored, not restarted. Fires land on anchor + k×interval, and the anchor is written to the session store the first time the trigger comes up. A daemon that is redeployed twice a day resumes the phase it had rather than quietly moving a 02:00 sweep into the afternoon — the failure where a schedule keeps working and stops meaning what it said. (The anchor lives on a bookkeeping row, not a session; it never appears in mast sessions list.)
  • A tick the daemon was down for is skipped, not caught up. Coming back from an outage that spanned three ticks fires none of them and logs one line naming how many were dropped and over what window. A periodic run samples the current state of the world, so a sample nobody took is owed to nobody — and catching up means a crash-looping daemon buys a fresh backlog of model runs at every restart, about the crash. If you need every occurrence to run, a schedule is the wrong shape: post them.
  • Every fire is a fresh session, and it runs as mast:scheduler. The session is named for its tick and listed like any other, so a scheduled run is as readable after the fact as an injected one. The identity is namespaced, so no human login can produce it and no audit row can be misread as somebody’s. A mutating call inside a scheduled run still parks for a real approver under hitl.on_mutation — unattended is not unsupervised — and the run is bounded by the same budget: block as everything else.
  • One replica fires the cadence; the others say they are not. Two replicas sharing a session store no longer both fire: the first to start takes a lease and drives the schedule, and every other one logs at ERROR that it will not, naming the instance that does. This is a refusal, not leader election — a passive replica stays passive for its whole life and does not take over if the driving one dies; your orchestrator restarting the dead pod is what restores the cadence. jitter still staggers fires within one instance and was never a deduplication mechanism. See scaling a scheduled workload and #345.

Fires are counted by mast_scheduled_fires_total{workload,outcome} — ran, skipped (a tick that came due during a drain), error, and missed (one per tick coalesced away after an outage). A run that fails is not retried: the next tick is the retry, and it samples a fresher world.

monitor: — the facts a cycle gathers for itself

Section titled “monitor: — the facts a cycle gathers for itself”

A scheduled fire on its own wakes the model with a tick and a prompt, and leaves it to work out what to look at. monitor.collect runs the looking first, as mast rather than as the model:

edge_trigger:
scheduled:
interval: 15m
monitor:
collect:
- tool: k8s_cluster_health
as: health
- tool: k8s_findings_diff
args: {transitions: "new,escalated,resolved"}
as: transitions
transitions_from: transitions

The calls run in declaration order, serially, before any model call. Their results reach the roster inside the wake-up envelope:

{
"kind": "scheduled",
"workload": "cluster-watch",
"tick": "2026-08-21T10:00:00Z",
"collected": {
"health": { "…": "whatever the tool returned" }
},
"transitions": {
"scanned": 412,
"records": [
{
"subject_key": "prod/checkout-7d9f/OOMKilled",
"transition": "escalated",
"fields": { "severity": "critical", "prev_severity": "warning" }
}
]
}
}

Everything named in collect lands under collected as the tool returned it. The one key named by transitions_from is the exception: it is parsed, and it moves — it appears under transitions and not under collected, so the model is never handed two spellings of the same fact.

Why this is not just a tool the model holds

Section titled “Why this is not just a tool the model holds”

Because of what the interesting tools are. Knowing what changed since the last run means asking something that keeps per-run state, and a tool that advances persisted state as a side effect of answering is a mutating tool — correctly so. Under the default hitl.on_mutation: require_approval, a model holding that tool parks the cycle for an operator on every fire. An unattended monitor that needs someone awake to authorize finding out whether anything changed is not unattended. (And a tool nothing has classified is mutating by default, so this is the common case, not a corner of it.)

So the collection is mast’s. Three things follow, all of them deliberate:

  • Nothing gates it, because no model asked for anything. The write gate stays registered and stays in force for everything the model does call.
  • It costs zero model calls, by construction rather than by tuning — a leg the model is not part of cannot spend a token. A monitoring cycle on a bounded roster therefore costs exactly one model call, the same as an injected incident.
  • mast learns nothing about your domain. It runs the calls you named and passes the results through unchanged. What a transition means is the collected tool’s business.

transitions_from: — the classification comes from the tool

Section titled “transitions_from: — the classification comes from the tool”

A monitor’s real question is not “what does the cluster look like” but “what changed since last time”, and answering that needs per-run state. The tool that keeps it — k8s-lookout’s findings diff, or anything shaped like it — already does the classifying. transitions_from points mast at that result so the transitions ride the envelope as data rather than as a wall of text the model has to re-read:

monitor:
collect:
- tool: k8s_findings_diff
args: {transitions: "new,escalated,resolved"}
as: transitions
transitions_from: transitions

mast has no vocabulary of transition classes. There is no enum, no severity comparison, no fingerprinting, no “is this really new” second opinion. A record’s transition value is whatever string the classifier wrote, carried to the model verbatim — if your tool emits quiesced, the model sees quiesced. transitions_from names where the verdict comes from; it never constrains what the verdict says. Two implementations of “what changed” is one more than can be right.

The named tool answers in text: one record per line, then a summary line. Each record is logfmt or flat JSON (detected per line, so a stream may mix them), and needs two keys — subject_key and transition. Everything else becomes fields:

subject_key=prod/checkout-7d9f/OOMKilled transition=escalated severity=critical prev_severity=warning
{"subject_key":"prod/api-5c1/CrashLoopBackOff","transition":"new","severity":"warning"}
scanned=412 findings=2 elapsed=1.4s

The trailing scanned=<n> findings=<n> elapsed=<d> line is mandatory, and findings= must equal the records above it. That is the only judgement mast makes about the stream, and it is about completeness, not correctness: a truncated answer is a prefix of a healthy one, and the notify half deliberately says nothing when nothing changed. Without the summary line the two are indistinguishable, so a stream that lacks it — or whose count disagrees — is void, and voids the cycle. A record with a transition but no subject_key is malformed on the same footing: nothing downstream can acknowledge or de-duplicate a subject it cannot name.

"records": [] means “we classified, and nothing changed”. A workload with no transitions_from ships no transitions key at all, which means “we do not know”. Those are different facts and the notify half acts on only one of them, so the empty list is never elided.

A malformed stream fails the cycle exactly the way a failed collection does — before any model call, counted error, cadence continuing — and the log line names both the transitions_from key and what was wrong with the bytes.

notify: — speaking only when something changed

Section titled “notify: — speaking only when something changed”

transitions_from tells mast whether anything changed. notify is what it does with that answer:

monitor:
collect:
- tool: k8s_findings_diff
args: {transitions: "new,escalated,resolved"}
as: transitions
transitions_from: transitions
notify:
conversation: "#sre-oncall"
digest_after: 12h

The daemon supplies the other half — which ingress, and with what credential:

Terminal window
MAST_INJECT_TOKEN=… MAST_NOTIFY_TOKEN=… mast --workload=cluster-watch \
--notify-url=http://switchboard:8080 --listen=:7777 --session-db=…

That split is deliberate. Where to speak is a property of the workload; which switchboard, and as whom is a property of the deployment. A bundle that named its own ingress could not be promoted from staging to production without editing the workload. The token is refused at startup if it equals any of the daemon’s own inbound tokens (MAST_INJECT_TOKEN, MAST_ATTACH_TOKEN, MAST_A2A_TOKEN, MAST_AGUI_TOKEN): those point the other way, and sharing one means anything that can read the chat bridge’s configuration can drive this daemon. It is an env var and never a flag, so it stays out of ps and out of the container spec’s args.

A bundle with a notify: block and a daemon with no --notify-url is a startup refusal, not a warning. The workload’s entire output is the message it was going to send.

Not “wakes it and then declines to post” — the turn never runs. A fifteen-minute cadence that spends a model call on every quiet cycle costs more per month in nothing-happened than the incidents it exists to catch.

The skip is narrow: it applies only when the workload declared both transitions_from (so “nothing changed” is the classifier’s answer, not mast’s guess) and notify (so speaking is what the cycle is for). A workload that names no classification source speaks on every cycle, and the daemon says so at startup with speaks_every_cycle=true.

The first speaking cycle posts; the next ones append to that message, so an incident that takes six cycles to resolve reads as one growing story instead of six notifications an operator has to reassemble. The first quiet cycle closes the timeline — what happens after calm is a new incident, and it gets a new message.

Switchboard can answer an append two ways that are not errors, and both are handled rather than surfaced:

  • 409, “send the full text” — a restart, another replica, or a message posted from elsewhere means it no longer remembers the body. mast holds what it last sent and re-sends the whole story as an edit.
  • 200 with a continuation ref — the message is full, so the platform posted a threaded continuation. Every later cycle targets that one.

If neither works (the platform cannot edit, or the message is gone), the whole story is posted fresh, so the thread that survives is the readable one.

There is no queue, no retry and no spool. A send that failed is an errored fire, counted mast_monitor_notifications_total{outcome="error"}, and the next cycle reports what is new then.

Holding the message and re-sending it next cycle is the tempting fix and it is wrong: the classifier advanced its own state when it answered, so the replay would describe a world that has already moved on. Advancing state before speaking is the ordering that makes this safe.

If a cycle cannot complete — collection failed, the classification was truncated, the turn errored — mast posts a notice of its own into the same conversation, and another when the cycle next succeeds. Both are edge-triggered: once on the way down and once on the way back, never on every failing cycle, because a channel that repeats itself every fifteen minutes is a channel an operator mutes, and the mute costs them the incident report too. A health notice that cannot be delivered is logged and never fails the fire.

With digest_after, a workload that has said nothing for that long speaks on its next cycle whether or not it has news, and the deadman resets. The clock starts at daemon startup, so a daemon booting into a quiet world does not immediately announce the quiet. Those cycles are counted separately on mast_monitor_digest_wakes_total, because “did anything change” and “did the deadman have to fire” are different operator questions.

Every cycle’s outcome is on mast_monitor_notifications_total{workload,outcome} — posted, appended, replaced, rolled, quiet, health, error. A healthy monitor is mostly quiet.

Everything above runs outward. ack is the one leg that runs the other way: an operator reads a finding in the chat, says “I have seen this one”, and the monitoring stops reporting it.

monitor:
ack:
tool: k8s_findings_ack
args: {window: 4h}

That arms POST /monitor-ack on the daemon. A workload with no ack: block answers 404 there — nowhere to forward one.

Terminal window
curl -s -X POST http://localhost:7777/monitor-ack \
-H 'Authorization: Bearer '"$MAST_INJECT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"subject":"ns/checkout/oom-restarts","reason":"known, fix rolling out"}'
{
"workload": "cluster-watch",
"subject": "ns/checkout/oom-restarts",
"ack_by": "alice@example.com",
"previously_acked_by": "bob@example.com",
"previously_acked_at": "2026-08-21T07:02:11Z"
}

The subject is the producer’s subject key, verbatim from the classification mast reported — mast does not parse it and has no vocabulary for what a subject is.

The suppression lives with the producer of the transitions. It is the only place the next cycle’s classification can read it from, so mast forwarding and then keeping its own copy of “how long this is muted” would be a second, wrong answer to a question already answered. monitor.ack.args is where the deployment’s policy goes — which cluster, how long — and there is no per-request window.

What the producer cannot do is say who asked. Its ack surface takes an identity string from whoever calls it and has no way to check it. mast can, because the ack came through an authenticated ingress, so the split is:

Store of record for
The producerthe suppression — whether a subject is muted, and until when
mastthe attribution — who acked, when, from what credential, with what note

mast writes its record before forwarding. A forward that then fails leaves an attributed ack the suppression never reached, which is visibly different from nobody having acked at all; the operator is told, and acking again is the recovery.

ack_by comes from the credential, never the body

Section titled “ack_by comes from the credential, never the body”

The identity mast forwards and records is the one that authenticated the request. A body carrying ack_by is refused with a 400 naming the field — not ignored, because silently dropping a field a client believed in produces an audit line naming the wrong person with no sign anything went wrong.

A relay acking on a human’s behalf names them the supported way, with the X-Asserted-Caller header, which works only for a credential the users file provisioned to assert. Both are kept: the human is the acker, the relay is recorded alongside. This is the rule /resume settled for approvals, and it matters at least as much here — see Who a resume names.

They share an operator, a chat window and a verb, and nothing else. An approval mints a grant that licenses a write to the world and is consumed on use. An ack asserts no diagnosis, authorizes no change, and carries no verdict, no grant, no freshness window and no change-set signature. It does not go through the write gate and does not appear in the decision export — otherwise “who approved this change” would quietly start meaning “who muted an alert”.

The count is on mast_monitor_acks_total{workload,outcome}: forwarded or error, and nothing between them.

The exception is narrow because it is enforced, not because it is documented. A tool mast runs on its own behalf — everything named in monitor.collect, plus the one named in monitor.ack — must be reachable by nothing else, and the daemon refuses to start otherwise, before it wires MCP, so an operator without credentials reads the roster problem rather than a 403 standing in for it. Three ways a roster reaches a tool, all three refused:

  1. a specialist names it outright, on an MCP server or among its built-ins;
  2. a specialist allows an MCP server with no tools: list, which grants it every tool on that server (refused whether or not a collect tool is on that server today — mast cannot tell without connecting to it);
  3. a specialist declares no tools.mcp key at all, which inherits the whole catalog. Write mcp: [] if it needs no tools.

SingleTurn specialists are exempt: they are built with no toolsets at all, so they reach nothing. That is what makes a bounded monitoring roster the clearest form of the shape — its model holds no tools whatsoever and still gets the transitions.

The fence matters most for the ack tool. A collect tool a model could also reach would let it gather facts ungated; an ack tool it could reach would let it suppress its own alerts, and the producer’s triage-status write is typically not permission-gated on its side, so the daemon’s ingress authentication is the only thing in front of it. “There is no ack tool the model can call” is a property of the build — an agent that cannot see a tool cannot be talked into calling it.

The cycle fails, before any model call. Not “collect what you can and wake the model with the rest”: a cycle whose diff failed and whose scan succeeded would hand the model a snapshot with no transitions attached, and the honest reading of “no transitions” is “nothing changed”. A monitor that reports calm because its collection broke is worse than one that reports nothing, because only the second is visibly broken. The fire is counted error on mast_scheduled_fires_total, the reason is logged against the tick, and the cadence continues to the next one.

builtin_tools: — the provider’s own server-side tools

Section titled “builtin_tools: — the provider’s own server-side tools”

Both providers ship tools that do not run where mast’s tools run. Gemini’s google_search, url_context and code_execution, and Anthropic’s web_search, execute inside the vendor’s infrastructure; their results arrive folded into the model’s response.

That last clause is the whole problem. A server-side built-in never becomes a tool call, so:

  • the permissions gate has no name to allow or deny,
  • the write gate has no call to park for an operator,
  • the effect outbox has nothing to record,
  • and the transcript shows a model that simply knew something.

A specialist declared capability: read_only — a declaration mast verifies at startup and the write gate measures at runtime — could still read the public internet, and nothing downstream would say so. builtin_tools: is the only gate there is.

builtin_tools:
web_search: true # opt in, explicitly
url_context: false # explicit off; same as omitting it

Omitting the block entirely, or omitting a key inside it, leaves that tool off — on every provider. mast does not inherit the vendor’s default. Gemini’s own baseline is search-and-URL-context on and Anthropic’s is search off, so inheriting them would mean one mast image changing an unattended agent’s reach with a --provider flag, and “the same bundle runs on Gemini or Claude” is the point of the bundle. It also means the paths with no bundle to read — mast run, a library embed that sets only a model name — are safe because there is nothing to forget.

Writing false explicitly is worth doing anyway: it records that somebody decided, rather than that nobody wrote a key.

Bundle keyGeminiAnthropic
web_searchgoogle_searchweb_search
url_contexturl_context—
code_executioncode_execution—

A key with no equivalent lands nowhere. That is fail-safe by construction — a tool a provider cannot be sent is a tool it cannot leave on — but it is also silent, so read the startup line rather than assume:

INFO model constructed name=gemini-3.7-flash builtin_tools=web_search,url_context
INFO model constructed name=claude-sonnet-4-6 builtin_tools=web_search

The line reports what the constructed model will send, not what the bundle said. Unknown YAML keys are discarded without complaint, so builtin_tols: {web_search: true} parses fine and turns nothing on; a line derived from the same discarded struct would have agreed with the typo. builtin_tools=none means the provider has these tools and all of them are off. No line at all means the backend has no such concept — the offline fakes, scripted replay.

The gate is per bundle, not per specialist

Section titled “The gate is per bundle, not per specialist”

There is no per-specialist builtin_tools:. Under a default-off baseline there is nothing for a specialist to reclaim: only the bundle can turn a tool on, and a specialist’s model: override resolves through the same gate the root does — a workload that turned web search off cannot have it handed back by an analyst that names a different tier. If a roster ever needs one analyst grounded and the rest not, that is a change to make then; until it exists, the missing axis fails closed.

Unless a bundle turns it off, mast places a cache breakpoint on a claude-* model’s system prompt (which caches the tool schemas with it, since they render first) and rolling breakpoints over the end of the conversation. An incident re-sends its whole growing transcript on every model call; with the breakpoints in place, Anthropic re-reads it at the cache rate, a tenth of fresh input, instead of billing it in full again.

prompt_cache:
enabled: true # the default; false turns it off
ttl: 5m # the default; or 1h

On by default, and that is a breaking change. Before this block existed mast sent no cache breakpoints, so a workload that upgrades starts caching without touching its bundle: Claude bills the cache writes at 1.25x input and the re-reads at 0.1x. On the judged corpus the run came out 30% cheaper; a workload of single-call turns could come out slightly dearer, and enabled: false restores the old behaviour. The default matches core-agent’s, and it changed before v1.0 on purpose, while the compatibility policy still allows a default to move without a deprecation window.

Measured on the judged corpus (claude-sonnet-5 on Vertex’s global endpoint, ten incidents, --prompt-cache=5m against off), caching left every score unchanged and cut the run’s cost by 30%, and its input cost by 45%. Those incidents average about three model calls; a longer investigation re-reads more and saves more. On the global endpoint consecutive calls can also miss the cache, since they may be served from different regions; a regional endpoint such as us-east5 reads it reliably.

The TTL is a real trade-off. Writing to the cache costs more than fresh input: 1.25x for a 5-minute breakpoint, 2x for a 1-hour one. A tight loop refreshes the 5-minute window on every call, so 5m is right for nearly every workload, and the extra 0.75x of 1h would be pure loss there. 1h pays when turns are routinely more than five minutes apart: a turn parked on an operator’s approval, or a scheduler-driven daemon. Both TTLs are priced at their own rate, because Anthropic reports which TTL each write used.

The block is workload-wide: the root and every specialist on a claude-* model cache the same way, and so does a provider profile on the Anthropic dialect. It changes nothing on Gemini, whose caching is implicit (or the Vertex context cache). With no bundle to read — mast run, a library embed that sets only a model name — the default applies: on, 5 minutes. The eval harness follows the same default and takes --prompt-cache=off|5m|1h to override it, so the measurement above is reproducible from the command line.

core-agent has the same setting, as --prompt-cache-ttl / --no-prompt-cache and model.anthropic.prompt_cache in its config, on by default there too. Both products get it from the same core-models adapter.

run_queue: — bounding concurrent runs on one thread

Section titled “run_queue: — bounding concurrent runs on one thread”

One AG-UI thread runs one turn at a time. That is not an AG-UI decision: a mast session is a single-writer store, so every turn-driving surface serializes on the same per-session lock. What run_queue: decides is what happens to the second run.

agui:
expose: true
run_queue:
depth: 3 # runs that may WAIT. Omit for this default.

depth counts runs that may wait, not runs that may exist, so the admitted total is depth + 1 — one executing plus depth queued. That is why 0 is a useful setting rather than an absurd one: it means no concurrency on a thread, one run at a time and the rest refused immediately. Omitting the key gives you 3.

The run that arrives at a full thread is refused with 409 Conflict and a Retry-After, decided before the SSE stream opens, so a client gets an HTTP status it can branch on rather than a stream that opens and immediately carries an error frame. Retry-After is a fixed backoff floor, not a prediction: mast does not know how long the turn ahead of you will take.

Three things worth knowing before you tune it:

  • 409, not 429. A 429 from this endpoint means the rate limiter refused your arrival rate, and the remedy is to slow down everywhere. A 409 means this one conversation is busy, and the remedy is to retry it or start a different thread. Collapsing them would leave a client unable to tell which it is.
  • The bound is per thread, so a busy thread never refuses a run addressed to another one, and under session_model: per_run — a fresh session per run — it effectively never fires at all.
  • There is no way to say “unbounded”. Unbounded is what this key exists to end, so a negative depth is refused at daemon start rather than read as -1 means no limit.

Refusals are counted as mast_agui_runs_total{outcome="queue_full"}, kept separate from the rejected the credential-shaped refusals share: a climbing queue_full is answered with capacity or with this key, not with a caller’s token.

FieldMeaning
budget.max_turnsCap on model calls per session. One “turn” = one model call — a Task specialist looping through five model calls before finish_task has spent five turns, not one. Absent/0 = unlimited.
budget.max_model_calls_per_turnCap on model calls in one turn, where max_turns caps the session. The backstop for a turn that runs away in a shape the watchdog does not recognize; it needs no price, so it holds for unpriced models. The call over the cap is not made and the turn ends as loop_stop, with nothing latched. Absent/0 = mast’s default of 100; negative = unlimited. Applies under every watchdog posture. See a loop inside one turn.
budget.max_wallclock_secondsBounds each whole turn with a context timeout.
budget.max_cost_usdSession-cumulative cost ceiling, derived by the budget meter from streamed usage metadata (flat per-1K-token spike pricing in v0.1).
budget.final_reportGrants a specialist stopped by a ceiling one model call past it, with every tool but its report tool withdrawn, to file what it already established. Default false. Once per specialist per session, and never to one that has spent nothing. See letting a stopped specialist file what it found.

Crossing a ceiling cancels the run context mid-turn, aborts in-flight model/tool work, and increments mast_budget_trips_total. Budgets compose: workload-level and per-specialist budgets both apply, tightest cap wins.

A specialist file may declare its own budget in frontmatter, alongside the model override and report contract above:

---
description: Diagnoses OOMKilled container terminations.
budget:
max_turns: 6
max_wallclock_seconds: 60
max_cost_usd: 0.25
---

max_turns and max_cost_usd are ceilings on that specialist’s spend, checked on every model call it authors; max_wallclock_seconds bounds each activation of its node under graph dispatch. Composition with the workload’s ceilings is by construction rather than arithmetic: each call is measured against the specialist’s ceiling and the workload’s, and whichever is reached first stops what it holds — the specialist, or the whole run. When one call crosses both, the error names the specialist — the more specific fact, and the one an operator acts on. A specialist that declares a model: override or a tier: is priced at the rate of the model it actually runs on — a tier is priced off what it resolved to — so a cheap analyst’s tokens are not billed at the synthesizer’s.

One limit is worth knowing. A ceiling is checked both before a call and after it, but the pre-call check refuses only what it can prove — so max_turns is exact, while a call that starts with dollars or tokens to spare always finishes and is billed for what it turns out to cost. The cap bounds total spend within one call’s overshoot; it does not pre-authorize a call.

A specialist’s own ceiling stops that specialist and not the session: the coordinator is handed the refusal and routes around it, so a workload with budget elsewhere finishes with a path missing rather than failing. The loss is reported on mast_budget_trips_total, in the daemon log, per specialist under cost_ceiling.scopes[], and in mast.Result.Exhausted (budgets).

Scalar budget values can be overridden process-wide (applies to every bundle loaded in the invocation, overrides file values unconditionally; set-but-unparseable is a fatal load error):

budget.max_cost_usd → MAST_BUDGET_MAX_COST_USD
budget.max_wallclock_seconds → MAST_BUDGET_MAX_WALLCLOCK_SECONDS

mast reads the bundle once, at startup, and never reloads it. Editing workload.yaml, a specialist template or mcp.json while the daemon is running changes nothing until the daemon restarts.

That is easy to trip over in Kubernetes, because the deployment mounts the bundle from a ConfigMap and the kubelet does rewrite the mounted files under a running pod. The base kustomization also sets disableNameSuffixHash: true, so kubectl apply does not roll the pod either. Both are deliberate — see below — and together they mean an applied edit can look like it took effect when it has not.

So mast says which configuration it is running. At startup:

level=INFO msg="workload config identity" root=/workspace/workload
bundle=/workspace/workload/workload.yaml digest=sha256:1f0c2a93b7d4e615
files=17 bytes=41328 newest_mtime=2026-09-06T10:14:22Z

The digest covers every file the loaders actually read — the bundle, each specialist template, each output_schema: they resolve, and the MCP catalog — keyed by path relative to the root, so the digest you compute from a checkout is the digest the pod prints. It does not include modification times, because a ConfigMap remount rewrites those whether or not a byte changed.

Once a minute the daemon re-hashes the same files. When they stop matching what it loaded, it says so once:

level=WARN msg="WORKLOAD CONFIG ON DISK NO LONGER MATCHES THE RUNNING CONFIG
— the edit has not taken effect" running_digest=sha256:1f0c2a93b7d4e615
on_disk_digest=sha256:9b31c07ae5f2d488
changed=specialists/CrashLoopBackOff.specialist.md
remedy="mast does not reload configuration; restart the daemon
(kubectl rollout restart) to pick this up"

Once per edit, not once per minute; reverting the file logs that the two agree again.

Why not roll the pod on apply, and why not hot reload. A hashed ConfigMap name would restart the daemon on every kubectl apply, which is a heavier action here than it looks: an unattended daemon holds in-flight turns that are spending money, parked approvals waiting on a human, and an armed cadence. Making the restart something an operator asks for is the safer default, and kubectl rollout restart statefulset/mast is the whole of it. Hot reload is a larger question than a file watcher — what a mid-flight turn, a parked approval or a running monitoring cycle should do when the bundle changes underneath them — and it is not answered by noticing that a file moved.