Context Management and Reliability

Mechanism reference: 1. Window sizes per model family and the 1M default

The context window is the total token budget from which the system prompt, every message, every tool result, every document, tool definitions, and the generated output all draw. The size of that budget is fixed per model; there is no longer a "standard 200K with an opt-in extended 1M" split, each model has the window it ships with.

The 1M-token window models are Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, and Sonnet 4.6. The Fable 5, Mythos 5, and Mythos Preview models also carry a 1M window. Every other model, including Sonnet 4.5, has a 200K window. For each 1M-window model, 1M is the default: no beta header is required to use it and it is billed at standard pricing. A single request to a 1M-window model can generate up to 128,000 output tokens. A request can include up to 600 images or PDF pages, and the limit is 100 on a 200K-window model.

The lesson library records the same split from the product side: Opus 4.8 and Sonnet 4.6 (and Opus 4.7, Opus 4.6, Sonnet 5, Opus 5, Fable 5) at 1M, Haiku 4.5 at 200K. The key architectural consequence is that 1M is not "better" by default. A well-structured 150K prompt on a 1M model outperforms a sloppy 800K prompt on the same model, because the quality ceiling still applies inside the larger window. The window is a shared tank; how you fill it matters more than its size.

Mechanism reference: 2. Everything in the request counts toward the window

This is the single most important accounting rule and the source of most real context bugs. Everything in the request counts toward the window: the system prompt, every message including tool results, images, and documents, tool definitions, and the output including extended thinking. None of these is free or metered separately from the window budget.

The usage field reports the split. With caching enabled, the input count is split across three numbers that all count toward the window: input_tokens, cache_read_input_tokens, and cache_creation_input_tokens. All three are real tokens occupying the window; caching changes the price you pay, not the space the content takes. The lesson library states this in its own words: input tokens, output tokens, cache creation, and cache reads all appear in response.usage, and the cached tokens still occupy the context.

A practical boundary: output tokens count toward the window. If you send 180K input on a 200K model and set max_tokens to 32K, the request fails because 180K plus 32K exceeds 200K. Always reserve headroom for the reply. The lesson library's context-window diagram labels the free region as "Free: response headroom" for exactly this reason.

Mechanism reference: 3. Context rot: the documented name for quality loss at scale

The documented name for quality loss as token count grows is context rot. Accuracy and recall degrade as the count grows, so curating what is in context matters as much as how much room is left. The phenomenon is described as a monotonic degradation with token count, with no published threshold.

The lesson library names a specific effective ceiling of roughly 147,000 to 152,000 tokens, but documentation does not publish that number. Treat the specific figure as a community estimate and never as an official measurement. The documented phenomenon to cite on the exam is context rot; the high-140000s number is an estimate that the lesson library uses as a planning heuristic, not an Anthropic-measured limit.

This interacts with the lost-in-the-middle effect. Research shows a U-shaped performance curve: content at the very start and very end of the context is attended to most reliably, while content in the middle (roughly the 25 percent to 75 percent band) is more likely to be underweighted or missed. The lesson library documents this with a worked 180K-legal-contract example where a liability cap on page 247 is missed because it sits in the middle. The fix is structural: put critical instructions at the start (in the system prompt) and the current task at the end (in the latest user turn), and relegate background material to the middle.

Mechanism reference: 4. Server-side compaction: the documented primary strategy

Server-side compaction is the documented primary strategy for long-running conversations, not client-side summarisation. The strategy type is compact_20260112, the beta header is compact-2026-01-12, and it is passed inside context_management.edits. The default trigger is {"type": "input_tokens", "value": 150000}, and value must be at least 50,000. Optional fields are pause_after_compaction (default false) and instructions, which completely replaces the default summarisation prompt.

When the API detects the threshold, it generates a summary, emits a compaction block, and continues the response. On later requests it drops all blocks prior to the compaction block. This makes the compaction block itself the truncation boundary, which is exactly what the application must anchor on. Supported models are Fable 5, Mythos 5, Mythos Preview, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, and Sonnet 4.6.

The default compaction summary prompt is documented and structured as: Task Overview, Current State, Important Discoveries, Next Steps, Context to Preserve, wrapped in <summary></summary> tags. This is the documented shape of a handoff summary and is directly reusable as a scratchpad or phase-summary schema.

There is a documented limitation with server-side tools: after a web search the SDK may add cache_read_input_tokens accumulated across the tool's internal calls to the total, so the input count can read several hundred thousand tokens when the real context is far smaller, causing premature compaction. The workaround is the token counting endpoint, or avoiding client-side compaction with heavy server-side tool use.

Client-side SDK compaction exists only in the TypeScript and Ruby SDKs via tool_runner with compaction_control, default context_token_threshold of 100,000. The Python, C#, Go, Java, and PHP tool runners do not support it, and the docs point them to server-side compaction.

Mechanism reference: 5. Context editing: the fine-grained alternative

Context editing is the fine-grained alternative to compaction, under beta header context-management-2025-06-27. It has two strategies: clear_tool_uses_20250919 and clear_thinking_20251015.

Tool result clearing takes the fields trigger, keep, clear_at_least, exclude_tools, and clear_tool_inputs. Cleared results are replaced with placeholder text. Clearing happens server-side before the prompt reaches the model, so the client keeps its own full unmodified history and does not sync. This means the application can retain a complete, verbatim log for later audit or replay while the model sees a trimmed view.

Cache interaction is strategy-specific. Tool result clearing invalidates the cached prefix at the clearing point, which is why clear_at_least exists: you clear enough to make the cache write worth it. Thinking block clearing preserves the cache while blocks are kept, and invalidates at the clearing point when they are not kept.

Thinking block retention is model-dependent. Opus 4.5 and later, Sonnet 4.6 and later, Fable 5, Mythos 5, and Mythos Preview keep prior thinking blocks by default and they count as input tokens. Earlier Opus and Sonnet models and all Haiku models strip them automatically when passed back. Set keep explicitly when code spans model tiers.

Mechanism reference: 6. Prompt caching mechanics

Prompt caching lets you mark stable content with a cache_control breakpoint of {"type": "ephemeral"}. Everything up to and including the breakpoint is cached; content after the last breakpoint is processed fresh every request.

Prefix matching is order-dependent: the cache is checked in the order tools, then system, then messages. Layout decides whether you get a hit. Put the content that stays constant first: tool definitions, system instructions, long reference documents. Put the breakpoint at the end of that static block. Put the volatile content, the user's latest message and anything that changes per request, after the breakpoint.

You may set up to four breakpoints per request, each representing a layer of different reuse frequency from most stable to least stable. The minimum cacheable length is model-specific: 1,024 tokens for Sonnet 4.6 and Opus 4.8, and 4,096 tokens for Haiku 4.5. Below that minimum the API silently bypasses caching regardless of any cache_control you set.

The write multiplier is roughly 1.25x the standard input rate for the default 5-minute TTL and roughly 2x for the 1-hour TTL. The read multiplier is roughly 0.1x (10 percent) of standard input rate for either TTL. The TTL refreshes on every cache hit, so a high-traffic application effectively caches indefinitely; a nightly batch that pauses for hours re-pays the write cost.

Cached tokens still occupy the window. Caching reduces cost, not size. A 30K cached system prompt consumes 30K of window on every request; you simply pay less for it.

Mechanism reference: 7. Token counting to size a request before sending

The token counting endpoint (POST /v1/messages/count_tokens, exposed in the SDK as client.messages.countTokens()) returns exact token counts before you make a request. Use it to validate prompt size, estimate cost, and prevent context window overflow. This is the documented way to size a request rather than guessing from word counts. The lesson library shows a cost-estimation function built on countTokens that also returns withinContext by comparing input plus estimated output against the model limit.

Mechanism reference: 8. The persistent facts block (application-owned protection)

The persistent facts block is the application-owned protection that survives any summarisation or compaction. It is a structured block of transactional facts, amounts, dates, order numbers, and statuses, included in every prompt and never summarised. It sits outside the summarised region. The lesson library calls this the immutable facts block and places it immediately after the system prompt, before any conversation history.

This block remains necessary even though server-side compaction exists, because compaction still summarises, and anything the application must keep verbatim has to live outside the summarised region. The reference material omits compaction entirely and treats the facts block as the only protection; documentation now makes compaction the recommended strategy, with a documented trigger threshold, a documented summary structure, and a compaction block that the API uses as the truncation boundary. State the documented mechanism first, then the application-side protection.

Mechanism reference: 9. Tool result trimming at the boundary

Tool results are a silent context budget killer. An order lookup may return 40 or more fields; the application needs 5. Those other fields consume tokens in every subsequent turn as history grows. Trim verbose tool outputs to only the relevant fields before they accumulate in context. This should happen in a PostToolUse hook or in the tool implementation itself, before the result enters the conversation history. Once verbose data is in context, it stays there for every subsequent turn.

Mechanism reference: 10. Upstream agent optimisation and the stateless API

In multi-agent systems, upstream agents often return verbose reasoning chains and raw content that downstream agents do not need. Require subagents to return structured data, key facts, citations, and relevance scores, instead of verbose content and reasoning chains. This saves tokens and lets downstream agents process findings without re-parsing prose.

The API is stateless. Each request must include the complete conversation history. Omit earlier messages and the model loses conversational coherence. There is no server-side session state, so every turn has to carry everything the model needs. This creates tension with context limits: you need the full history for coherence, but the history grows with every turn. The persistent facts block resolves this by separating critical facts from summarisable narrative.

Ownership map

Which layer owns which guarantee:

• The model owns attention behaviour: it reliably attends to the start and end of context and degrades in the middle. You cannot fix lost-in-the-middle with a prompt instruction; you fix it with layout.
• The API and SDK own server-side compaction and context editing. When you enable compact_20260112 or a context-editing strategy, the API detects the threshold, rewrites the conversation, emits the compaction block, and enforces the truncation boundary. The client's retained history is untouched.
• The API owns the prompt caching machinery: prefix matching, breakpoint accounting, TTL, and the usage split across input_tokens, cache_read_input_tokens, and cache_creation_input_tokens.
• Application code owns the persistent facts block, tool-result trimming, priority-based truncation, and the decision of what content earns a place in the window. These are not API features; they are application disciplines the model and API cannot perform for you.
• Tool implementations and PostToolUse hooks own tool-result trimming at the boundary.
• The lesson library notes that Claude Sonnet 4.6 and Haiku 4.5 add a model-side context awareness signal (a session-start budget marker and a running per-tool-call usage update), but DOC-URLS directs that this behaviour be marked not independently confirmed for the specific marker and warning phrasing and not used as a decision rule, because it is not documented on the checked pages.

Version and terminology currency

The terminology has shifted between the exam guide era and the current product. The older "200K standard, 1M extended with a beta header" framing is gone: 1M is now the default on the 1M-window models with standard pricing and no beta header.

The compaction strategy name compact_20260112 and beta header compact-2026-01-12 are dated markers; the date in the name is the version, not an expiry. The context-editing beta header context-management-2025-06-27 and the strategy names clear_tool_uses_20250919 and clear_thinking_20251015 follow the same dated convention. When you read older community write-ups that call compaction a Claude Code feature only, note that /compact in Claude Code is one surface; the API-level compact_20260112 strategy is the programmatic equivalent for applications not running inside Claude Code. Keep both and say which layer each belongs to.

The memory tool is {"type": "memory_20250818", "name": "memory"}, available on Claude 4 and later. It is client-side: the model requests view, create, update, and delete operations under /memories and the application executes them against storage it controls, returning a tool_result. The /memories prefix is mapped by the handler onto real storage, and the handler must reject paths outside /memories (path traversal protection). Its documented purpose is just-in-time context retrieval so the active window stays focused.

Official versus community divergence

The reference material and current documentation disagree in six places that a candidate must navigate. Documentation wins; the divergences are restated here so the writer and the candidate can answer correctly.

1. The reference material and the lesson library state a quality ceiling of roughly 147,000 to 152,000 tokens. No Anthropic page publishes that number. Documentation describes context rot as monotonic degradation with no published threshold. Treat the figure as a community estimate, name the documented phenomenon as context rot, and do not present the number as an official measurement.

1. The reference material treats client-side progressive summarisation as the default long-conversation strategy and the persistent facts block as the only protection. Documentation now makes server-side compaction the recommended strategy, with a documented trigger threshold, a documented summary structure, and a compaction block used as the truncation boundary. The facts block remains correct and necessary, because compaction still summarises and anything that must survive verbatim has to live outside the summarised region. State the documented mechanism first, then the application-side protection, and note that the reference omits compaction entirely.

1. The reference material presents provenance as an application-side discipline of five-field claim-source mappings preserved through synthesis by prompt instruction. Documentation provides two enforcement mechanisms the reference omits: the citations feature on document blocks and search result content blocks with required source and title. The exam-relevant judgement is unchanged, since attribution still has to survive multi-step synthesis in application code, but grounding must present the documented mechanisms as the preferred enforcement point and treat prompt-preserved mappings as what you do for content that does not arrive as documents or search results.

1. The reference material describes the scratchpad file for long exploration as a purely local convention. Documentation names the same pattern as just-in-time context retrieval and provides the memory tool as the supported surface, with the important detail that execution and storage are the application's responsibility and path containment is a security requirement.

1. The reference material describes the model receiving a token budget marker at session start and a running warning after each tool call. That behaviour is not documented on the checked pages. Mark it not independently confirmed and do not build a decision rule on it.

1. The reference material treats /compact in Claude Code as the only compaction lever. It is one surface; the API-level compact_20260112 strategy is the programmatic equivalent for applications not running inside Claude Code. Keep both and say which layer each belongs to.

Beyond the task statement

The reference page covers the persistent facts block, lost-in-the-middle, tool-result trimming, statelessness, upstream agent optimisation, and prompt caching. The lesson library covers adjacent material the reference omits. Each item below lists its slug and why it matters for this task.

• token-budgeting: introduces FIFO truncation, priority-based truncation (P0 through P4 tiers), and fixed versus dynamic versus priority allocation. It matters because the persistent facts block is the P1 tier in a priority scheme; understanding the tiers explains why the block must be tagged protected, not merely prepended.
• context-compression: covers extractive versus abstractive summarization, the immutable facts block, sliding window versus summarization versus selective retention, and the built-in primitives (memory tool, context editing, compaction). It matters because it is where the documented server-side primitives are reconciled with the hand-built patterns.
• token-management: covers token counting, the usage split, image and PDF token costs, output token ceilings (128K on 1M models, 64K on Haiku 4.5), and the fact that cached tokens still occupy the window. It matters because the exam tests budget tracking through usage.
• context-engineering-stack: frames the whole window as a stack of layers (system, tools, retrieved context, history, scratchpad) and shows how each layer is cached, trimmed, or protected. It matters because it gives the facts block a precise home in the stack.
• context-sources-taxonomy: a six-level taxonomy of where context originates (user input, retrieval, tool results, subagent output, memory, system). It matters because tool-result trimming and upstream agent optimisation are both source-tier decisions.
• prompt-caching: the full caching reference, including the 1,024 versus 4,096 token minimums, the four-breakpoint limit, and the write/read multipliers. It matters because the reference page's cache example is correct but under-specified.

Worked production examples

The six examples below are complete, language-tagged, and evolve as one pipeline. Each names its language, states what it proves, its failure boundary, and its observable output. They cover the six required mechanisms: a persistent facts block with the prompt-construction function that guarantees it, an array-form system field with the correctly placed cache breakpoint shown next to the wrong placement and the usage fields that distinguish them, a server-side compaction request with an explicit trigger threshold, a tool-result clearing configuration with trigger, keep, clear_at_least, and exclude_tools, a token-counting call used to size a request before sending it, and a tool-result trimmer at the tool boundary.

Example 1: persistent facts block prepended outside the summarised region, with the prompt-construction function that guarantees it.

type CaseFacts = {
  customerId: string;
  issues: Array<{
    orderId: string;
    orderDate: string;
    refundAmount: string;
    status: string;
    itemDescription: string;
  }>;
};

const CASE_FACTS_HEADER = "<immutable_facts>";

function buildPrompt(
  systemPrompt: string,
  facts: CaseFacts,
  summarisedHistory: string[],
  currentTurn: string
): string {
  const factsBlock =
    `${CASE_FACTS_HEADER}\n` +
    `customerId: ${facts.customerId}\n` +
    facts.issues
      .map(
        (i) =>
          `issue: order ${i.orderId} (${i.orderDate}) refund ${i.refundAmount} status ${i.status} - ${i.itemDescription}`
      )
      .join("\n") +
    "\n</immutable_facts>";

  // Order is deliberate: facts are prepended outside the summarised region,
  // then summarised history, then the live turn. Compaction and summarisation
  // act on the middle region only; the facts block is never in scope.
  return [systemPrompt, factsBlock, ...summarisedHistory, currentTurn].join("\n\n");
}

const facts: CaseFacts = {
  customerId: "C-4421",
  issues: [
    {
      orderId: "#8891",
      orderDate: "2024-03-03",
      refundAmount: "$247.83",
      status: "pending_refund",
      itemDescription: "Wireless headphones - defective",
    },
  ],
};

const prompt = buildPrompt(SYSTEM_PROMPT, facts, olderTurns, "What is my refund status?");

What this proves: the facts block is constructed by a function that always prepends it between the system prompt and the summarised history, so it sits outside the region that compaction or progressive summarisation touches. The block carries the exact amount, order id, and date that abstractive summarisation would otherwise destroy. Failure boundary: if any code path assembles the prompt without calling buildPrompt, the guarantee breaks; the function must be the single source of prompt assembly. Observable output: after a compaction that replaces olderTurns with a summary, the rendered prompt still begins with <immutable_facts> containing $247.83, #8891, and 2024-03-03 verbatim.

Example 2: array-form system field with the correctly placed cache breakpoint next to the wrong placement, plus the usage fields that distinguish them.

{
  "model": "claude-sonnet-5",
  "max_tokens": 4096,
  "system": [
    {
      "type": "text",
      "text": "You are a support agent. Rules: refund policy X, escalation path Y.",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Large product catalogue reference document shared every turn.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the status of order #8891?" }
  ]
}

Wrong placement: putting cache_control on the volatile user message, or interleaving dynamic text before the static block, breaks the stable prefix so every request pays full price. Correct placement is at the end of the static system array, as shown. The usage field distinguishes the outcomes:

{
  "usage": {
    "input_tokens": 312,
    "output_tokens": 84,
    "cache_creation_input_tokens": 18420,
    "cache_read_input_tokens": 0
  }
}

On a cache miss (first request, or after the prefix changed) cache_creation_input_tokens is high and cache_read_input_tokens is zero, and you paid the 1.25x write multiplier on the 18,420 cached tokens. On subsequent hits:

{
  "usage": {
    "input_tokens": 312,
    "output_tokens": 84,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 18420
  }
}

Now cache_read_input_tokens is high and you paid the 0.1x read multiplier. All three input numbers count toward the window even though only the read was cheap. Failure boundary: a one-character change in the static text invalidates the prefix and reverts to a write on the next call. Observable output: cache_read_input_tokens climbs on every repeated prefix; if it stays zero, the breakpoint is misplaced.

Example 3: server-side compaction request with an explicit trigger threshold.

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "system": [{ "type": "text", "text": "You are a long-running research agent." }],
  "messages": [{ "role": "user", "content": "Begin the multi-hour investigation." }],
  "context_management": {
    "edits": [
      {
        "type": "compact_20260112",
        "trigger": { "type": "input_tokens", "value": 150000 },
        "pause_after_compaction": false,
        "instructions": "Summarise preserving exact figures, dates, and order ids. Keep the <immutable_facts> block verbatim."
      }
    ]
  },
  "anthropic-beta": "compact-2026-01-12"
}

What this proves: compaction is requested declaratively with an explicit trigger of 150,000 input tokens (above the 50,000 floor), an optional pause_after_compaction flag, and an instructions string that replaces the default summary prompt. The API detects the threshold, emits a compaction block, and on later requests drops everything before it. The application keeps its own full history; only the model's view is truncated. Failure boundary: a value below 50,000 is rejected, and compaction is unsupported on models outside the listed set (for example Haiku 4.5). Observable output: a response whose content contains a compaction block, after which subsequent requests omit all prior blocks.

Example 4: tool-result clearing configuration with trigger, keep, clear_at_least, and exclude_tools.

{
  "model": "claude-sonnet-5",
  "max_tokens": 2048,
  "tools": [{ "name": "order_lookup" }, { "name": "refund_processor" }],
  "messages": [{ "role": "user", "content": "Lookup and refund order #8891." }],
  "context_management": {
    "edits": [
      {
        "type": "clear_tool_uses_20250919",
        "trigger": { "type": "input_tokens", "value": 50000 },
        "keep": 5,
        "clear_at_least": 20000,
        "exclude_tools": ["refund_processor"],
        "clear_tool_inputs": false
      }
    ]
  },
  "anthropic-beta": "context-management-2025-06-27"
}

What this proves: the clear_tool_uses_20250919 strategy clears old tool results once input crosses 50,000 tokens, keeping the 5 most recent tool-use or result pairs, clearing at least 20,000 tokens' worth to make the cache write worthwhile, and excluding refund_processor results from clearing so the authoritative refund record survives. Cleared results are replaced with placeholder text server-side, so the client's history stays intact and unmodified. clear_at_least exists precisely because clearing invalidates the cached prefix at the clearing point, so you clear enough to justify the cache write. Failure boundary: if keep is set so high that nothing is cleared, the window still overflows; if clear_at_least is too small, the cache thrash costs more than the space saved. Observable output: the model receives placeholder text for old order_lookup results while the refund_processor result remains verbatim, and the client log shows the original results unaltered.

Example 5: token-counting call used to size a request before sending it.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function sizeRequest(
  model: string,
  system: string,
  messages: Anthropic.MessageParam[],
  estimatedOutput: number,
  limit: number
): Promise<{ fits: boolean; inputTokens: number }> {
  const count = await client.messages.countTokens({
    model,
    system,
    messages,
  });
  const inputTokens = count.input_tokens;
  const fits = inputTokens + estimatedOutput <= limit;
  return { fits, inputTokens };
}

const result = await sizeRequest(
  "claude-opus-5",
  SYSTEM_PROMPT,
  conversationHistory,
  4096,
  1_000_000
);

if (!result.fits) {
  // Trim, compact, or summarise before sending. Do not fire a request that will overflow.
  throw new Error(`Request of ${result.inputTokens} input tokens exceeds budget.`);
}

What this proves: the token counting endpoint gives an exact input size before the request is sent, so you can refuse to send an oversized request rather than letting it fail mid-flight or trigger premature compaction. This is the documented sizing mechanism and the workaround for the web-search inflated-count limitation. Failure boundary: the estimate for output is your own guess, so add headroom; the count call itself consumes a round trip and should be cached or batched for high-volume paths. Observable output: result.fits is a boolean you can branch on; result.inputTokens feeds your budget dashboard.

Example 6: tool-result trimmer at the tool boundary.

RELEVANT_FIELDS = [
    "order_id",
    "order_date",
    "total_amount",
    "return_eligible",
    "item_description",
]

def trim_order_result(raw_result: dict) -> dict:
    return {k: v for k, v in raw_result.items() if k in RELEVANT_FIELDS}

def order_lookup(order_id: str) -> dict:
    raw = _call_backend(order_id)  # returns 40+ fields
    return trim_order_result(raw)  # trimmed before it ever reaches history

What this proves: trimming happens inside the tool, at the boundary, so the 35 irrelevant fields (warehouse codes, carrier ids, audit timestamps) never enter the conversation history and never cost tokens on subsequent turns. The trimmer returns a dict with only the five fields the agent acts on. Failure boundary: if the tool returns the raw object and trimming is deferred to a later step, the verbose payload has already been written into history and the damage is done; trimming must occur before the tool_result is returned. Observable output: the tool_result content is 80 to 90 percent smaller than the raw payload, and downstream turns no longer carry stale fields.

Build exercise material

Build a Persistent Case Facts Context Manager. Difficulty 45 minutes. What you will learn: implement the persistent facts block pattern, trim verbose tool results, mitigate progressive summarisation, apply lost-in-the-middle placement, and respect API statelessness.

Step 1: implement a case facts extractor that identifies transactional data (amounts, dates, order numbers, statuses) from tool results. Why: extracting transactional facts into a structured block that is never summarised prevents the progressive summarisation trap from destroying critical values. You should see: a function that takes raw tool output and returns a structured object containing only the transactional facts: customer id, order numbers, amounts, dates, and statuses. Non-transactional narrative content is excluded.

Step 2: implement a persistent facts block that is prepended to every prompt, outside summarised history. Why: the block must persist across every turn regardless of what happens to the conversation history. You should see: a prompt-construction function that always includes the facts block at the top, followed by any summarised history, followed by the current turn. The block is clearly delimited with a section header. Use the buildPrompt function from Example 1 as the reference implementation.

Step 3: build a tool-result trimmer that filters order lookup responses from 40+ fields to only the 5 relevant return-related fields. Why: untrimmed tool results are a silent context budget killer. You should see: a trimming function that takes a raw tool result and returns only the fields needed for the current task. The trimmed result should be 80 to 90 percent smaller than the original. Use Example 6 as the reference.

Step 4: test with a multi-turn conversation where summarisation occurs and verify that transactional facts survive intact across all turns. Why: this validates that the pattern actually works. You should see: a 6 to 8 turn conversation where summarisation occurs after turn 4. After summarisation, the agent should still reference the exact refund amount ($247.83), order number (#8891), and date (March 3rd) from the facts block. Without the block, these values would be lost.

Step 5: add key findings placement logic that positions summaries at the beginning of aggregated inputs to mitigate lost-in-the-middle. Why: models process the beginning and end of long inputs reliably, but findings buried in the middle may be missed. You should see: an aggregation function that places a Key Findings Summary section at the top of combined inputs, followed by detailed results with explicit section headers.

Observable success criteria for the whole exercise: every assembled prompt begins with the delimited facts block, every tool result in history is trimmed, a summarised run still reproduces $247.83, #8891, and 2024-03-03, and aggregated multi-source input leads with a Key Findings Summary. Each criterion is checkable without a model call, by inspecting the rendered prompt strings.

Expanded mechanism depth: Window allocation in practice

The lesson library gives concrete allocation numbers that make the abstract budget tangible. For a 200K customer-support agent with five tools, the system prompt is about 2,600 tokens, the five tool definitions about 17,600 tokens, MCP context about 10,000 tokens, conversation history about 97,000 tokens, current input buffer about 25,000 tokens, and a safety buffer of about 47,800 tokens. The cached components (system, tools, MCP) total about 30K. With prompt caching, that 30K is charged at full price only once per cache period, not on every request. The safety buffer is non-negotiable: without it, a single long user document can push a session past the quality ceiling mid-turn.

For a document-analysis application on the same 200K window, the split inverts: system plus tools stay about 20,600 tokens, but the document content itself takes about 140,000 tokens (70 percent) and is cached if reused, while history shrinks to a minimal 4,400 tokens. The lesson library's point is that conversational agents budget for history, while document tools budget for document content; these are opposite priorities and the same budget template does not serve both. A 1M-window model changes the absolute numbers but not the discipline; the 128K output ceiling and the quality ceiling both still apply.

Expanded mechanism depth: Image and document limits

A request to a 1M-window model can include up to 600 images or PDF pages; the limit drops to 100 on a 200K-window model. Images and PDF pages are not free of the window budget; each consumed page or image is tokenised and counts toward the same 1M or 200K total. The lesson library notes that image tokens scale with resolution, a high-resolution image costs roughly 800 tokens while a low-resolution image costs roughly 85 tokens, and that multi-modal inputs must be accounted for in any budget plan. This matters directly for the exam scenario where a document-analysis agent loads a 500-page contract: even at 100 pages per request on a 200K model, the page budget is the binding constraint, not just the token budget.

Expanded mechanism depth: Context rot in production

Context rot is the documented name for the monotonic degradation of accuracy and recall as token count grows. The lesson library expresses the same idea as an effective quality ceiling near 147,000 to 152,000 tokens, but that number is a planning heuristic, not an Anthropic-measured boundary. The two statements are compatible if you treat the figure as a community estimate and context rot as the documented phenomenon. In production, the practical implication is that past the high-140000s region, fine-grained attention to middle content degrades even though the model still processes the full window. The fix is never to extend the window further but to restructure: pull critical content to the ends, externalise low-value bulk to tools or retrieval, and protect exact facts in the facts block.

Expanded mechanism depth: Compaction summary structure detail

The default compaction summary prompt is documented and structured as five labelled parts wrapped in <summary></summary> tags: Task Overview, Current State, Important Discoveries, Next Steps, and Context to Preserve. This is not an arbitrary format; it is the documented shape of a handoff summary and is directly reusable as a scratchpad or phase-summary schema. When you supply your own instructions to the compact_20260112 strategy, you replace the entire default prompt, so your replacement should preserve these five concerns or you will lose one of them. In particular, "Context to Preserve" is the field that should carry the verbatim facts block content, because anything not named there is subject to the summarisation that compaction performs.

Expanded mechanism depth: Context editing placeholder replacement and server-side clearing

Under clear_tool_uses_20250919, cleared results are replaced with placeholder text, not deleted. The placeholder is what the model sees; your client history keeps the original result untouched. This is a deliberate design: clearing happens server-side, before the prompt reaches the model, so the application can later replay or audit the complete exchange. The clear_tool_inputs flag controls whether the tool inputs are cleared alongside the results; setting it false keeps the inputs visible while only the bulky outputs are replaced. exclude_tools names tools whose results must never be cleared, which is how you keep an authoritative record such as a refund confirmation while still trimming verbose lookups.

Expanded mechanism depth: Cache minimums by tier and the silent bypass

The minimum cacheable length is model-specific: 1,024 tokens for Sonnet 4.6 and Opus 4.8 (and by extension the newer Sonnet 5 and Opus 5 tiers), and 4,096 tokens for Haiku 4.5. Below that minimum, the API silently bypasses caching regardless of any cache_control you set. This is a common source of "why am I not seeing cache reads" confusion: a 900-token static system prompt on Haiku 4.5 will never cache. The fix is to either pad the cached prefix past the minimum or accept that very small static content is not worth caching. The lesson library calls this out explicitly and warns that the minimum is the reason some otherwise-correct cache setups show zero cache_read_input_tokens.

Expanded mechanism depth: Token counting edge cases

The token counting endpoint returns exact input tokens but knows nothing about your output; you must supply your own output estimate and add headroom. It also does not account for the cache_creation_input_tokens versus cache_read_input_tokens split, it returns the raw input count as if uncached. Therefore use it to decide fit, not to decide cost. A second edge case is the web-search inflation noted earlier: after a server-side web search, the SDK may accumulate cache_read_input_tokens from the tool's internal calls into the apparent total, so a naive size check may report a huge input count and trigger premature compaction even though your own context is small. The token counting endpoint, run on your own assembled messages, gives the true size of what you control.

Common production failure modes

The following failure modes recur in real systems and map directly to exam traps.

First, the silent summarisation loss. A support agent summarises history every few turns, and a customer-stated refund amount of $247.83 becomes "a refund was discussed". The agent later refers to "your recent refund request" with no amount or order id. The fix is the prepended facts block; the amount, order id, and date are never in the summarised region.

Second, the middle-drop. A 180K context places a hard security constraint at the 90K mark. The model ignores it because middle content is underweighted. The fix is layout: move the constraint to the system prompt (start) or the current user turn (end).

Third, the untrimmed tool result. An order lookup returns 40 fields and the raw object is stored in history. Over 30 turns the stale fields cost thousands of tokens and crowd out the safety buffer. The fix is trimming at the tool boundary.

Fourth, the broken cache prefix. A timestamp or request id is embedded in the "static" system block, so the prefix changes every call and caching never engages. The fix is to keep cached content truly stable: no dynamic values, no per-request personalisation in cached sections.

Fifth, FIFO truncation of the original goal. Pure first-in-first-out truncation drops the user's opening instruction (the oldest message) exactly when the window fills, causing silent goal drift. The fix is priority-based truncation that protects P0 and P1 content.

Sixth, treating the 1M window as a licence to skip curation. A team puts 800K of loosely relevant material into a 1M window and gets worse results than a curated 150K prompt. Context rot still applies. The fix is curation, not size.

Exam trap deep dives

The reference page lists four exam traps. Each is expanded here with the reasoning chain the exam expects.

Trap one: thinking progressive summarisation is safe for transactional data. The exam expects you to recognise that summarisation systematically destroys numerical values, dates, and specific identifiers. A persistent facts block must hold these outside summarised history. The distractor answers are "instruct the model to preserve values when summarising" (unreliable, because abstractive summarisation paraphrases) and "store full history in a database and retrieve on demand" (works, but the facts block is the lighter-weight, always-in-context fix the question is steering toward).

Trap two: assuming lost-in-the-middle is solved by telling the model to pay attention. The exam expects the structural fix: place key findings at the beginning of aggregated inputs and use explicit section headers. Prompt-based reminders are unreliable for position effects. The worked layout is a "Key Findings Summary" section at the top, then detailed results with clear section boundaries.

Trap three: keeping full tool results because the model might need them later. The exam expects trimming to relevant fields before results enter history. Untrimmed results from 40-field lookups exhaust the budget across turns. The fix is a trimmer at the tool boundary.

Trap four: believing conversation history can be selectively truncated without consequences. The exam expects you to know the API is stateless, so each request needs complete history, and selective truncation breaks coherence. Use facts blocks and summarisation instead of truncation.

Token budgeting worked arithmetic

The lesson library presents priority-based truncation with five tiers. P0 (system prompt, tool definitions, current user input) is never removed. P1 (original task instructions, immutable facts block, key preferences) is last to be removed. P2 (recent 5 to 10 turns) is preserved until critically full. P3 (mid-conversation exchanges, older tool results) is FIFO-truncated as needed. P4 (acknowledgements, chit-chat) is removed first. The implementation below tags each message with a priority and removes from the bottom of the priority stack when the budget is exceeded; P0 messages are filtered out of the removal set so they are never touched.

interface PrioritizedMessage {
  role: "user" | "assistant" | "tool";
  content: string;
  priority: 0 | 1 | 2 | 3 | 4;
  tokenCount: number;
}

function truncateByPriority(
  messages: PrioritizedMessage[],
  budget: number
): PrioritizedMessage[] {
  let total = messages.reduce((sum, m) => sum + m.tokenCount, 0);
  const removable = [...messages]
    .filter((m) => m.priority > 0)
    .sort((a, b) => b.priority - a.priority);
  for (const msg of removable) {
    if (total <= budget) break;
    const idx = messages.indexOf(msg);
    if (idx !== -1) messages.splice(idx, 1);
    total -= msg.tokenCount;
  }
  return messages;
}

What this proves: priority truncation is deterministic and auditable, unlike FIFO. P0 content (the system prompt and tool definitions) is structurally protected because the removal set excludes priority 0. The facts block, as a P1 item, survives all but the most extreme truncation. Failure boundary: if priorities are not tagged at creation time, retroactive classification is error-prone and may mislabel the facts block as removable. Observable output: after truncation, messages still contains every P0 and P1 entry and the oldest P4 chit-chat is gone.

Lost-in-the-middle worked layouts

For aggregated multi-source input, the recommended structure leads with a Key Findings Summary. The lesson library gives the canonical shape: a "Key Findings Summary" section with one bullet per source (for example "Source A: 12 percent market growth in renewable sector (2023)"), followed by "Detailed Findings" with a named subsection per source. The model attends to the summary at the top reliably; the detailed sections below carry the supporting evidence. This is the structural antidote to the middle-drop, and it is the layout the exam rewards over any prompt instruction to "pay attention to everything".

A second layout rule applies within a single long document: put the specific question at the very end, after the document, so it sits at the high-attention end of the context. The lesson library makes this explicit: for a long document for analysis, the question belongs after the document, not before it.

Multi-agent and memory tool tie-ins

In multi-agent systems, context window management becomes a per-agent and per-handoff concern. Upstream agents should return structured findings (claim, source, relevance, date) rather than verbose reasoning, so downstream agents do not waste window on reasoning they cannot use. This is a source-tier decision: the upstream agent's output is a context source, and trimming it at the source is cheaper than trimming it after it has already been paid for in the upstream call.

The memory tool ({"type": "memory_20250818", "name": "memory"}) is the documented, model-driven alternative to a hand-maintained facts block. Where the immutable facts block is populated by your application code, the memory tool lets the model decide what is worth persisting and retrieve it on demand via /memories. The handler executes view, create, update, and delete against storage the application controls, and must reject paths outside /memories to prevent path traversal. The lesson library positions the memory tool as one of three built-in primitives (with context editing and compaction) that implement the same ideas as the hand-built patterns. For the exam, the distinction to hold is: the facts block is application-owned and always in context; the memory tool is model-driven and retrieved just in time, which keeps the active window focused.

Provenance tie-in: where content arrives as a document block or a search_result block, the documented enforcement mechanism for attribution is the citations feature or the required source and title fields, not a prompt instruction. The exam-relevant judgement is unchanged, because attribution still has to survive multi-step synthesis in application code, but the documented mechanisms are the preferred enforcement point and prompt-preserved mappings are what you use for content that does not arrive as documents or search results.

Summary of the documented primary path

For a long-running conversation on a supported model, the documented primary path is: enable compact_20260112 with an explicit input_tokens trigger at or above 50,000 (default 150,000), optionally supply instructions that preserve the five-part summary shape and name the facts block in "Context to Preserve", let the API emit the compaction block and drop everything before it on later requests, and keep your own application-side facts block prepended outside the summarised region so verbatim values survive. Use context editing (clear_tool_uses_20250919) for fine-grained tool-result trimming with keep, clear_at_least, exclude_tools, and clear_tool_inputs. Use prompt caching with correctly placed breakpoints and awareness of the per-tier minimum. Use the token counting endpoint to size requests before sending. Trim tool results at the boundary. Place critical content at the ends to defeat lost-in-the-middle. This is the complete, documentation-first picture that resolves the reference material's omissions.

Worked end-to-end scenario

Consider a customer-support agent that runs for 60 turns over two hours, investigates a billing issue across multiple systems, escalates to a supervisor, and resolves the refund. The documented primary path combines compaction, a prepended facts block, tool-result trimming, and caching.

At session start, the application extracts the customer id, the issue type, the exact amount, the order id, the date, and the escalation level into the facts block and prepends it via the buildPrompt function from Example 1. The system prompt and tool definitions carry cache_control breakpoints so they are written once and read at 0.1x thereafter. A clear_tool_uses_20250919 edit with exclude_tools: ["refund_processor"] keeps the authoritative refund confirmation out of trimming while verbose lookups are cleared once input crosses 50,000 tokens.

As the conversation grows past 150,000 input tokens, the compact_20260112 edit fires. The API generates a summary in the five-part shape, emits a compaction block, and on the next request drops everything before it. Because the facts block is assembled outside the summarised region by buildPrompt, it survives the compaction: the agent still references $247.83, order #8891, and the March 3 date verbatim, while the narrative of the investigation is compressed. This is exactly the failure the reference page warns about, resolved by documentation-first means rather than client-side summarisation alone.

The observable outcomes you can assert without a model call are: the rendered prompt always begins with the delimited facts block; every tool_result in history is trimmed to five fields; after a compaction the narrative is shorter but the facts block is byte-identical; the usage field shows cache_read_input_tokens climbing on repeated prefixes; and a token-count check before each send confirms the request fits the limit. Each is a concrete, testable property of the design.

Comparison: client-side versus server-side compaction

The reference material presents client-side progressive summarisation as the default and the facts block as the only protection. Documentation reframes this: server-side compaction is the recommended strategy, and client-side summarisation (the hand-built Haiku-call pipeline the lesson library describes) is now one option among several, including the built-in compact_20260112 strategy and the SDK tool_runner compaction in TypeScript and Ruby. The table below contrasts them.

Server-side compaction runs in the API, requires no orchestration code, emits a compaction block the API itself uses as the truncation boundary, and is supported on the listed 1M and recent models. Its limitation is the web-search inflated-count issue and the fact that it still summarises, so verbatim facts must live outside the summarised region. Client-side compaction gives you full control over the summary prompt and works on any model, but you must build the trigger, the summarisation call, the history replacement, and the audit trail yourself, and you pay for the extra model call. The facts block is required under both, because both approaches summarise narrative content.

The practical recommendation for the exam is: when asked for the default documented strategy for a long conversation on a supported model, answer server-side compaction with the compact_20260112 strategy and the compaction block boundary; when asked how to protect exact transactional values, answer the application-owned facts block prepended outside the summarised region. The reference material's facts-block answer remains correct; it is simply no longer the whole story.

Prompt caching layout decision tree

The reference page's cache example is correct but under-specified. The full decision is:

First, identify every block that is stable across requests: tool definitions, system instructions, long reference documents, stable few-shot examples. Place these first, in the tools array, then the system array, then the start of messages.

Second, place a cache_control: {"type": "ephemeral"} breakpoint at the end of each stable layer. Up to four breakpoints are allowed; most applications need two or three. Never place a breakpoint on volatile content such as the current user message, because that breaks the stable prefix and every request pays full price.

Third, check the per-tier minimum. On Haiku 4.5 the cached prefix must exceed 4,096 tokens or caching silently bypasses; on Sonnet 4.6, Opus 4.8, Sonnet 5, and Opus 5 the floor is 1,024 tokens. If your static content is below the minimum, either combine it with other stable content to cross the threshold or accept no caching.

Fourth, choose the TTL. The default 5-minute TTL is right for interactive traffic that hits the prefix frequently; the 1-hour TTL costs roughly 2x to write but survives longer idle gaps and is right for long-lived sessions with stable reference documents. The read cost is roughly 0.1x regardless of which TTL wrote the entry.

Fifth, monitor cache_read_input_tokens in the usage field. A climbing read count confirms the breakpoint is correctly placed; a persistent zero means the prefix is changing per request or the minimum is not met. Remember that cached tokens still occupy the window, so caching is a cost lever, not a space lever.

Token counting and budget dashboard pattern

The token counting endpoint is the documented way to size a request before sending it, and it underpins a budget dashboard. A minimal pattern: before each send, call countTokens with the assembled system, messages, and tools; add your output estimate and a 15 to 20 percent safety overhead; compare against the model limit; and refuse to send if it does not fit, triggering compaction or trimming instead. Because the count call knows nothing about caching, use it only for fit, and read the real usage after the call for cost. For high-volume paths, cache or batch the count call to avoid paying a round trip per request. The web-search inflation caveat means you should count your own assembled messages, not trust an accumulated cache_read_input_tokens total that includes the tool's internal calls.

This closes the loop with the ownership map: the model owns attention, the API owns compaction and caching and the usage split, and application code owns the facts block, trimming, priority truncation, and the decision to consult the token counting endpoint before each send. A reliable system assigns each guarantee to its correct layer rather than expecting one layer to cover another.

Context editing strategy detail: clear_thinking and cache interaction

The clear_thinking_20251015 strategy clears extended thinking blocks rather than tool results. Its cache interaction differs from tool-result clearing: when thinking blocks are kept, the cache is preserved; when they are not kept, the cache is invalidated at the clearing point. This matters because thinking blocks count as input tokens on the model families that retain them by default (Opus 4.5 and later, Sonnet 4.6 and later, Fable 5, Mythos 5, Mythos Preview), while earlier Opus and Sonnet models and all Haiku models strip them automatically when passed back. The lesson for the exam is that retention is model-dependent, and you should set keep explicitly whenever your code spans model tiers, because the default differs across families.

The reason clear_at_least exists for tool-result clearing is specific to cache economics: clearing invalidates the cached prefix at the clearing point, so if you clear too little, you pay the cache-write cost without freeing enough space to matter. clear_at_least forces a minimum clear volume so the cache write is justified. This is a nuance the reference page does not cover, because the reference predates the cache-aware clearing semantics.

Memory tool handler security and path containment

The memory tool is {"type": "memory_20250818", "name": "memory"}, available on Claude 4 and later. The model requests operations (view, create, update, delete) under /memories, and the application executes them against storage it controls, returning a tool_result. The critical security property is path containment: the handler must reject any path outside /memories, because a path traversal attempt could otherwise reach arbitrary files. The /memories prefix is mapped by the handler onto the real storage root. This is the application's responsibility, not the model's, and it is the same containment discipline that governs any tool that touches a filesystem. The documented purpose of the memory tool is just-in-time context retrieval, so the active window stays focused on what the current step needs rather than carrying everything.

For the exam, the distinction to hold is between the three related but separate ideas: the application-owned facts block (always in context, populated by your code), the memory tool (model-driven, retrieved on demand, with handler-enforced path containment), and server-side compaction (API-driven, summarises the narrative and emits a compaction block). They compose: the facts block and memory tool protect exact values, while compaction trims the narrative; context editing clears bulky tool results and thinking blocks in between.

Safety buffer and priority truncation arithmetic recap

The lesson library is explicit that the safety buffer is not optional. A buffer of 10 to 25 percent of the window absorbs unexpectedly large turns; without it, a single long user document pushes a session past the quality ceiling with no recovery path. In the 200K support-agent allocation, the buffer is about 47,800 tokens (roughly 24 percent), which is what allows the system to keep active context near 130K while leaving room for spikes. In the document-analysis allocation on the same window, the buffer shrinks to about 10,000 tokens (5 percent) because the document dominates and the task is single-shot rather than turn-heavy.

Priority truncation arithmetic follows from the tiers: protect P0 and P1 unconditionally, preserve P2 until the window is critically full, FIFO-truncate P3 as needed, and remove P4 first. The failure mode to avoid is tagging the facts block as anything lower than P1, because then an aggressive truncation pass could drop it. The facts block is, by definition, the content that would cause a silent hard-to-detect failure if lost, which is exactly the P1 criterion.

Exam framing summary

The exam frames Task 5.1 around a small set of recurrent scenarios, each mapping to a documented mechanism. A long conversation that loses exact values points to the prepended facts block outside the summarised region, now reinforced by server-side compaction as the documented primary strategy. A critical instruction ignored mid-context points to lost-in-the-middle and the structural fix of end-placement. An overflowing window from verbose tool output points to trimming at the tool boundary and to priority truncation that protects P0 and P1. A request that pays full price every turn points to a misplaced cache breakpoint or a below-minimum prefix. A statelessness question points to complete-history-per-request plus the facts block. A long conversation on a supported model points to compact_20260112 with the compaction block boundary. In every case, the documented mechanism is the first answer, and the application-side protection is the necessary complement, because compaction still summarises and anything that must survive verbatim has to live outside the summarised region.

The six required mechanisms at a glance

This section restates the six mechanisms the task requires, each tied to its documented behaviour and its exam relevance, so the writer can confirm complete coverage.

First, the persistent facts block prepended outside the summarised region, guaranteed by a single prompt-construction function that always places it between the system prompt and the summarised history. It survives both client-side summarisation and server-side compaction because it is never in the region those operations act on.

Second, the array-form system field with a correctly placed cache breakpoint at the end of the static block, shown next to the wrong placement that interleaves volatile content and breaks the prefix. The usage fields input_tokens, cache_creation_input_tokens, and cache_read_input_tokens distinguish a cache miss from a hit, and all three count toward the window.

Third, the server-side compaction request with an explicit input_tokens trigger at or above the 50,000 floor (default 150,000), emitting a compaction block that later requests use as the truncation boundary.

Fourth, the tool-result clearing configuration with trigger, keep, clear_at_least, exclude_tools, and clear_tool_inputs, clearing server-side and replacing results with placeholder text while the client history stays intact.

Fifth, the token-counting call used to size a request before sending it, returning exact input tokens so an oversized request is refused rather than failed mid-flight.

Sixth, the tool-result trimmer at the tool boundary, returning only the fields the agent acts on so verbose payloads never enter history.

Together these six form the complete, documentation-first picture of context window management for Task 5.1, with the facts block as the constant that protects verbatim truth across every other mechanism's compression or clearing.

Mechanism reference: 1. Escalation criteria as written prompt policy

Escalation policy for a support agent is written policy first and code second. The prompt holds the decision rule the model follows, the tool schema holds the shape of the handoff, and application code holds the non-bypassable gates. None of these layers substitutes for the others, which is why the exam treats prompt criteria plus schema enforcement plus hook enforcement as complementary rather than competing answers.

The smallest correct escalation criteria block names three triggers and two anti-patterns explicitly. It states when to escalate and when to resolve, and it states what not to use. The structure borrows from the RACCE framework in, where Constraints are testable, few enough to follow, and followed by Examples placed last for maximum influence.

The critical properties are testability and enumerability. A constraint such as "never escalate on sentiment or self-reported confidence" can be verified from output. A constraint such as "be conservative about escalation" cannot be verified and therefore does not calibrate. The escalation-patterns lesson is explicit that thresholds without semantics do not replace analysis, and the forensics Rule 22 records vague directives like "be conservative" as a consistently failed fix.

The three triggers, as tested, are:

• Explicit request for a human. The user names a person as the desired handler. Phrases vary but contain "human," "person," "real person," or "manager" as the target. This trigger is absolute and immediate. The agent does not investigate first and does not ask for confirmation.

• Policy gap. The governing rules are silent or internally ambiguous on the specific request. The agent has retrieved the relevant policy and confirmed the silence. A gap is not a violation. A violation has a documented answer and is handled by applying that answer, not by escalating.

• Inability to make meaningful progress after a genuine attempt. Tools have been called, data gathered, and a wall remains: conflicting information that no tool resolves, missing access, or a technical fault. "Might not be able to handle this" without trying is not this trigger.

Two signals are explicitly excluded as triggers and appear as distractors in every miscalibration item:

• Sentiment or frustration detection. See the dedicated subsection below.

• Self-reported confidence scores. See the dedicated subsection below and the Task 5.5 distinction.

Few-shot examples attached to these criteria are not enumerated case lists. They demonstrate generalizable boundary reasoning so the agent handles unseen gaps. The forensics Rule 21 records that an agent correctly escalating an unseen loyalty-program dispute after two boundary examples proves the examples taught the principle. The system-prompt-design lesson states that 2 to 4 input and output pairs showing expected interaction patterns produce the most reliable behavior, and that examples belong at the end of the prompt, closest to the user input.

Example 1 below shows the explicit escalation criteria with worked examples for each trigger. It is the first of the six required substantial examples and it proves the testability requirement: every rule is verifiable and the examples sit last.

You are a customer support agent for Nimbus Retail. Your job is to resolve
issues within documented policy or escalate to a human when one of three
triggers applies. You must not escalate on sentiment, frustration keywords,
or self-reported confidence.

ROLE
You are a careful support agent who retrieves policy before deciding and never
invents policy by analogy.

ESCALATION CRITERIA - escalate when exactly one of these holds:

1. Explicit human request: the customer names a human as the handler
   ("human," "person," "real person," "agent," "manager," "someone on your team").
   Override any capability assessment. Do not ask for confirmation, do not
   investigate first. Call escalate_to_human immediately and include whatever
   context you already hold.

2. Policy gap: the governing policy is silent or internally ambiguous on this
   specific request after you have retrieved the relevant policy text.
   Distinguish gaps from violations. A violation has a documented answer
   (for example, "return window is 30 days, request is at day 45" means deny).
   A gap has no answer and must escalate. Being within a dollar limit does not
   grant policy authority in a gap.

3. Inability to make meaningful progress after a genuine attempt: you have
   called the available tools, gathered the relevant data, retried a transient
   failure once where isRetryable is true, and still cannot advance because
   information conflicts, access is denied, or the system lacks the capability.
   "Might not be able to handle this" without trying is not this trigger.
   Retry exhaustion on a tool whose errorCategory is transient and whose
   isRetryable is true is this trigger once the retry budget is exhausted.

RESOLVE AUTONOMOUSLY when none of the above holds: standard billing
adjustment within the documented window, duplicate-charge refund via
process_refund, address update, order status, and other actions explicitly
covered by retrieved policy.

ANTI-PATTERNS - do NOT escalate based on:
- Sentiment, frustration language, punctuation ("!!!", "unacceptable"), emoji,
  or any tone proxy such as short replies.
- Self-reported confidence scores or a model-generated numeric certainty.

FEW-SHOT EXAMPLES

Example 1 - explicit human request overrides capability
User: "I want to speak to a real person NOW. My order 88921 was charged twice
and I have been waiting three weeks."
Thought: explicit human request is present, so escalation is mandatory
regardless of the fact that I can resolve duplicate charges in one tool call.
Action: escalate_to_human with customer_id, root cause as duplicate charge on
order 88921, and note that resolution via process_refund is available for the
human to apply.

Example 2 - frustrated but resolvable issue stays with the agent
User: "This is RIDICULOUS, nothing ever works! My order 77231 shows a duplicate
charge of $47.20."
Policy retrieved: duplicate charges are refundable within 60 days, no manager
approval under $500.
Thought: frustration is present but the issue is within policy and within
capability. No explicit human request and no policy gap. Resolve autonomously
after acknowledging.
Action: "I understand this is frustrating. I can process the $47.20 refund for
order 77231 right now." Then call process_refund with the verified order ID.

Example 3 - policy gap caused by silence on competitor price matching
User: "Another store has this laptop $120 cheaper. Will you match it?"
Policy retrieved: price adjustments cover same-site drops within 14 days with
original receipt, silent on competitor matches.
Thought: this is not a violation with a documented denial, it is a gap because
the policy does not address competitor pricing. Being under the $500 limit does
not grant authority to decide. Escalate with the identified silent clause.
Action: escalate_to_human naming the silent competitor-match clause, with the
customer ID, the $120 amount, and recommended action for the human to decide.

Example 4 - inability to progress after genuine attempt
User: "My invoice says $2,410 but I was quoted $1,890. Which is correct?"
Actions taken: called get_invoice for two invoice IDs, results conflict, called
lookup_order, still irreconcilable, retried once on transient timeout.
Thought: genuine attempt exhausted, wall remains due to conflicting source data
no tool resolves. Escalate with the conflict.
Action: escalate_to_human describing both invoice IDs, both amounts, the
attempted lookups, and that no tool can reconcile the discrepancy.

This block proves three things the exam tests. First, the three triggers are named operationally so a grader can verify mapping. Second, the anti-patterns are explicitly prohibited so sentiment and confidence cannot be substituted. Third, the examples sit last and demonstrate boundary reasoning, not just labels, which is how the agent generalises to unseen gaps.

Mechanism reference: 2. Tool definition and input schema for the escalation tool

The escalation handoff is only as reliable as its schema. If completeness is requested in prose but not required in the contract, the model can omit fields and still produce a syntactically valid call. The correct fix is to make completeness structurally enforced at the interface.

A tool definition is an object with name, description, and input_schema passed in the tools array of a Messages request. The name is the snake_case identifier the model must produce. The description controls selection accuracy and must state what the tool does, when to use it, and what result shape to expect. The input_schema is a JSON Schema object that constrains what the model can emit as input. Every property in properties should carry its own description with format guidance, and required must list every field without which the handoff is not actionable.

The documented input schema rules relevant to handoff enforcement are:

• type must be "object" at the top level for the handoff payload. Properties carry their own type values (string, number, integer, boolean, array, object) matched exactly to what the backend expects.

• enum constrains fixed-value parameters. For a field like escalation_reason or urgency the schema must enumerate every valid value so the model cannot invent one.

• required is an array of keys that must be present. Only fields listed there are enforced. If customer_id is not in required, the model can emit a call without it and the call will validate.

• description on each property guides parameter inference. Without it the model guesses format, for example whether refund_amount is a number or a formatted string.

• strict as a top-level tool property, when true, constrains token sampling to schema-valid output via grammar-constrained sampling, guaranteeing the input matches input_schema and the name is one of the provided tools.

• additionalProperties controls whether extra keys are allowed. For a handoff that must be consumed by a human queue, setting it to false prevents drift into free-form keys that downstream parsing ignores.

The distinction between success and failure in tool results also shapes escalation. The Messages API uses a tool_result block with is_error to signal failure. A structured error object with isError, errorCategory, and isRetryable lets the agent reason about retry versus escalate rather than treating every empty array as an error. This matters for exhaustion detection, because a transient error with isRetryable: true retries, while an isRetryable: false permission or validation error escalates without wasted retries.

Example 2 shows an escalation tool whose schema forces a complete self-contained handoff. It is the second required example.

import Anthropic from "@anthropic-ai/sdk";

const escalateToHumanTool = {
  name: "escalate_to_human",
  description:
    "Escalate the current support case to a human agent. Use when the " +
    "customer explicitly requests a human, the request falls in a policy gap " +
    "where governing policy is silent or ambiguous, or you cannot make " +
    "meaningful progress after a genuine attempt including one retry of any " +
    "isRetryable transient error. The human has no transcript access and must " +
    "be able to act from this payload alone. Do not use for sentiment, " +
    "frustration, or self-reported confidence. Returns a handoff receipt with " +
    "queue assignment.",
  strict: true,
  input_schema: {
    type: "object",
    properties: {
      customer_id: {
        type: "string",
        description: "Verified customer identifier, for example CUST-4421 or USR-48721. Must be the record the customer confirmed, not a heuristically selected match.",
      },
      escalation_reason: {
        type: "string",
        enum: [
          "explicit_human_request",
          "policy_gap",
          "inability_to_progress",
        ],
        description: "One of the three valid triggers. Use explicit_human_request when the user names a human, policy_gap when governing policy is silent or ambiguous on this request, inability_to_progress after genuine attempt and retry exhaustion.",
      },
      root_cause: {
        type: "string",
        description: "One sentence stating the underlying issue in plain language, for example 'Duplicate charge of $847.00 on order 88921 due to gateway retry'.",
      },
      relevant_ids: {
        type: "object",
        properties: {
          order_id: { type: "string", description: "Primary order or invoice ID relevant to the case, if any." },
          invoice_ids: {
            type: "array",
            items: { type: "string" },
            description: "Additional invoice or order IDs when conflicting records exist, otherwise omit.",
          },
        },
        required: ["order_id"],
        description: "Identifiers the human needs to locate the case without the transcript.",
        additionalProperties: false,
      },
      amounts: {
        type: "object",
        properties: {
          disputed_amount: { type: "number", description: "Monetary amount in dispute as a number, for example 847.00. Omit when not monetary." },
          currency: { type: "string", enum: ["USD", "EUR", "GBP"], description: "ISO currency code when amounts is present." },
        },
        required: [],
        description: "Monetary context, omitted for non-monetary cases. Never invent a value.",
        additionalProperties: false,
      },
      attempted_actions: {
        type: "array",
        items: { type: "string" },
        description: "Ordered list of actions already taken, for example 'lookup_order 88921 succeeded', 'process_refund dry-run blocked by policy check'. Include one retry attempt for any transient error where isRetryable was true.",
      },
      blocking_reason: {
        type: "string",
        description: "Why autonomous resolution cannot proceed. For policy_gap name the silent clause, for inability_to_progress name the irreconcilable data or missing capability.",
      },
      recommended_action: {
        type: "string",
        description: "Concrete next step for the human, for example 'Approve $847 refund to original payment method; customer not at fault; gateway retry caused duplication'.",
      },
      conversation_summary: {
        type: "string",
        description: "Three sentence narrative arc of the conversation, not a transcript dump or turn reference. What the customer asked, what the agent found, why this handoff is needed.",
      },
      urgency: {
        type: "string",
        enum: ["low", "normal", "high", "critical"],
        description: "Queue priority. Use high when an explicit request is paired with reiterated frustration. Does not drive the escalation decision itself.",
      },
    },
    required: [
      "customer_id",
      "escalation_reason",
      "root_cause",
      "relevant_ids",
      "attempted_actions",
      "blocking_reason",
      "recommended_action",
      "conversation_summary",
    ],
    additionalProperties: false,
  },
} as const;

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  tools: [escalateToHumanTool],
  tool_choice: { type: "auto" },
  system: "You are Nimbus Retail support. Follow the escalation criteria exactly.",
  messages: [{ role: "user", content: "My order 88921 was charged twice." }],
});

Every required field maps to a load-bearing piece of the human task: customer_id prevents re-identification, escalation_reason with enum makes the trigger auditable, root_cause plus blocking_reason explains why autonomy stopped, attempted_actions prevents duplicate work, recommended_action makes the handoff productive, and conversation_summary replaces a transcript the human cannot open. The enum on escalation_reason and urgency is not decorative; without it the model can emit values the queue does not route. The additionalProperties: false prevents drift into reference IDs or turn pointers that look helpful but shift work back onto the human.

Mechanism reference: 3. The full tool_choice value space and what forcing a specific tool does

The tool_choice parameter controls whether the model may act, must act, or must act in a specific way on this turn. The platform defines four values. Only two of them receive most exam attention, which is why grounding must present all four and the interaction with stop_reason.

• {"type": "auto"} lets the model decide whether to call a tool or respond with text. This is the default. With auto the response stop_reason can be either "tool_use" or "end_turn", and the agent loop must handle both. This is the correct default for a general-purpose support agent where most turns are conversational and only some need a tool.

• {"type": "any"} requires a tool call on this turn. The model must select one of the available tools and produce a tool_use block. The stop_reason is always "tool_use" and never "end_turn", so a loop using any must enforce a maximum turn budget or it runs forever. With any the model chooses which tool, so it can still select the wrong tool when none is appropriate. For that reason any is best served by a single well-designed tool whose enum covers all outcomes.

• {"type": "tool", "name": "<tool_name>"} forces exactly that tool. The model has no freedom to answer with text or to select a different tool. The stop_reason is always "tool_use" for that specific tool. This is the form that makes a handoff unskippable.

• {"type": "none"} suppresses all tools. The model must respond with text only and stop_reason is always "end_turn". This is used for greeting turns, confirmation asks before an irreversible operation, and error explanations where a retry would repeat the failure.

The exam favours auto and the specific-tool form, but all four belong in the answer and all four appear in production patterns. The critical exam traps are forgetting that any never produces end_turn so a loop budget is mandatory, and assuming auto will always call the desired tool when the tool is merely relevant.

A deliberate escalation design therefore pairs two fields. The prompt holds the when, the forced tool choice holds the guarantee that when the condition matches the handoff fires. Example 3 shows the pattern that makes the handoff unskippable after detection.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const tools = [
  {
    name: "escalate_to_human",
    description: "Escalate to a human with a complete self-contained handoff.",
    strict: true,
    input_schema: {
      type: "object",
      properties: {
        customer_id: { type: "string", description: "Verified customer ID" },
        escalation_reason: {
          type: "string",
          enum: ["explicit_human_request", "policy_gap", "inability_to_progress"],
          description: "One of the three valid triggers",
        },
        root_cause: { type: "string", description: "Plain-language cause" },
        relevant_ids: {
          type: "object",
          properties: { order_id: { type: "string" } },
          required: ["order_id"],
          additionalProperties: false,
        },
        attempted_actions: { type: "array", items: { type: "string" } },
        blocking_reason: { type: "string" },
        recommended_action: { type: "string" },
        conversation_summary: { type: "string" },
      },
      required: [
        "customer_id",
        "escalation_reason",
        "root_cause",
        "relevant_ids",
        "attempted_actions",
        "blocking_reason",
        "recommended_action",
        "conversation_summary",
      ],
      additionalProperties: false,
    },
  },
  {
    name: "process_refund",
    description: "Process a refund for order_id after policy checks.",
    input_schema: {
      type: "object",
      properties: {
        order_id: { type: "string" },
        amount: { type: "number" },
        reason: { type: "string" },
      },
      required: ["order_id", "amount", "reason"],
    },
  },
];

// Step 1: the agent loop detects an explicit human request via a cheap
// classifier or keyword rule that matches "human, person, real person, manager".
// That detection is application code, not a model confidence judgement.
// Once matched, the next model turn is forced to the handoff tool so the
// escalate path cannot be talked past or soft-pedalled.

// If detection is true, force the escalation tool on the very next turn:
const handoffResponse = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  tools,
  // This is the documented form that forces a specific tool. The model has no
  // freedom to reply with text or to pick process_refund instead.
  tool_choice: { type: "tool", name: "escalate_to_human" },
  system:
    "You are Nimbus Retail support. Honour explicit human requests immediately. " +
    "Emit a complete handoff with no missing required fields.",
  messages: [
    { role: "user", content: "I want to speak to a human now, stop troubleshooting. Order 88921." },
  ],
});

// handoffResponse.stop_reason is always "tool_use" and the tool_use block
// name is always escalate_to_human when this form is used.
// An application gate around this call enforces the required fields even when
// strict is true, so the first parse failure is surfaced to the model as a
// tool_result with is_error, not silently swallowed.
console.log(handoffResponse.stop_reason); // "tool_use"

// Contrast: {"type": "any"} would also force a tool call but would let the
// model choose between escalate_to_human and process_refund, so the handoff
// could be skipped in favour of an autonomous refund. {"type": "auto"} would
// also let the model skip the handoff entirely by answering with text. Only
// {"type": "tool", "name": "escalate_to_human"} removes both degrees of
// freedom on the turn where escalation is required
//.

What forcing does to model freedom is the point. With auto the model retains two freedoms: whether to act and which tool to use. With any it retains one freedom: which tool to use. With type: tool it retains zero freedoms on tool selection for that turn. That is the guarantee a "cannot be left to model discretion" requirement needs.

There is a cost. Forcing suppresses leading text. When tool_choice is any or a specific tool name the API prefills the assistant turn to guarantee the tool call, so the model does not emit a natural-language explanation before the tool_use block, even if the prompt asks it to explain first. For most handoffs this is acceptable because the handoff payload plus a short post-handoff confirmation message to the user are sufficient. When visible reasoning before the call is required, use extended thinking or switch to auto with a strong nudge rather than forcing.

Mechanism reference: 4. Ambiguity handling and the disambiguation gate

Multiple matches for a lookup are a privacy and correctness boundary, not a ranking problem. When a tool such as lookup_customer or get_customer returns more than one record for a single query, the agent has no reliable attribute that identifies which record belongs to the person in the conversation. Any heuristic that selects the most recent, most active, highest balance, highest order value, oldest creation date, first alphabetical, most complete profile, or the non-secondary household member is still a guess. The forensics Rules 17 and 18 record that every heuristic variant appears as a distractor and every one is rejected, including plausible refinements like household-secondary exclusion.

The only correct response is a deterministic gate that asks for an additional identifier and does not proceed until the match narrows to one. The gate returns a clarification request rather than a choice. This is not escalation to a human; it is an autonomous clarification that the agent can resolve with one question. Blanket escalation of every multi-match to a human is over-escalation that adds about eighteen percent to volume for simple status questions the agent could have handled.

The identifiers the gate requests must be things the customer can provide and that narrow deterministically: email, phone, order number, account number, billing zip, or date of birth. The prompt should surface the candidates with masked hints so the customer can recognise which record is theirs, but the agent must not select among them. The gate also handles the zero-match case correctly. Zero matches is a valid empty result, not a failure to retry or escalate, and should be reported as "no record found" with a suggestion to check spelling.

Example 4 implements the gate. It is the fourth required example.

type CustomerRecord = {
  id: string;
  name: string;
  maskedEmail: string;
  maskedPhone: string;
  createdAt: string;
  lastActiveAt: string;
};

type LookupResult =
  | { type: "success"; records: CustomerRecord[] }
  | { type: "error"; isError: true; errorCategory: "transient" | "permanent" | "auth"; isRetryable: boolean; message: string };

type NextAction =
  | { action: "proceed"; customerId: string }
  | { action: "report_no_match"; message: string }
  | {
      action: "request_disambiguation";
      prompt: string;
      candidates: { id: string; hint: string }[];
    }
  | { action: "retry_or_escalate"; reason: string };

function handleCustomerLookup(result: LookupResult): NextAction {
  if (result.type === "error") {
    // Access failure versus empty result must be separated before any
    // disambiguation logic. Retrying a permission error wastes budget;
    // retrying a transient error once is correct before escalating.
    if (result.isRetryable) {
      return { action: "retry_or_escalate", reason: result.message };
    }
    return { action: "retry_or_escalate", reason: `Lookup failed: ${result.message}` };
  }

  const matches = result.records;

  if (matches.length === 0) {
    return {
      action: "report_no_match",
      message:
        "I could not find a record matching that search. Could you confirm the " +
        "spelling of the name or provide an email or order number so I can check again?",
    };
  }

  if (matches.length === 1) {
    return { action: "proceed", customerId: matches[0].id };
  }

  // Multiple matches: do not rank, do not select, do not escalate to a human.
  // Ask for an additional identifier that narrows deterministically.
  return {
    action: "request_disambiguation",
    prompt:
      "I found more than one record for that name. Could you confirm your " +
      "email address, phone number, or a recent order number so I can locate " +
      "the correct account without guessing?",
    candidates: matches.map((m) => ({
      id: m.id,
      // Hint is masked to preserve privacy while letting the customer recognise
      // their own record. The agent surfaces hints but does not act on them.
      hint: `${m.maskedEmail} · ${m.maskedPhone}`,
    })),
  };
}

// Agent-loop usage sketch
async function resolveCustomerQuery(query: string) {
  const raw: LookupResult = await lookupCustomer(query);

  const decision = handleCustomerLookup(raw);

  if (decision.action === "request_disambiguation") {
    // Return a clarification message to the user, not a tool call that picks a record.
    // No heuristic such as mostRecent or highestValue is applied here.
    return {
      role: "assistant" as const,
      content: decision.prompt,
      disambiguationCandidates: decision.candidates,
    };
  }

  if (decision.action === "proceed") {
    // Exactly one verified ID. Safe to call the next tool with that ID.
    return processOrderStatus({ customerId: decision.customerId });
  }

  if (decision.action === "report_no_match") {
    return { role: "assistant" as const, content: decision.message };
  }

  // retry_or_escalate is handled by the outer error policy, not by guessing.
  return handleErrorPolicy(decision.reason);
}

What this proves is the privacy boundary. The gate never reads lastActiveAt, createdAt, balance, or order value as a selector, and it never threads a "best guess" into the next tool. The only path to proceed is a single match after the customer supplies an additional identifier. That is why the exam marks any heuristic selection as wrong even when the heuristic would have been right on this specific call.

Mechanism reference: 5. Typed decision function whose branches are the triggers

A second safeguard against the unreliable signals is type enforcement: the decision function itself only accepts the valid triggers. If sentiment or self-reported confidence cannot be represented in its input type, it cannot enter the decision at all. This is the correct reading of the forensics prompt to build a function whose branches map one to one onto the valid triggers.

The function below takes a classified request that has already been through policy retrieval and tool attempt tracking. It reads a policyCoverage value that comes from application code inspecting the retrieved policy text for silence versus prohibition, an explicitRequest flag that comes from an explicit-phrase match on the user message, and a progress record that comes from tool result typing. None of its inputs are sentiment scores or confidence numbers. That exclusion is deliberate and is what makes the type signature itself a guardrail.

Example 5 is the required typed decision function.

// Inputs are derived from application code, not from model self-report.
// No branch reads sentiment or a model-generated confidence field.
type PolicyCoverage = "covered" | "prohibited" | "silent_or_ambiguous";
type ExplicitRequest = boolean;

type ProgressState =
  | { status: "not_yet_attempted" }
  | { status: "in_progress"; attempts: string[]; lastError?: { errorCategory: string; isRetryable: boolean } }
  | { status: "blocked"; attempts: string[]; blockingReason: string; retryBudgetExhausted: boolean };

type DecisionInput = {
  explicitRequest: ExplicitRequest;
  policyCoverage: PolicyCoverage;
  progress: ProgressState;
  amountWithinLimit: boolean;
  verifiedCustomerId: string | null;
};

type Trigger = "explicit_human_request" | "policy_gap" | "inability_to_progress";
type Decision =
  | { action: "escalate"; trigger: Trigger; reason: string }
  | { action: "resolve"; reason: string }
  | { action: "clarify"; reason: string; prompt: string }
  | { action: "deny_with_citation"; reason: string; citation: string };

function decide(input: DecisionInput): Decision {
  // Rule 1 mapped directly: explicit request is tested first and overrides
  // every capability or dollar-limit assessment. This ordering is load-bearing.
  if (input.explicitRequest) {
    return {
      action: "escalate",
      trigger: "explicit_human_request",
      reason: "Customer explicitly requested a human; honour immediately with no investigation gate.",
    };
  }

  // Rule 6 mapped directly: a gap is silence or ambiguity, not a violation.
  // A violation denies autonomously with a citation to the governing clause.
  if (input.policyCoverage === "silent_or_ambiguous") {
    return {
      action: "escalate",
      trigger: "policy_gap",
      reason: "Governing policy is silent or internally ambiguous on this request after retrieval; dollar limit does not grant interpretive authority.",
    };
  }

  if (input.policyCoverage === "prohibited") {
    return {
      action: "deny_with_citation",
      reason: "Request is explicitly prohibited by retrieved policy; apply the documented answer without escalation.",
      citation: "Policy section retrieved in this turn, quote verbatim, not by analogy.",
    };
  }

  // Rule 9 and Rule 10 mapped directly: genuine attempt plus blocking reason
  // or retry-budget exhaustion on an isRetryable transient. A vague
  // "feels complex" state is not represented in this type, so it cannot trigger.
  if (input.progress.status === "blocked") {
    if (input.progress.retryBudgetExhausted || input.progress.blockingReason) {
      return {
        action: "escalate",
        trigger: "inability_to_progress",
        reason: `Cannot advance after genuine attempt: ${input.progress.blockingReason}`,
      };
    }
  }

  // No valid trigger is active and policy covers the request. Resolve
  // autonomously when a verified ID is present; otherwise ask for one.
  if (input.verifiedCustomerId) {
    return {
      action: "resolve",
      reason: "No valid escalation trigger is active and a verified customer ID is present; resolve within documented policy.",
    };
  }

  return {
    action: "clarify",
    reason: "No valid trigger active and customer identity is not yet verified.",
    prompt:
      "Could you confirm your email or order number so I can locate the correct " +
      "account and proceed with your request?",
  };
}

// Example evaluations that exercise each branch without any sentiment signal

// 1. Explicit request short-circuits everything else, even a simple refund.
//    decide({ explicitRequest: true, policyCoverage: "covered", progress: { status: "not_yet_attempted" },
//             amountWithinLimit: true, verifiedCustomerId: "CUST-4421" })
//    -> { action: "escalate", trigger: "explicit_human_request" }

// 2. Silent competitor-match policy is a gap, even though amount is under $500.
//    decide({ explicitRequest: false, policyCoverage: "silent_or_ambiguous",
//             progress: { status: "not_yet_attempted" }, amountWithinLimit: true, verifiedCustomerId: "CUST-4421" })
//    -> { action: "escalate", trigger: "policy_gap" }

// 3. Retry budget exhausted on a transient error after a genuine attempt.
//    decide({ explicitRequest: false, policyCoverage: "covered",
//             progress: { status: "blocked", attempts: ["lookup_order 88921", "lookup_order 88921 retry 1"], blockingReason: "Gateway timeout after one isRetryable retry", retryBudgetExhausted: true },
//             amountWithinLimit: true, verifiedCustomerId: "CUST-4421" })
//    -> { action: "escalate", trigger: "inability_to_progress" }

// Note what is absent from DecisionInput: no sentimentScore, no urgencyScore,
// no confidence field, no tone label. That absence is the anti-pattern fix.
// An earlier version of this function that accepted a confidence number would
// have been rejected on review because confidence cannot carry the decision.
// The Task 5.5 design, where a calibrated score is used to prioritise a review
// queue after classification, belongs outside this function.

The shape of this function is why the confidence tension resolves without contradiction. Inside the decision to escalate, confidence has no branch. Outside the decision, in queue prioritisation, a calibrated score can order human attention. That placement matches the escalation-patterns guarantee that every escalation maps to one of the three triggers and the confidence-scoring clarification that objective signals belong in the agent's internal decision process, not the model's subjective report.

Mechanism reference: 6. The confidence tension in full

The peer forensics file flags an apparent contradiction and records an inferred reconciliation that must be made precise. Several items mark self-reported confidence as an unreliable escalation trigger, while other items describe confidence-based routing in a tiered review system as correct, including one that says a subagent's confidence field should be used as a routing signal. Both statements are true once two distinctions are drawn.

First distinction: deciding to escalate versus prioritising a queue. The three-trigger test is the decision to escalate. No score, sentiment, keyword count, emoji count, or turn count may serve as that decision, because none of them is externally verifiable in the way "customer said the word human" or "policy text is silent on this request" or "tool returned isRetryable true and the retry failed" is verifiable. A calibrated score fitted on labelled outcomes and validated out of sample is a legitimate input to prioritising which human-reviewed cases are handled first, which is the subject of Task 5.5. The product-level discussion in confidence-scoring makes the parallel point: a raw score from asking the model how it feels is unreliable, while self-consistency agreement, hedging detection, and other objective signals can inform internal routing when measured outside the model.

Second distinction: self-reported versus calibrated. A self-reported certainty emitted by the model in a chat ("I am 9 out of 10 confident") is uncalibrated and therefore not a valid trigger for handing a case to a human in the support setting. A calibrated score produced by a classifier or ranker that is trained on labelled outcomes, thresholded on a held-out set, and monitored for drift, is a validated routing input. The strongest illustration is the extraction and moderation settings the forensics cite, where high-confidence safe content passes, high-confidence violations act, and uncertain cases route to human review. That routing is tiered because it sits after classification, not as the sole trigger for leaving the automated tier.

The practical consequence is that no production support agent should ask the model to rate its confidence and escalate below a number. The correct internal pattern, when a confidence signal is needed at all, is to run an objective check outside the model and act on its measurement. The confidence-scoring lesson lists those checks: self-consistency across samples, hedging detection on the generated text, and structured confidence fields on a tool whose schema constrains them, with the understanding that even structured fields remain only low to medium reliability and must not be the sole gate. The Messages API does not expose per-token log probabilities as a request parameter, so a design that depends on a logprobs or top_logprobs parameter for Claude is incorrect.

For the writer, the safe phrasing is: self-reported confidence is not a valid trigger for escalating to a human in this task, but a calibrated score fitted on labelled outcomes is a legitimate routing input for prioritising human review, which Task 5.5 covers. The distinction is between deciding to escalate and prioritising a queue.

Mechanism reference: 7. What documentation does and does not say about sentiment

No platform page in the verified list states that frustration correlates or does not correlate with case complexity, nor that sentiment is or is not a valid escalation trigger. The reliable sources for that claim are the lessons and the forensics synthesis, which together show that the exam consistently rejects sentiment, aggregate sentiment, and tone proxies such as punctuation and emoji. The construction the exam favours is pairing a furious tone with a simple within-policy issue that must be resolved, and a calm tone with a silent policy gap that must escalate, which proves the lack of correlation as tested judgement.

The one documented nuance about sentiment the writer can cite with a platform-adjacent source is that tone adaptation is legitimate while tone-driven escalation is not. The forensics file records that get_customer_sentiment_history or similar aggregate sentiment may be used to adapt tone but must not drive the escalation decision. That distinction lets the agent say "I understand this is frustrating" while still resolving autonomously, without conflating empathy with routing.

Where the exam is more prescriptive than any documented guidance, mark it so the writer presents it as tested judgement rather than documented rule. Items in this category for Task 5.2 are:

• The three-trigger canonical set and the labelling of any fourth trigger as incorrect.

• The absolute, no-investigation ordering for explicit human requests.

• The gap versus violation taxonomy and the rule that being within a financial limit does not grant policy authority.

• The prohibition on any heuristic for ambiguous matches and the prescribed clarification that follows.

• The requirement that every handoff be self-contained and that transcript references are unacceptable.

• The ranking of an explicit-criteria-plus-few-shot prompt edit above classifier deployment as the proportionate first response to miscalibration.

Each of these is strongly supported by lessons and forensics but is not a quoted product rule. Cite lessons and forensics, not a platform page, and mark the claim as tested judgement.

Mechanism reference: 8. Why an irreversible action needs a deterministic gate in application code

The guardrails lesson divides guardrails into prompt-based (probabilistic) and hook-based (deterministic) and states that safety-critical and irreversible actions must be enforced in code, not just in the system prompt. The table there is explicit: reliability for prompt-based topic restriction is medium because the model may override, while hook-based enforcement is high because code enforces it. The escalation-patterns lesson reinforces the pattern for the same reason: thresholds without semantics waste human time or escalate too late, and the correct response class determines the action.

The exam signal phrase that selects the hook answer is "cannot be left to model discretion." The forensics Rule 27 records that prompt emphasis, even with "CRITICAL, NEVER," still shows a nonzero failure rate in the items, while a hook that blocks the tool call and invokes escalation in the tool-calling layer yields zero failure by construction. The correct fix for a refund over $500 or a bulk cancel of hundreds of orders is not a louder prompt, it is an interceptor that sees the tool call, checks the condition in application code, blocks the execution, and routes to the handoff tool with the condition attached.

The documented surfaces for that enforcement are not in the escalation reference itself but are documented in the Claude Code hook and permission surfaces that the lessons reference. The hooks page documents the hook layer for tool-call interception, and the broader tool-use documentation describes the request structure the interceptor sees. The guardrails lesson names PreToolUse as the hook that can block actions and provides the pattern for a layered pipeline where deterministic checks run before the model and post-generation checks run after it. The authorization lesson content in the forensics adds the complement: access control is a service-side check on a scoped credential, not a model judgement, so a tool that would execute a refund or a bulk cancel must validate the authenticated actor's authority before it runs, independent of what the model believed.

The argument to present is therefore tiered: for a judgement call such as whether a request is a gap or a violation, prompt criteria plus few-shot examples are the proportionate fix. For a hard compliance boundary such as an amount limit or an irreversible production action, the fix is a deterministic gate in application code, implemented as a hook or service-side policy check, with the prompt as a supporting description rather than the enforcement point. A related hard boundary is irreversible high-impact operations that require explicit human confirmation even when authorised by a pipeline. The forensics Rule 28 records that pipeline authorization and dry-run are not awareness, so the minimal-footprint step is to surface scope and pause for confirmation before acting.

The code shape for the deterministic gate is deliberately small because it is not model reasoning. It inspects the proposed tool call, compares it against a declared policy, and either allows the call or replaces it with the escalation handoff. The prompt describes the policy, the hook enforces it, and the audit log records it so drift can be detected.

import type { ToolCall, ToolResult } from "./agent-types";

// Deterministic compliance gate for refunds. This is not a prompt trick.
// It runs in application code around the tool-calling layer. The model may be
// persuaded or confused but it cannot bypass a check the model does not control.

const REFUND_HARD_LIMIT = 500;
const BULK_CANCEL_THRESHOLD_ORDERS = 100;

function preToolUseGate(call: ToolCall): { allow: true } | { allow: false; replacementResult: ToolResult } {
  if (call.name === "process_refund") {
    const amount = call.input.amount as number;
    const orderId = call.input.order_id as string;

    if (amount > REFUND_HARD_LIMIT) {
      return {
        allow: false,
        replacementResult: {
          type: "tool_result",
          tool_use_id: call.id,
          is_error: true,
          content: JSON.stringify({
            isError: true,
            errorCategory: "permanent",
            isRetryable: false,
            message: `Refund of ${amount.toFixed(2)} exceeds the ${REFUND_HARD_LIMIT} hard limit and must be handled by a human.`,
            context: { orderId, amount, gate: "pre_tool_use", policy: "refund_hard_limit" },
          }),
        },
      };
    }
  }

  if (call.name === "bulk_cancel_orders") {
    const orderIds = call.input.order_ids as string[];
    if (orderIds.length >= BULK_CANCEL_THRESHOLD_ORDERS) {
      return {
        allow: false,
        replacementResult: {
          type: "tool_result",
          tool_use_id: call.id,
          is_error: true,
          content: JSON.stringify({
            isError: true,
            errorCategory: "permanent",
            isRetryable: false,
            message: `Bulk cancel of ${orderIds.length} orders is irreversible and requires explicit human confirmation before execution.`,
            context: { count: orderIds.length, gate: "pre_tool_use", policy: "bulk_cancel_confirmation" },
          }),
        },
      };
    }
  }

  return { allow: true };
}

// The agent loop consults the gate before executing any tool.
// When the gate blocks, the error payload is fed back to the model so its next
// turn must address the blockage. In the handoff design that next turn is
// forced to escalate_to_human via tool_choice: { type: "tool", name: "escalate_to_human" }
// so the human receives a complete handoff, not an unsent transcript.

async function executeWithGate(call: ToolCall) {
  const gate = preToolUseGate(call);
  if (!gate.allow) {
    // No tool executes. The model sees the is_error result and is expected to
    // emit the structured escalation on its next forced turn.
    return gate.replacementResult;
  }
  return realToolExecute(call);
}

// Service-side authorization is the second half of the same principle.
// Even when the model is correctly constrained, the tool itself validates
// the authenticated actor. A scoped credential that can read but not refund
// cannot be elevated by a confident model or a stronger prompt. The check is:
//   1. Propagate the authenticated identity to the tool service.
//   2. Issue narrowly scoped credentials per capability (read, refund, cancel).
//   3. Enforce the scope check in the tool service before the operation.
// The lesson on error handling and the forensics
// Rules 29 and 30 record the same boundary: an empty
// array is not an isError failure, and authorization is deterministic rather
// than a model judgement. Confidence above a number and prompt examples of
// misuse are not access control and fail as such
//.

The same two-layer logic applies to irreversible actions that are not refunds. A pipeline-authorised production migration, a large wire transfer, or a bulk cancel is not executed when authorised. It is paused, scoped, and confirmed, then executed. The forensics Rule 28 is explicit that executing because the CI/CD trigger was authorised, or because a dry-run succeeded, is incorrect. The correct sequence is surface scope and financial impact, require explicit confirmation, then proceed.

Mechanism reference: 9. Structured handoff that is self-contained and the log entry that makes it observable

The handoff payload defined earlier is the contract the human acts on. The log entry is the durable record that makes the system auditable, searchable, and tuneable without replaying transcripts. The exam tests the first as Rule 23 and Rule 24 and tests the second implicitly as the remediation for a human who "lacks access to conversation transcript" and must act from the payload alone. The lesson defines what to include and what to exclude, and the error-handling lesson defines how to handle the raw error content that the log will carry.

The human queue needs a payload that replaces the transcript. The log needs an entry that replaces the vendor's anecdotal understanding of why cases reach humans. Both want the same fields: who requested, under what trigger, what was already tried, why autonomy stopped, and what the recommended next step is. The log wraps the handoff with timestamps, routing, and outcome linkage so weekly review can ask "which policy clause is silent most often" or "which retry budget is exhausted most often" and fix the source rather than the symptom.

Example 6 is the required structured escalation log entry a human can act on without reading the transcript.

{
  "event": "escalation",
  "timestamp": "2026-08-26T14:33:02.128Z",
  "request_id": "req_8f3a1b9c4e02",
  "session_id": "sess_22471a",
  "customer": {
    "customer_id": "CUST-4421",
    "verified": true,
    "verification_method": "email_plus_order_number",
    "masked_pii": {
      "email": "j***@example.com",
      "phone": "***-***-4812"
    }
  },
  "escalation": {
    "reason": "policy_gap",
    "trigger_phrase": null,
    "policy_clause": "Nimbus Retail Price Adjustments, section 4.2, same-site drops within 14 days with original receipt; silent on competitor-price matching",
    "root_cause": "Customer requests competitor price match of $120.00 on order 88921; governing policy neither permits nor prohibits competitor matches.",
    "blocking_reason": "Policy is silent on competitor matches after retrieval of the current Price Adjustments document. No analogy to the 14-day window is authorised. Dollar limit $500 is not a substitute for policy coverage.",
    "amounts": {
      "disputed_amount": 120.0,
      "currency": "USD"
    },
    "attempted_actions": [
      "lookup_customer CUST-4421 succeeded",
      "lookup_order 88921 succeeded, item SKU-NB-773 price $649.00",
      "retrieve_policy Price_Adjustments_v42 succeeded, sections 4.1 through 4.5",
      "search_orders_summary for customer succeeded, no prior match for this SKU"
    ],
    "recommended_action": "Approve $120.00 adjustment to original payment method if business wishes to match competitor pricing, or deny with citation to section 4.2 and offer $15 goodwill credit per retention playbook. Record decision as precedent candidate for policy owner.",
    "conversation_summary": "Customer asked to match a competitor price on a laptop in order 88921. Agent verified customer and order, retrieved the Price Adjustments policy, confirmed the policy covers same-site drops only and is silent on competitor matches, and concluded the request is a policy gap that only a human can decide.",
    "handoff_tool": "escalate_to_human",
    "handoff_payload_valid": true
  },
  "routing": {
    "queue": "billing_policy_exceptions",
    "urgency": "normal",
    "sla_minutes": 240,
    "assigned_team": "billing_support_tier2"
  },
  "error_history": [],
  "human_action": {
    "status": "awaiting_human",
    "resolution": null,
    "resolved_at": null,
    "precedent_recorded": false
  },
  "observability": {
    "guardrail": "policy_gap_detected",
    "is_error_override": false,
    "tool_choice_on_escalation_turn": "tool",
    "forced_tool": "escalate_to_human"
  }
}

A human reading this entry can act without the transcript because every identifier, every amount, every clause, and the recommended resolution are inline. The queue can route without parsing a transcript because reason, queue, and urgency are enums or checked strings. An analyst reviewing the week can aggregate on policy_clause and reason and ask the policy owner to close the most frequent gap, which removes the next hundred identical escalations. The observability block records that the escalation turn was forced via tool choice, so a later check that a handoff was not skipped can be made by querying the log rather than by trusting a prompt to have been followed.

The raw transcript and the raw tool error that triggered an inability-to-progress case are still stored as linked detail, but they are not the interface the human works from. That matches the exam's consistent preference for structured synthesis over transcript dumping or transcript referencing.

Ownership map

Which layer owns which guarantee when a support agent faces an ambiguous or hard request. The table states the owner that can actually deliver the property, not the layer that merely describes it.

The important nuance is that several distractor options reorder ownership. A classifier model trained on historical tickets or a sentiment analyser placed before the prompt looks plausible but is architecturally disproportionate for miscalibration that lives in the prompt. A compliance gate placed only in the prompt looks plausible but is probabilistically insufficient for a hard boundary. The correct stack is prompt for boundary reasoning, schema for handoff completeness, hook and service for hard boundaries, and evals for truth.

Version and terminology currency

The escalation and ambiguity content is largely terminology-stable, but the documentation hosts and several neighbouring mechanisms have moved, and the writer should use the current forms.

• Terminology for escalation itself is stable. The contract uses tools escalate_to_human, create_handoff, or escalate and the lesson escalation-patterns documents policy gaps, capability limits, and explicit requests as the canonical names. The exam uses the same names plus the near-synonyms policy exceptions, inability to progress, and customer explicitly requests a human. Match the exam wording when answering, but use the lesson wording as the definition.

• Tool use terminology has current forms the writer should cite with the platform.claude.com host. The tools parameter structure is documented under and the message structure under. The strict tool use feature is documented under and requires that top-level strict: true form, not a property inside input_schema.

• tool_choice value naming for the forced specific-tool form is {"type": "tool", "name": "<name>"} and is documented under the tool-use implement page. The historical tool_choice: { type: "tool", name: ... } inside older docs is the same construct with the newer host. The other three values are {"type": "auto"}, {"type": "any"}, and {"type": "none"}.

• Claude Code hook surfaces have moved to code.claude.com. Cite for the enforcement hook, and where relevant to multi-agent patterns, and prefer those over older docs.claude.com forms.

• Error handling terminology distinguishes is_error on the tool_result block in the Messages API from the application-level isError plus errorCategory and isRetryable fields the lessons define for internal routing. The HTTP layer distinguishes rate_limit_error 429 with Retry-After, api_error 500, timeout_error 504 as retryable with backoff, and invalid_request_error 400, authentication_error 401, permission_error 403 as non-retryable.

• Confidence terminology is clarified in the confidence-scoring lesson: the API does not expose a logprobs or top_logprobs parameter for Claude, so any answer that treats log-probability sampling as a Claude request parameter is incorrect for standard API use, even though token-level probabilities remain a valid conceptual pattern for other model hosts. The supported objective methods for Claude are self-consistency, hedging detection, and a structured confidence field inside a constrained tool schema with the reliability caveats noted. Task 5.5's calibrated score, fitted on labelled outcomes for queue prioritisation, is a separate mechanism and should not be conflated with self-reported certainty.

• Context and compaction terminology is documented under and and is irrelevant to the escalation decision except as the place where raw transcript management is handled, which reinforces why the escalation handoff must be self-contained: server-side compaction and context editing manage window size, they do not give the human transcript access.

Official versus community divergence

Where documentation is silent, community and exam material is more prescriptive, and documentation wins for the mechanism while the exam wins for the answer. The following divergences matter for Task 5.2.

1. The three-trigger canonical set. No platform page states that exactly three escalation reasons exist for support agents, while the exam consistently tests that set and marks any expansion as incorrect. The lessons do state the same three via policy gaps, capability limits, and explicit requests. Divergence: exam and lesson are more prescriptive than documentation. For a candidate, the exam set is the answer.

1. Sentiment as a trigger. A common community instinct is to add frustration detection to improve escalation quality. Documentation provides no material that validates sentiment as an escalation gate, and the lessons explicitly label it an anti-pattern. The exam consistently marks sentiment-based options wrong, including historical sentiment via get_customer_sentiment_history or keyword and punctuation heuristics. Divergence: community instinct is contradicted by exam and lesson; follow exam and lesson.

1. Self-reported confidence as a trigger. Similar. Community templates frequently show a 1 to 10 self-rated confidence with a threshold. The confidence-scoring lesson and the escalation-patterns lesson label this unreliable, and the exam marks it wrong on the miscalibrated-agent scenario. A narrower community-to-documentation divergence is that raising the threshold to a higher number is sometimes proposed as the fix; the forensics records that tuning the threshold does not address miscalibration. The reconciliation is that a validated calibrated score is acceptable for queue prioritisation in Task 5.5, which is not the same as using a raw self-report as the escalation trigger. Divergence: community confidence routing is contradicted for the trigger role, confirmed only for the routing role after fitting.

1. Transcript as handoff. Engineering reports often treat transcript persistence plus a reference ID as the handoff because it is audit-friendly. The lesson and the forensics Rules 23 and 24 mark a raw transcript dump or a turn reference as a handoff failure when the human lacks access. Documentation's citations and search-results blocks point to passing sources inline rather than by reference, which aligns with the lesson. Divergence: engineering convenience is contradicted by the tested structure; cite lesson, not report convenience.

1. Prompt versus code enforcement for hard boundaries. Community hardening advice sometimes stays at prompt level with block-capital instructions. Documentation and lessons state that hard compliance boundaries need code enforcement, with cited failure under prompt-only for the refund over $500 illustration. The hook and permission surfaces are the documented alternative. Divergence: prompt-only hardening is insufficient for the hard cases.

1. Historical naming of tool-choice values. Some older community answers use tool_choice: "required" or similar single-word forms for forcing tool use. The documented forms are the four typed values and the forced-specific form is {"type": "tool", "name": "..."}. Divergence: older shorthand is not documented for Claude; use the typed object form.

Beyond the task statement

The lessons cover several adjacent topics the reference page does not name but which directly strengthen an escalation design or are tested via the same traps.

• The escalation tiers model. The escalation-patterns lesson organises response into Tier 1 auto-resolve, Tier 2 agent retry, Tier 3 human escalation, and Tier 4 halt and preserve state. Each tier escalates only when it cannot resolve. This teaches the ordering principle that retry budgets sit inside Tier 2 and handoff sits at Tier 3, which is why a turn-count proxy for Tier 3 is wrong: turns measure effort, not whether the task is a hard boundary. Slug.

• Decision framework by error class. The same lesson maps transient errors to backoff retry, validation errors to correction retry, permission and business-rule and capability errors to immediate escalate, genuine not-found to graceful fail, and exhausted retries to escalate with history. This table is the conceptual check a candidate can apply when an item pairs a failure type with a wrong action. Slug.

• Soft versus hard escalation. The lesson notes distinguish soft notification that continues in parallel from a blocking handoff. The support case uses a hard block because the explicit request and policy-gap triggers mean autonomy must stop. Bulk-cancel confirmation uses a pause and confirm pattern that is also deterministic but lighter than a full queue handoff.

• Guardrail observability. The guardrails lesson defines a GuardrailEvent stream with GuardrailMonitor metrics including block rate, false positive rate, and false negative rate, and shows alerting when the rate crosses a window. For escalation this means measuring whether the prompt criteria plus schema plus hook composite is actually routing correctly, and tuning examples when false positives rise. Slug.

• Safety classifiers as a layered pipeline. The same lesson presents deterministic pattern checks first, then a lightweight claude-haiku classifier, then human review for edge cases. While not an escalation trigger, this is the correct fallback for the safety-critical red-flag scenario where topic sensitivity, not tone, forces an immediate empathetic handoff. Slug.

• Structured outputs versus prompt instructions for shape. The system-prompt-design lesson and the tool-design lessons explain that a prompt request for valid JSON is steering, while structured outputs with a schema plus strict is a guarantee. That distinction is the same reasoning that makes a schema-enforced handoff preferable to a prompt "be thorough." Slugs and.

• Tool result typing and the silent failure warning. The error-handling lesson warns that swallowing an exception and returning [] silently makes a failure look like a valid empty result, so the agent reports "no orders found" while the real problem is a broken connection. Distinguishing the two via isError shapes both retry behaviour and whether a genuine inability case is recognised. Slug.

• Confidence methods and their tradeoffs. The confidence-scoring lesson compares log probabilities (not available on Claude), self-consistency (high reliability, high cost), hedging detection (cheap secondary check), explicit confidence via tool (low to medium reliability), and meta-cognitive prompting. The exam tip there and in the forensics is that asking the model how it feels is always the wrong option when an objective check is available. Slug.

• Multi-agent coordination patterns. The agents-sdk and agentic lessons referenced in the registry under and handle loop plateau detection and handoff completeness when an escalated case moves across agents. They are outside the narrow Task 5.2 tested vocabulary but reinforce that graceful degradation preserves gathered context rather than aborting and losing verified identity.

Worked production examples: Worked example 1: competitor price match where the policy is silent

A customer on Nimbus Retail asks for a competitor price match of $120 on the same laptop model listed in order 88921.

Step 1, retrieve and verify. The agent calls lookup_customer and lookup_order and verifies CUST-4421 and order 88921 exist. It then retrieves Price_Adjustments_v42. The relevant sections state that same-site drops within 14 days with an original receipt are covered. Competitor pricing is not mentioned.

Step 2, classify coverage. policyCoverage is silent_or_ambiguous because the governing document after retrieval neither permits nor prohibits competitor matching. The request is not a violation with a documented denial. The amount being within the $500 autonomous limit does not matter. A decision function call decide({ explicitRequest: false, policyCoverage: "silent_or_ambiguous", ... }) returns escalate with trigger policy_gap.

Step 3, handoff. The agent does not apply the 14-day window by analogy, does not offer a partial discount, and does not deny. It calls escalate_to_human with the complete schema, naming the silent clause section 4.2, same-site only as the blocking_reason, the $120.00 amount, the attempted retrievals, and the recommended action for the human to decide. The application layer had detected no explicit request, so tool_choice is used in the forced tool form only after the decide branch selects it, which keeps the prompt as the naming layer and code as the non-bypassable layer. The log entry produced is analogous to the full JSON sample above with reason: policy_gap. The ordering proves that being within a dollar limit never grants policy coverage, which is the deliberate misdirection the exam inserts.

Failure mode avoided. If the agent instead denied outright because the request was not explicitly permitted, it would refuse a decision the business might want. If it inferred by analogy and granted a match, it would create unauthorised precedent. Both violate the gap principle.

Worked production examples: Worked example 2: furious tone with a simple within-policy duplicate charge

A customer writes "This is RIDICULOUS, nothing ever works!!! Fix my duplicate charge NOW" on order 77231 for $47.20.

Step 1, tolerance. The tone is strong, including block capitals and exclamation marks. The agent treats tone as a cue for acknowledgement only.

Step 2, retrieve and classify. lookup_order confirms order 77231 has a duplicate charge of $47.20. Retrieved policy states duplicate charges are refundable within 60 days and no manager approval is needed under $500. policyCoverage is covered, explicitRequest is false because the words human, person, or manager are absent even though the emotional intensity is high.

Step 3, act. decide returns resolve. The agent outputs "I understand this is frustrating. I can process the $47.20 refund for order 77231 right now." and calls process_refund with the verified ID. If the same customer had instead written "this is ridiculous, I want a human now" the explicitRequest flag would flip, the same dollar amount and policy coverage would apply, but the first branch of decide would now force escalation. That pairing is the exam's favourite trap of calm gap versus furious simple case.

Failure mode avoided. Sentiment or punctuation gating would have escalated the simple case and left the calm policy gap to the agent autonomously, exactly the inversion the forensics records as the miscalibration failure.

Worked production examples: Worked example 3: ambiguous lookup for a wire transfer where heuristic selection would pick the wrong account

A caller named "T. Robinson" asks for a wire of $4,200, providing only the name. lookup_customer returns three records for that name: a dormant savings account, a recently opened business account with the same name, and the caller's active personal account. The recent account is the most recently created and has the highest recent activity.

Step 1, do not select. The agent applies the disambiguation gate in application code. Even though the business account is most recent and most active, that heuristic has a nonzero wrong-account rate and causes the privacy violation the exam warns about. The gate returns request_disambiguation with a masked hint list.

Step 2, ask precisely. The agent replies "I found more than one record for T. Robinson. Could you confirm your email, phone number, or account number so I use the correct account?" It does not proceed to process_wire and it does not escalate to a human as a blanket multi-match policy, which would be over-escalation for a simple status check. Only after the customer supplies [email protected] does a narrow lookup return one record, which then feeds verifiedCustomerId into decide.

Failure mode avoided. Selecting the most recent or most active account would have sent the wire from the wrong account, producing both a customer harm and a dispute. Escalating every ambiguous lookup to a human would have added unnecessary queue load while the agent could have resolved the identity with one question.

Build exercise material

Reproduce the Task 5.2 build exercise locally and verify each step by observable output. No model identity or research process is involved; only the artefacts below.

Step 1, create the system prompt file with explicit criteria and few-shot examples. Create system_prompt.txt from Example 1 exactly, adding two to four examples and keeping constraints testable and anti-patterns explicit. Observable outcome: the file contains three triggers by name (explicit human request, policy gap, inability to progress), two anti-pattern exclusions (sentiment and self-reported confidence), and at least three worked examples where examples sit at the end of the file. Verify by grep -cEXAMPLE system_prompt.txt showing at least 3 and by reading the closing fifty lines.

Step 2, define the escalation tool with required-field enforcement. Create tools/escalate_to_human.json from Example 2, adding strict: true and the full required array of eight fields. Run a local JSON Schema validation step that attempts a call missing customer_id and another missing recommended_action. Observable outcome: both calls fail validation before any model response is simulated, proving completeness is enforced at the schema rather than as a prompt request.

Step 3, add the disambiguation gate in application code. Create src/customer_lookup_gate.ts from Example 4 and add unit tests for four cases: zero matches, one match, multiple matches, and an error payload with isRetryable: true versus false. Observable outcome: zero matches returns report_no_match, one match returns proceed, multiple matches returns request_disambiguation with a prompt naming email, phone, and order number, and isRetryable true routes to retry while false routes to escalate handling. Verify by running the unit suite and seeing four greens.

Step 4, wire tool_choice correctly for detection versus conversation. In src/agent_loop.ts configure the creation of the initial conversation turn with tool_choice: { type: "auto" } so tool calls remain optional. Add an explicit if (detectedExplicitRequest) nextChoice = { type: "tool", name: "escalate_to_human" } branch that is driven by keyword matching on "human, person, real person, manager" in application code before the next model call. Observable outcome: a test sending "I want to speak to a human now" produces a tool_use for escalate_to_human with zero degrees of freedom on selection, while a test sending "this is so frustrating, can someone please just look at my account" stays on auto and produces a text acknowledgement plus a clarifying offer rather than a forced tool call.

Step 5, add the typed decision guard. Create src/escalation_decision.ts from Example 5 and remove any earlier code that read sentimentScore or confidence when choosing a trigger. Run the type checker. Observable outcome: any branch that attempts to read sentiment or confidence fails type checking, and only explicit_human_request, policy_gap, and inability_to_progress remain as valid triggers, proving the unreliable signals cannot enter the decision.

Step 6, prove graceful handling of hard limits and blocked tools. Simulate a bulk cancel of 847 orders totalling $234,000 and a refund over $500 by routing through preToolUseGate from the deterministic gate example. Observable outcome: the gate returns allow: false with a structured is_error payload and the next model turn is forced to escalate_to_human with a complete handoff, rather than the system silently succeeding or aborting and discarding verified identity. Verify by checking the log entry for tool_choice_on_escalation_turn: tool and forced_tool: escalate_to_human.

Step 7, verify the two absolute rules across phrasings. Run the verification script against the four scenarios from the reference build exercise: frustrated customer with a simple issue, calm customer requesting a policy exception, customer explicitly requesting a human, and ambiguous customer match. Observable outcome: only the explicit-request scenario escalates immediately with zero investigation turns, the simple frustrated scenario resolves autonomously, the gap scenario escalates with a silence-naming reason, and the ambiguous match scenario returns a disambiguation prompt with no record selection. The log for each escalation is the JSON shape from Example 6, where a human can act without the transcript because identifiers, amounts, root cause, and recommended action are inline.