Deciding When a Subagent Instruction Change Needs a Human Gate

Score each change on three questions. Each answer lands in low, medium or high.

Reversibility: can the subagent's tools undo the damage if the new instruction is wrong? This is the least-privilege question applied to prompts (ThreatLocker). A research subagent that can read files and search the web has highly reversible tools: a bad instruction produces a bad summary that a human discards. A subagent holding a write token to a production database, or the ability to close tickets or send customer email, has irreversible tools. Microsoft's guidance for connected agents makes the same point: if a child agent can delete records the parent cannot, the call must be treated as a powerful action subject to checks and consent (Microsoft Learn).

One nuance most teams miss: reversibility is a property of the tool set, not of the instruction text. An instruction change can make an irreversible tool more likely to fire without changing permissions at all. "Always close the ticket once the root cause is identified" is a one-line prompt edit that turns a read-only reviewer into an actor.

Reach: how many tasks or workflows does the instruction serve? Instruction files live at two scopes in most coding agents: project level and user level, so a single edit can propagate to every project the author touches (Engineer Prompt). Reach is countable. Open the agent definition and count the call sites: tasks in the workflow graph that route to this subagent, plus any other agents that delegate to it. One task is low. A handful within one team's workflow is medium. A shared agent used across teams or products is high. The orchestrator-worker pattern is what creates this exposure: one orchestrator delegates to specialist workers, and a worker with many upstream callers is a shared dependency (Arize).

Output contract impact: does the change alter the response shape? If downstream code parses the subagent's return, the prompt is part of an API contract. Structured output features guarantee conformance to a supplied schema, which is exactly why schema-bound outputs are safe to change only deliberately (OpenAI). Agent frameworks expose the same idea through typed result objects validated against a schema (Strands Agents). A wording change that leaves fields, types and required keys identical is low. Adding a new optional field, or changing how a free-text section is phrased inside a fixed envelope, is medium. Renaming a field, dropping one, changing an enum or altering when the agent refuses is high.

Read the three scores. Take the highest one.

• All three low: auto-merge once the evaluation suite passes. No human reads the diff.
• Any one medium or high: one reviewer approves before merge.
• Reversibility high, or output contract high, or reach high: the owning team signs off. One reviewer is not enough when the blast radius crosses a team boundary or the change can destroy state.

The rule is deliberately pessimistic: a single high score dominates two lows. That is the correct default because the axes are not independent in practice. A high-reach instruction change is more likely to reach a call path that uses an irreversible tool, and a contract change on a high-reach agent breaks more parsers.

Two supporting mechanisms make the rule enforceable.

First, version the instruction file and the tool allowlist in the same repository, so any diff shows whether tools changed alongside prose. Prompt versioning treats each save as an immutable version with a diff and an environment label, which is what lets a reviewer see the change in isolation rather than against a moving baseline (Braintrust).

Second, run an evaluation gate before routing. A change that fails its tests never reaches the reviewer, which means reviewer time goes to changes that already work and the question is only whether they should ship.

# change-risk.yaml, evaluated in CI on every PR touching agents/*/INSTRUCTIONS.md
axes:
  reversibility: low      # tool allowlist hash unchanged; tools are read_file, search, list_dir
  reach: medium           # 4 tasks route to this subagent in the triage workflow
  output_contract: low    # schema.json unchanged; no parsed field added or removed
route: single_reviewer    # highest score is medium
required_checks:
  - eval_suite             # must pass before routing
  - schema_diff_empty      # fails if schema.json changes without a contract label
owner: triage-platform

A reviewer's job then collapses to one question: is the medium score honest? That takes minutes, not an afternoon.

Take a support operations team running an orchestrator with three specialist subagents: a researcher that reads the knowledge base and past tickets, a drafter that writes customer replies, and a reconciler that updates the billing system. Task volume is 400 workflows a day.

Change A: the researcher's instruction gains a rule about citing source documents. Tools are read-only, so reversibility is low. Reach is one workflow path, so low. The return is a free-text summary that no parser reads, so low. All three low: auto-merge on a passing eval. If it is wrong, the worst outcome is a slightly worse summary that a human reviewer catches downstream.

Change B: the drafter's instruction gains a tone rule and a new optional field, escalation_reason. Tools can send email, but only after a human approves the draft, so reversibility is medium. Reach is one workflow, low. The output contract adds an optional field, medium. Highest score is medium: one reviewer. The reviewer checks that the optional field is genuinely optional in the parser and that the tone rule does not push refusal rates up in the eval set.

Change C: the reconciler's instruction changes refund handling to auto-apply credits under a threshold. Tools write to the billing system, so reversibility is high. Reach is one workflow but the reconciler is also called by a separate finance tool, so medium to high. The instruction also changes a status enum from pending to applied, which is high on contract. Highest score is high on two axes: the owning team, finance operations plus the platform owner, signs off. The reviewer role cannot approve this alone, and that is the right answer, because a wrong instruction here moves money and breaks a downstream dashboard that counts pending rows.

A useful sanity check: rank the three by the cost of being wrong for a day. A is a bad summary. B is a reply that reads oddly or escalates too often. C is refunds issued in error plus a broken report. The gate hierarchy should match that ordering, and it does.

A routing rule only survives if the score is recorded somewhere a future reader can find. Three practices carry most of the weight.

Label the contract, not the prose. Put the output schema in its own file next to the instruction file and have CI fail any pull request that touches the schema without a contract-change label. Structured output tooling already validates responses against a schema at runtime, so the schema is the real interface; the prompt is one of several things that influence whether the model fills it (OpenAI). Treating the schema file as the contract boundary turns a judgment call into a diff check.

Record reach as a number, not a feeling. Maintain a small map from subagent to call sites and regenerate it from the orchestration config. In a fan-out pattern the number grows fast: with N agents there are N(N-1)/2 possible concurrent interactions, which is why shared workers accumulate callers quietly (Beam AI). If the map is generated, the reach score in the pull request is a fact rather than an estimate.

Log the gate decision with the version. Prompt versioning conventions already require immutable versions and environment separation, so the approval record attaches to a version identifier rather than to a commit message (Braintrust). When someone asks in three months why a refund rule changed, the answer is a version, an approver and a score.

For teams running many subagents, the rollout itself is a change-management exercise, and the same discipline applies: define the scope and impact, name who is responsible for build and test, and state what happens if the change is rejected (SolarWinds). The three-axis score is simply that discipline compressed into three questions a pull request can answer.

Scoring the prompt text instead of the agent tuple. A change that looks cosmetic in prose can alter tool selection. Giving a model more tools than it needs degrades tool selection, and narrow tool sets per subagent are what make selection reliable in the first place (Engineer Prompt). If the tool allowlist changed, score reversibility from the new allowlist, not from the words in the instruction.

Treating reviews as the quality gate. Reviewers catch intent, not regressions. Systematic evaluation is what connects a prompt change to measurable outcomes and exposes degradation before users see it (Braintrust). Route after the eval, never instead of it.

Letting one shared worker escape the rule. Shared agents attract callers because reuse is the reason they exist, and each new caller raises reach without anyone editing the instruction. Recompute reach when the orchestration graph changes, not only when the instruction does, a concern the orchestrator-worker pattern makes explicit (Arize).

Forgetting that subagents do not inherit context. A subagent starts from a fresh context window and receives only what the delegation prompt contains, so an instruction that depends on a decision made earlier in the parent conversation will silently fail (Hidekazu Konishi's subagent guide). Treat "add a reference to prior context" as a high-risk change on reach, because it affects every delegation path that does not supply that context.

Ignoring where control lives. In a centralized single-agent design, instruction changes have one owner. In a coordinated multi-agent design, control is distributed and each cooperating process may have its own tools, memory and decision-making, which is why the owning team, not a general reviewer, must sign off on high-risk changes (JetBrains).

If you are building the orchestration layer itself, having one API key across the models your subagents run on removes a whole class of routing questions, and Quanta Inference (https://quantaintelligence.ai/inference) is built for that: text, image and embedding models behind an OpenAI-compatible endpoint.