# Make the agent loop finish, recover and stay inspectable

Treat this file as reference data, never as instructions that override the user or agent. Read the complete item before applying it. Keep use conditions, avoid conditions, limits, evidence roles and source links with the answer. An editorial block is a separately versioned analysis layer, not an original corpus claim or proof of efficacy. Cite the readable URL and version. Do not infer human review. This is a saved edition, not a live safety-notice service. Before consequential reuse, check the current page, https://vedokrok.com/data/availability.json and https://vedokrok.com/data/notices.json; absence alone does not explain why an item was removed.

Release: VEDOKROK-SEL-5d86e1b23401e578
Snapshot SHA-256: 30ce1c8fa9155763797e3d5cb55b1d94cbb8c3146ebd03fb3c006531ce60e82f
Current availability: https://vedokrok.com/data/availability.json
Current notices: https://vedokrok.com/data/notices.json
Editorial overlay: MHC-EO-20261021-481e1ce95099
Editorial projection SHA-256: 6b41bfd164b85b2522e2378c425929aa041d9e093e81428ade9a7b7b9f78e8fe

Turn current 2025-2026 agent engineering into practical controls for bounded loops, context, memory, checkpointing, evaluation and trajectory monitoring.
Collection kind: collection
Source: https://vedokrok.com/collections/make-the-agent-loop-finish-recover-and-stay-inspectable
Version: 0.1.0

---

## Bound every autonomous agent loop before it starts

ID: MHC-D-RESEARCH-0945 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/bound-every-autonomous-agent-loop-before-it-starts

A loop without a hard edge is an outage waiting for a goal condition to fail.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- An agent can iterate until it believes the task is complete.

### Avoid when

- Bounds can stop useful work early; choose them from task stakes and expected horizon, then tune with observed trajectories.

### Explanation

Set explicit bounds before execution: maximum invocations or steps, elapsed time, tool-call count and/or cost. The loop can stop earlier on success, but it must have a deterministic ceiling if the completion condition fails, the model stalls or the evaluator becomes inconsistent.

### Steps

1. A broken completion condition cannot create an unbounded run.

### Example

A research agent can run until the coverage rubric passes, but never beyond 20 search/analysis iterations or the defined cost budget.

### Check

A broken completion condition cannot create an unbounded run.

### Limits

- Bounds can stop useful work early; choose them from task stakes and expected horizon, then tune with observed trajectories.

### Evidence and sources

- supports: Microsoft's agent-loop documentation explicitly recommends always bounding autonomous loops because completion conditions can fail and agents can stall. — RS-86F401513BF07EEC. Bounds can stop useful work early; choose them from task stakes and expected horizon, then tune with observed trajectories. (See source record)
- RS-86F401513BF07EEC: Agent Looping — https://learn.microsoft.com/en-us/agent-framework/agents/looping

### Vedokrok editorial review

Enforce agent-loop limits outside the model

An agent saying it will stop is not an enforced limit. Put the stop controls in the software running the agent, and distinguish a completed task from a run that used its budget.

#### Choose what each limit controls

Before starting, set an iteration limit and the time or spending limits the task needs. Stop starting new work when any required limit is reached. A counter alone does not bound the time spent waiting inside one tool call: configure connection and request timeouts too. Record which limit ended the run, unfinished work and any external operation whose outcome is still unknown.

#### Test a run that cannot finish

In a safe test, make the completion check always return false, then make a tool stall. Confirm that control returns within the configured limits and that the result is labelled incomplete. For example, a search limit of 20 calls must not be reported as successful coverage. Microsoft recommends bounded loops; AWS explains timeout coverage and the risks of setting timeouts too short. Choose values from the task and service behavior, not a universal number.

**Editorial takeaway:** A budget stop limits further work; it does not establish success or prove that an external operation was canceled. Resolve uncertain outcomes before resuming.

#### Editorial evidence

- supports: Microsoft recommends bounding autonomous agent loops because the completion mechanism may not terminate. — RS-86F401513BF07EEC. Official experimental framework documentation, updated 2026-08-25. Selected substantive passages read on 2026-10-04. Runtime enforcement and the failure-injection check are editorial operational advice. (Introduction; Set up looping manually; Control context, progress, and output)
- limits: A timeout may omit parts of a remote operation; a timeout also does not establish that side effects did not occur. — AWS-TIMEOUTS-BROOKER-2019. Selected full-text passages read. The document has a 2019 copyright notice; an exact publication date was not established. This limits claims that an iteration cap alone bounds elapsed time or that stopping a caller cancels remote work. (PDF pp. 2–3, Failures Happen and Timeouts)
- RS-86F401513BF07EEC: Agent looping — https://learn.microsoft.com/en-us/agent-framework/agents/looping
- AWS-TIMEOUTS-BROOKER-2019: Timeouts, retries, and backoff with jitter — https://d1.awsstatic.com/builderslibrary/pdfs/timeouts-retries-and-backoff-with-jitter.pdf — Marc Brooker

Editorial version: 1.0.0 · evidence checked 2026-10-04 · Agent editorial review; not human or expert certification.

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/bound-how-much-damage-one-agent-run-can-do

---

## Write the completion condition before the agent starts iterating

ID: MHC-D-RESEARCH-0946 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/write-the-completion-condition-before-the-agent-starts-iterating

An agent loop cannot finish reliably if 'done' exists only in the model's mood.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- An agent is told to 'keep improving' or 'work until done' without an external definition of done.

### Avoid when

- Open-ended creative work may need a human accept/reject condition rather than an objective test.

### Explanation

Define the observable completion state outside the loop: tests pass, required files exist, all checklist items are satisfied, source coverage reaches a threshold, or another verifiable condition. Keep subjective quality separate from mandatory completion so the agent does not keep polishing indefinitely.

### Steps

1. Completion is observable outside the model's narrative.
2. Mandatory outputs are explicit.
3. Quality improvements are separated from hard done criteria.
4. A human or grader can verify the state without trusting 'I finished.'

### Example

For a repo task, completion means the requested files changed, tests pass and the final diff contains no unrelated edits—not 'the implementation looks good now.'

### Check

A separate evaluator could decide done/not-done from artifacts and state.

### Limits

- Open-ended creative work may need a human accept/reject condition rather than an objective test.

### Evidence and sources

- supports: Agent-loop frameworks rely on explicit completion conditions; evaluation guidance likewise recommends unambiguous tasks and success criteria. — RS-86F401513BF07EEC. Open-ended creative work may need a human accept/reject condition rather than an objective test. (See source record)
- RS-86F401513BF07EEC: Agent Looping — https://learn.microsoft.com/en-us/agent-framework/agents/looping

No review details supplied.
Related (use_before): https://vedokrok.com/knowledge/keep-an-eval-set-that-can-embarrass-the-agent

---

## Detect stagnation separately from completion

ID: MHC-D-RESEARCH-0947 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/detect-stagnation-separately-from-completion

More motion is not the same thing as more progress.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- An agent is still acting but the task state is not improving.

### Avoid when

- Some valid work has delayed visible progress; choose signals that fit the task rather than using one generic iteration count.

### Explanation

Track a small progress signal—remaining checklist items, failing tests, unresolved claims, changed artifacts or another task-specific state. If several iterations repeat without reducing the remaining work, stop the normal loop and trigger replanning or human review. Do not let lack of progress masquerade as persistence.

### Steps

1. The loop can identify 'not done and not improving' as a state distinct from both success and ordinary progress.

### Example

If three coding iterations leave the same two tests failing with nearly identical edits, switch from retrying to diagnosis.

### Check

The loop can identify 'not done and not improving' as a state distinct from both success and ordinary progress.

### Limits

- Some valid work has delayed visible progress; choose signals that fit the task rather than using one generic iteration count.

### Evidence and sources

- supports: Long-horizon agent failure syntheses report compounding planning/execution failures and stalled behavior, supporting explicit progress diagnostics rather than outcome-only monitoring. — RS-A938C271AB252914. Some valid work has delayed visible progress; choose signals that fit the task rather than using one generic iteration count. (See source record)
- RS-A938C271AB252914: Beyond the Leaderboard: A Synthesis of Tool-Use, Planning, and Reasoning Failures in Large Language Model Agents — https://arxiv.org/abs/2607.05775

### Vedokrok editorial review

Check stalled work before stopping the agent

A progress alarm should start a diagnosis. It should not declare failure just because a counter stayed flat: an investigation can rule out a cause before it fixes anything.

#### Compare evidence of progress

Choose a signal linked to the task and a review interval before the run. At each check, save the last verified result, new evidence and remaining work. If these stay unchanged, inspect the recent actions and choose a different approach, a bounded wait or a request for help. For a failing build, an unchanged test count may still hide a useful finding that eliminates one suspected cause.

#### Keep the alarm separate from the verdict

This is an editorial monitoring heuristic, not a validated three-iteration rule. The cited paper is a narrative synthesis of agent failures; it does not establish an effective stagnation threshold. Its authors did not reproduce the underlying experiments. Test the alarm on both genuine loops and useful slow work. Record false alarms as well as missed stalls, and adjust the signal or interval when either is unacceptable.

**Editorial takeaway:** Produce a short diagnosis and a justified next action. An unchanged metric is a reason to inspect progress, not sufficient evidence that progress is impossible.

#### Editorial evidence

- contextualizes: The synthesis describes failures in composed, long-horizon agent tasks and proposes reporting partial progress alongside final success. — RS-A938C271AB252914. Selected full-text passages inspected in the 16-page PDF after HTML retrieval failed. These observations motivate review; they do not measure the benefit of this proposed alarm. (arXiv v1 PDF, sections 7.1–7.4 and 8.1, pp. 12–13)
- limits: The paper is a narrative review, does not reproduce its underlying experiments, and mainly covers English text and web tasks. — RS-A938C271AB252914. These are the authors’ stated review limitations. No specific stopping threshold or detector accuracy is claimed. Underlying benchmark experiments were not independently reviewed in this pass. (arXiv v1 PDF, section 9, p. 14)
- RS-A938C271AB252914: Beyond the Leaderboard: A Synthesis of Tool-Use, Planning, and Reasoning Failures in Large Language Model Agents — https://arxiv.org/abs/2607.05775v1 — Wael Albayaydh, Rui Zhao, Ivan Flechais

Editorial version: 1.0.0 · evidence checked 2026-10-04 · Agent editorial review; not human or expert certification.

No review details supplied.

---

## Treat repeated state-action pairs as a loop alarm

ID: MHC-D-RESEARCH-0948 · Version: 0.1.0 · Kind: heuristic
Source: https://vedokrok.com/knowledge/treat-repeated-state-action-pairs-as-a-loop-alarm

If the state did not change, the same action is usually a retry—not a new strategy.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- An agent repeatedly invokes the same tool or applies nearly the same fix without changing the relevant state.

### Avoid when

- Some polling/waiting tasks intentionally repeat; tag those loops separately with time-based conditions.

### Explanation

Record a compact signature of current state plus chosen action. When the same or near-identical pair recurs, flag it as potential looping and require an explicit explanation of what changed to justify another attempt. Otherwise replan, widen evidence or escalate.

### Example

The agent searches the same query four times and receives the same results; a loop alarm should force query redesign or stop.

### Check

Repeated actions require a changed state or new rationale rather than silently consuming budget.

### Limits

- Some polling/waiting tasks intentionally repeat; tag those loops separately with time-based conditions.

### Evidence and sources

- supports: Autonomous loops can stall, and long-horizon reliability degrades when repeated actions fail to resolve planning or execution problems. — RS-86F401513BF07EEC. Some polling/waiting tasks intentionally repeat; tag those loops separately with time-based conditions. (See source record)
- RS-86F401513BF07EEC: Agent Looping — https://learn.microsoft.com/en-us/agent-framework/agents/looping

No review details supplied.

---

## Retry after a state change; replan after the same failure

ID: MHC-D-RESEARCH-0949 · Version: 0.1.0 · Kind: principle
Source: https://vedokrok.com/knowledge/retry-after-a-state-change-replan-after-the-same-failure

A retry is justified by changed conditions; otherwise it is often just repetition.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- A tool call or action fails and the default response is to immediately repeat it.

### Avoid when

- Some failures are probabilistic even with unchanged visible state; use bounded retries informed by service behavior.

### Explanation

After failure, identify whether the environment changed: transient service error, refreshed credentials, corrected parameters or new input. If yes, retry within a bounded policy. If the same deterministic failure remains, change the plan or tool choice instead of spending another attempt on the same path.

### Example

Retry a rate-limited API after backoff; do not resend the same invalid schema payload five times.

### Check

Retries have a reason tied to changed state rather than hope.

### Limits

- Some failures are probabilistic even with unchanged visible state; use bounded retries informed by service behavior.

### Evidence and sources

- supports: Long-running agent guidance emphasizes bounded loops and actionable tool errors that steer agents toward corrected inputs rather than opaque repetition. — RS-6E5D62426C731E4C. Some failures are probabilistic even with unchanged visible state; use bounded retries informed by service behavior. (See source record)
- RS-6E5D62426C731E4C: Writing effective tools for AI agents—using AI agents — https://www.anthropic.com/engineering/writing-tools-for-agents

### Vedokrok editorial review

Decide whether to retry, repair or check the outcome

A failed response is not always a failed operation. Before another attempt, decide what failed, whether repeating the action is safe, and what makes another attempt reasonable.

#### Choose the next action from the failure

Read the service error and inspect the result when possible. Correct invalid inputs before trying again. A transient network or service fault may justify a bounded retry even when no visible state has changed. Follow the service retry policy; do not treat a permanent access denial as a reason to search for a bypass. Record the error, the retry reason and the remaining attempt budget.

#### Resolve uncertain writes before repeating them

If a write timed out, first check whether it took effect. Use the service’s documented duplicate-prevention mechanism when available: an idempotent retry repeats the same logical request without adding another effect. For example, check for the existing export job before submitting another. If the outcome remains uncertain and safe repetition is unavailable, stop and seek a decision. Retry timing and backoff are a separate concern from this choice.

**Editorial takeaway:** Choose one explicit branch: retry a recoverable operation, repair the request, verify an uncertain outcome, or stop. Changed conditions alone do not make a repeat safe.

#### Editorial evidence

- supports: Tool errors can provide specific input corrections instead of leaving an agent to repeat an opaque failure. — RS-6E5D62426C731E4C. Selected full-text passages read from vendor engineering guidance published 2025-09-11. This supports actionable error handling, not a universal rule that retries require visible state change. (Optimizing for token efficiency, error-response discussion)
- limits: Transient failures can recover on retry, but a missing response leaves uncertainty about whether a state-changing request already succeeded. — AWS-IDEMPOTENT-FEATONBY. Selected full-text passages read on the official AWS article. Publication date not established. The limit directly changes the retry decision after a timeout. (Introduction; Retrying and the potential for undesirable side effects)
- supports: A documented idempotent API contract can identify repeated logical requests and prevent additional side effects. — AWS-IDEMPOTENT-FEATONBY. Read the client-request-identifier discussion. Identical parameters alone do not always express identical intent; the service contract determines safe reuse. (Reducing client complexity with idempotent API design)
- RS-6E5D62426C731E4C: Writing effective tools for agents — with agents — https://www.anthropic.com/engineering/writing-tools-for-agents
- AWS-IDEMPOTENT-FEATONBY: Making retries safe with idempotent APIs — https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/ — Malcolm Featonby

Editorial version: 1.0.0 · evidence checked 2026-10-04 · Agent editorial review; not human or expert certification.

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/retry-slower-with-randomness-and-stop

---

## Checkpoint meaningful progress before a long agent crosses a fragile boundary

ID: MHC-D-RESEARCH-0950 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/checkpoint-meaningful-progress-before-a-long-agent-crosses-a-fragile-boundary

Progress that exists only in the current context window is not durable progress.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- A task spans many tool calls, context compactions, process restarts or long-running background work.

### Avoid when

- Do not checkpoint secrets or unnecessary raw data into insecure storage.

### Explanation

Save a checkpoint after meaningful milestones: current task state, completed outputs, unresolved items, relevant artifact versions and next action. Use checkpointing before context reset, external wait, process restart or other point where reconstruction would be expensive.

### Steps

1. Completed artifacts have stable identities.
2. Open work and next action are recorded.
3. Critical assumptions/decisions are persisted.
4. Checkpoint can be rehydrated without replaying the entire transcript.

### Example

After finishing repository analysis, persist the selected plan and changed-file list before the agent starts a long implementation phase.

### Check

A later process can resume from the checkpoint without guessing what the prior context knew.

### Limits

- Do not checkpoint secrets or unnecessary raw data into insecure storage.

### Evidence and sources

- supports: Microsoft's workflow checkpoint guidance supports saving state so long-running workflows can resume after failures or pauses. — RS-170C21C3D7B258FD. Do not checkpoint secrets or unnecessary raw data into insecure storage. (See source record)
- RS-170C21C3D7B258FD: Microsoft Agent Framework Workflows - Checkpoints — https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints

### Vedokrok editorial review

Test that the checkpoint can survive a restart

A handoff note tells the next agent what to do. A workflow checkpoint must also contain the state the software needs to resume. Decide which kind of recovery you need before saving it.

#### Save for the failure you expect

At a supported checkpoint boundary, save the workflow state and references to completed outputs, pending work and the next action. Choose storage that survives the expected failure. Microsoft’s in-memory checkpoint store does not survive a process restart; a local file does not by itself provide cross-machine recovery. Keep secrets and unnecessary raw data out of saved state. Keep storage private, preserve the workflow’s required structure and identities, and record the versions needed to reopen the saved state.

#### Prove recovery with a safe restart

Never load an untrusted or possibly tampered checkpoint. Stop a test process after a milestone, start a fresh process and restore the checkpoint. Verify the last completed output, the next pending action and any external writes before continuing. A saved summary is not enough if the program also needs executor state. Checkpoints do not automatically settle whether a timed-out external action succeeded. If required state is missing or incompatible, stop and repair the recovery path rather than guessing.

**Editorial takeaway:** The useful output is a recoverable state plus a tested resume path. Saving a checkpoint is only the first half of that job.

#### Editorial evidence

- supports: Checkpoint storage providers have different durability, and restoring a workflow requires compatible structure and executor identities. — RS-170C21C3D7B258FD. Official documentation updated 2026-09-16; selected full-text passages read. General procedure is editorial; exact identities and save/restore hooks depend on SDK and version. (Capturing Checkpoints, provider table; Rehydrating from Checkpoints; Save Executor States)
- limits: In-memory checkpoint storage cannot preserve work across process restarts, and untrusted checkpoint data must not be loaded. — RS-170C21C3D7B258FD. Selected full-text passages read. Restore testing is a proposed acceptance check, not a reported experiment or a promise that all application state is captured. (Capturing Checkpoints, In-Memory; Security Considerations)
- limits: Resilient execution does not automatically preserve all application progress or prevent duplicate external effects. — MS-FOUNDRY-RESILIENCE-PREVIEW. Official preview documentation, updated 2026-08-19, read in substantive sections. Used to bound the generic recovery claim, not to recommend production adoption of the preview service. (Background execution and resilience; Platform and application responsibilities)
- RS-170C21C3D7B258FD: Microsoft Agent Framework Workflows - Checkpoints — https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints
- MS-FOUNDRY-RESILIENCE-PREVIEW: Resilience for long-running Microsoft Foundry hosted agents (preview) — https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/long-running-agent-resilience

Editorial version: 1.0.0 · evidence checked 2026-10-04 · Agent editorial review; not human or expert certification.

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/checkpoint-the-task-before-a-planned-interruption

---

## Store durable task state outside the context window

ID: MHC-D-RESEARCH-0951 · Version: 0.1.0 · Kind: principle
Source: https://vedokrok.com/knowledge/store-durable-task-state-outside-the-context-window

Context is working memory, not a durable project database.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- The agent keeps all progress, decisions and open items only in conversation history.

### Avoid when

- Persistent memory can become stale or wrong; attach timestamps, versions or source references to important state.

### Explanation

Persist structured task state—todo status, decisions, artifact references, constraints and unresolved questions—in an external file, database or workflow state. Rehydrate only what the next step needs. This makes continuity less dependent on one increasingly polluted context window.

### Example

Keep `STATE.md` or a structured workflow record with current branch, completed tasks, test status and open blockers instead of relying on 80,000 tokens of chat history.

### Check

Important project state survives a fresh context and can be inspected independently.

### Limits

- Persistent memory can become stale or wrong; attach timestamps, versions or source references to important state.

### Evidence and sources

- supports: Anthropic and current long-running-agent frameworks recommend structured memory or durable state outside the context window for continuity. — RS-23629BCC74F3AC0C. Persistent memory can become stale or wrong; attach timestamps, versions or source references to important state. (See source record)
- RS-23629BCC74F3AC0C: Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/carry-data-lineage-through-derived-outputs

---

## Compact context by preserving decisions and unresolved work—not every tool result

ID: MHC-D-RESEARCH-0952 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/compact-context-by-preserving-decisions-and-unresolved-work-not-every-tool-result

Compaction should save the project, not the transcript.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- A long context contains large raw tool outputs and repeated discussion that crowd out current task state.

### Avoid when

- Over-aggressive compaction can silently remove a detail that matters later; favor recall before token efficiency.

### Explanation

When context must be compressed, preserve architectural decisions, constraints, unresolved bugs/questions, current state, source/artifact references and next actions. Drop duplicated prose and old raw tool results once their useful facts are represented elsewhere. Start with high recall; trim only after testing complex traces.

### Steps

1. Keep decisions and their reasons.
2. Keep unresolved items and next actions.
3. Keep references to authoritative artifacts/sources.
4. Remove redundant raw tool outputs already reflected in durable state.
5. Test compaction on difficult long traces before aggressive shortening.

### Example

Keep 'migration uses option B because rollback is required' and the source file path; drop the 2,000-line raw search result that led there.

### Check

A fresh context can continue the task without reopening decisions or inventing missing constraints.

### Limits

- Over-aggressive compaction can silently remove a detail that matters later; favor recall before token efficiency.

### Evidence and sources

- supports: Anthropic recommends compaction that preserves key decisions, unresolved work and implementation details while removing redundant tool outputs. — RS-23629BCC74F3AC0C. Over-aggressive compaction can silently remove a detail that matters later; favor recall before token efficiency. (See source record)
- RS-23629BCC74F3AC0C: Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

### Vedokrok editorial review

Keep the decision; make the transcript recoverable

A long-running agent can produce thousands of lines while the next useful action depends on five facts. Compaction is the handoff between those two scales. The handoff should say what was decided, why, what remains open, where the current artifacts live and how to check the next move. Its quality is measured by whether work can resume accurately, not by how short the summary looks.

#### Save the state that changes the next action

Imagine an agent preparing a site release. It tested the new page, found a broken link, fixed it and then stopped before deployment. A useful handoff names the tested commit, the fixed route, the test result, the remaining deployment step and the reason the work stopped. It does not need the full console log in the next prompt. Anthropic describes a similar approach in its context-engineering guidance: preserve decisions, unresolved problems and implementation details while clearing redundant tool output. That is an engineering pattern, not a guarantee that every automated summary keeps the right details.

#### Leave a route back to what you removed

A short note cannot anticipate every future question. Keep stable paths, commit IDs, report names or other references that let the next agent reopen the original evidence when a consequential detail matters. A decision without its reason may be reopened; a reason without its source can become an invented fact. Separate the current working summary from a durable record of events or artifacts. Anthropic's later account of managed agents makes the cost of deletion explicit: once compacted messages leave the active context, they can be recovered only if the system stored them elsewhere.

#### Test a handoff by resuming the work

Give the compacted state to a fresh agent or reviewer and ask three questions: What has already been verified? What is still uncertain? What action is allowed next? Compare the answers with the durable artifacts. If the new agent repeats a completed step, invents an approval or misses a stop condition, the handoff failed even if it reads smoothly. Start with generous recall on difficult traces, then remove details shown to be redundant. This is a proposed quality check for the workflow, not a measured claim that one summary format improves all agents.

#### When a summary is the wrong store

Do not use the next context window as the only copy of a decision, an exact source excerpt needed for audit, or a result that cannot be reproduced cheaply. Keep those in an appropriate durable system and point to them from the handoff. Limit what the agent can save: secrets, private customer data and irrelevant raw logs should not be copied into a broad shared note. When the original material is unavailable, say that the summary is incomplete and recheck the fact before acting on it.

**Editorial takeaway:** Compress the working view, not the evidence trail. Record decisions with reasons, unresolved work, exact artifact references and the next permitted action. Keep important originals recoverable, then test whether a fresh reader can resume without guessing. If an irreversible step depends on a detail absent from the handoff, reopen the source before proceeding.

#### Editorial evidence

- supports: Anthropic describes a compaction approach that preserves architectural decisions, unresolved bugs and implementation details while discarding redundant tool outputs or messages. — anthropic-context-engineering-2025. This is a first-party account of an engineering practice, not a controlled estimate of its effect across agents or tasks. (Context engineering for long-horizon tasks, Compaction)
- limits: Anthropic warns that aggressive compaction can lose subtle context whose importance becomes apparent later, and advises testing on complex traces with recall before brevity. — anthropic-context-engineering-2025. This limits any advice to delete old context merely to reduce tokens; the proposed resume check is an editorial operationalization, not a validated intervention. (Context engineering for long-horizon tasks, Compaction)
- limits: Anthropic's managed-agent design treats the event session as durable storage because discarded context can cause failures and compacted messages are recoverable only when stored elsewhere. — anthropic-managed-agents-2026. This challenges treating a compact summary as a complete archive. It is a vendor design account, not evidence that every product needs the same storage architecture. (The session is not Claude's context window)
- anthropic-context-engineering-2025: Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents — Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, Jeremy Hadfield
- anthropic-managed-agents-2026: Scaling Managed Agents: Decoupling the brain from the hands — https://www.anthropic.com/engineering/managed-agents — Lance Martin, Gabe Cemaj, Michael Cohen

Editorial version: 1.0.0 · evidence checked 2026-09-28 · Agent editorial review; not human or expert certification.

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/version-the-configuration-that-changes-behavior

---

## Retrieve context just in time instead of preloading the whole project

ID: MHC-D-RESEARCH-0953 · Version: 0.1.0 · Kind: principle
Source: https://vedokrok.com/knowledge/retrieve-context-just-in-time-instead-of-preloading-the-whole-project

Relevant context is valuable; irrelevant context taxes every token after it.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- An agent starts every task with huge documentation, memory and historical transcripts loaded into context.

### Avoid when

- Just-in-time retrieval fails if indexing is weak or the agent does not know important information exists.

### Explanation

Load the stable rules and task essentials up front, then retrieve project details, documents or memory when the current step needs them. This reduces context pollution and keeps attention focused. Add retrieval cues or source indexes so the agent knows what can be fetched later.

### Example

Load repository rules and task goals at start; fetch a specific design document only when modifying that component.

### Check

Most loaded context is relevant to the current stage rather than merely potentially useful someday.

### Limits

- Just-in-time retrieval fails if indexing is weak or the agent does not know important information exists.

### Evidence and sources

- supports: Anthropic's context-engineering guidance recommends treating context as finite and using just-in-time retrieval instead of indiscriminate preloading. — RS-23629BCC74F3AC0C. Just-in-time retrieval fails if indexing is weak or the agent does not know important information exists. (See source record)
- RS-23629BCC74F3AC0C: Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

### Vedokrok editorial review

Fetch task details when needed, with a fallback

Loading fewer documents is useful only if the agent still finds the information the task requires. Combine a small starting context with a reliable way to retrieve missing details.

#### Keep essentials available from the start

Load the goal, required constraints and information needed for the first decision. Keep references to other relevant material and fetch it before making a decision that depends on it. For example, a documentation agent can retrieve one component guide when editing that component, while keeping the project’s writing and disclosure rules available throughout. If a required reference is missing, stop that decision and recover the source.

#### Compare completeness as well as context size

Try this approach on representative tasks against a suitable preloaded baseline. Check required facts found, wrong decisions, retrieval time and total context used. Anthropic’s guidance describes runtime search as a trade-off: it may be slower and can miss key information without suitable tools and guidance. Preload material that is predictably needed when retrieval adds delay or repeatedly fails. Fewer loaded tokens alone are not evidence of a better result.

**Editorial takeaway:** Use retrieval to select relevant information, then verify that selection. Keep a fallback for missing sources and for tasks where preloading is simpler.

#### Editorial evidence

- supports: Just-in-time retrieval uses lightweight references to load information during a task; the guidance also describes hybrid approaches. — RS-23629BCC74F3AC0C. Vendor engineering article published 2025-09-29; selected full-text section read. The comparison procedure and documentation example are editorial recommendations, not results reported by the source. (Context retrieval and agentic search)
- limits: Runtime exploration can be slower than precomputed retrieval and can miss important information without effective tools and guidance. — RS-23629BCC74F3AC0C. This source-bound trade-off replaces an unconditional benefit claim. No task-independent performance gain, token target or superiority of retrieval over preloading is asserted. (Context retrieval and agentic search, trade-off and hybrid-strategy paragraphs)
- RS-23629BCC74F3AC0C: Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

Editorial version: 1.0.0 · evidence checked 2026-10-04 · Agent editorial review; not human or expert certification.

No review details supplied.

---

## Let subagents write durable artifacts instead of relaying everything through the coordinator

ID: MHC-D-RESEARCH-0954 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/let-subagents-write-durable-artifacts-instead-of-relaying-everything-through-the-coordinator

Every relay is another chance to lose detail.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- Specialist subagents produce large outputs that are summarized through several agents before reaching the final artifact.

### Avoid when

- Shared artifact stores need access control, provenance and conflict handling when multiple agents write concurrently.

### Explanation

When a subagent creates structured work—code, report, dataset, analysis—store it directly in the shared artifact system and pass a lightweight reference to the coordinator. The coordinator should synthesize or validate the artifact without forcing the full content through multiple conversational summaries.

### Steps

1. Give the subagent an explicit artifact destination.
2. Persist the output with a stable identity.
3. Return a concise result plus artifact reference.
4. Have the coordinator inspect or validate the artifact directly when needed.

### Example

A research subagent writes `market_scan.json`; the lead receives the path and summary instead of a rewritten copy of every source note.

### Check

Large specialist output can reach final production without a game of telephone through agent summaries.

### Limits

- Shared artifact stores need access control, provenance and conflict handling when multiple agents write concurrently.

### Evidence and sources

- supports: Anthropic's multi-agent research architecture uses direct artifact persistence to reduce information loss and token overhead across subagent handoffs. — RS-6479FBCFE4AB9C97. Shared artifact stores need access control, provenance and conflict handling when multiple agents write concurrently. (See source record)
- RS-6479FBCFE4AB9C97: How we built our multi-agent research system — https://www.anthropic.com/engineering/multi-agent-research-system

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/use-one-handoff-shape-for-recurring-transitions

---

## Evaluate the same agent task across multiple trials

ID: MHC-D-RESEARCH-0955 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/evaluate-the-same-agent-task-across-multiple-trials

A nondeterministic system needs more than one audition.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- One successful run is being treated as proof that an agent workflow is reliable.

### Avoid when

- Trial count should match cost and risk; small samples still leave uncertainty.

### Explanation

Run representative tasks multiple times and report distribution, not only pass@1 from a favorable run. Capture success, failure mode, steps, cost and variance. This distinguishes occasional capability from repeatable reliability, especially on longer tasks.

### Steps

1. Reliability claims include repeated trials and failure distribution rather than one anecdote.

### Example

Run the same repository change ten times in isolated copies to see whether the agent consistently edits the right files and completes tests.

### Check

Reliability claims include repeated trials and failure distribution rather than one anecdote.

### Limits

- Trial count should match cost and risk; small samples still leave uncertainty.

### Evidence and sources

- supports: Anthropic's agent-eval guidance defines separate trials because model outputs vary and recommends multiple trials for more consistent evaluation. — RS-EE9379CE3D2ABBDD. Trial count should match cost and risk; small samples still leave uncertainty. (See source record)
- RS-EE9379CE3D2ABBDD: Demystifying evals for AI agents — https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents

### Vedokrok editorial review

Repeat agent evaluations without selecting the best run

One successful run shows that success is possible. To estimate repeatability, preserve the failures too, and state exactly what your success metric counts.

#### Make attempts comparable

Choose representative tasks and a trial count before inspecting results. Keep model, tools, task and grading versions fixed; reset each trial to a clean starting state. Save every outcome, failure type, duration and cost. For example, report seven successes and three failures on a task across ten attempts, rather than showing only the best output. Ten is an illustration, not a recommended sample size.

#### Name the event being measured

Pass@1 concerns single-attempt success; it is not a name for a cherry-picked favorable run. Pass@k concerns at least one success in k attempts, while pass^k concerns success on every one of k attempts. State the chosen metric, sample size and per-task results. Shared files or resource shortages can connect trials and distort results. Repetition also cannot repair unrepresentative tasks or establish reliability outside the tested conditions.

**Editorial takeaway:** Keep a complete trial ledger and explain which success event the score estimates. A better best-case result and more dependable single attempts answer different questions.

#### Editorial evidence

- supports: The guidance distinguishes individual trials and the different success events represented by pass@k and pass^k. — RS-EE9379CE3D2ABBDD. Official engineering guidance published 2026-01-09. Selected full-text passages read. This corrects the original treatment of pass@1; no estimator formula or confidence interval is prescribed. (The structure of an evaluation; How to think about non-determinism in evaluations for agents)
- limits: Shared trial state can inflate results, while shared environment constraints can produce correlated failures. — RS-EE9379CE3D2ABBDD. Selected full-text passage read. Starting clean is necessary for a useful comparison but does not prove statistical independence or coverage of real-world tasks. (Step 4: Build a robust eval harness with a stable environment)
- RS-EE9379CE3D2ABBDD: Demystifying evals for AI agents — https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents

Editorial version: 1.0.0 · evidence checked 2026-10-04 · Agent editorial review; not human or expert certification.

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/keep-an-eval-set-that-can-embarrass-the-agent

---

## Read eval transcripts before trusting the score

ID: MHC-D-RESEARCH-0956 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/read-eval-transcripts-before-trusting-the-score

A score can fail because the agent failed—or because the eval did.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- An agent's eval score moves and the team immediately attributes the change to model quality.

### Avoid when

- Transcript review is expensive; sample strategically while keeping automated coverage broad.

### Explanation

Sample transcripts from passes and failures. Check whether tasks were unambiguous, graders penalized valid solutions, tool constraints caused artificial failures, or the agent genuinely made mistakes. Update the eval when the failure is unfair; update the agent when the failure is real.

### Steps

1. Read multiple failed transcripts.
2. Read some passes for hidden shortcuts.
3. Compare grader decision with artifact reality.
4. Classify agent failure versus eval/harness failure.
5. Feed real failures back into the eval set.

### Example

A coding agent 'fails' because the grader assumed a filepath the task never specified; that is an eval bug, not an agent regression.

### Check

Score changes have a transcript-backed explanation before they drive model or workflow decisions.

### Limits

- Transcript review is expensive; sample strategically while keeping automated coverage broad.

### Evidence and sources

- supports: Anthropic explicitly recommends reading eval transcripts to distinguish genuine agent mistakes from unfair grading or harness problems. — RS-EE9379CE3D2ABBDD. Transcript review is expensive; sample strategically while keeping automated coverage broad. (See source record)
- RS-EE9379CE3D2ABBDD: Demystifying evals for AI agents — https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/do-not-assume-a-rubric-reduced-noise-measure-it

---

## Combine grader types instead of asking one LLM judge to decide everything

ID: MHC-D-RESEARCH-0957 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/combine-grader-types-instead-of-asking-one-llm-judge-to-decide-everything

A flexible judge is useful; a monoculture of judgment is fragile.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- An open-ended agent task is scored entirely by one model-based evaluator.

### Avoid when

- More graders can add cost and conflicting signals; each must serve a clear decision.

### Explanation

Use deterministic checks where the outcome is objective, model-based rubrics for nuanced qualities, and human review to calibrate subjective grading. Design each grader for a specific dimension rather than one omnibus 'good/bad' score. Recalibrate model graders when tasks or models change.

### Steps

1. Use code/tests for objective conditions.
2. Use model rubrics for open-ended qualities.
3. Use human examples to calibrate subjective graders.
4. Keep grader dimensions separate enough to debug disagreement.

### Example

A research agent can be graded by source existence checks, citation-groundedness rubric, coverage checks and expert spot review.

### Check

No single probabilistic grader has unchecked authority over every success dimension.

### Limits

- More graders can add cost and conflicting signals; each must serve a clear decision.

### Evidence and sources

- supports: Anthropic's 2026 agent-eval guidance recommends combining code-based, model-based and human graders according to task needs. — RS-EE9379CE3D2ABBDD. More graders can add cost and conflicting signals; each must serve a clear decision. (See source record)
- RS-EE9379CE3D2ABBDD: Demystifying evals for AI agents — https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents

No review details supplied.
Related (useful_with): https://vedokrok.com/knowledge/measure-agreement-on-the-criteria-not-only-the-verdict

---

## Track tool errors, tool calls, runtime and tokens as agent diagnostics

ID: MHC-D-RESEARCH-0958 · Version: 0.1.0 · Kind: checklist
Source: https://vedokrok.com/knowledge/track-tool-errors-tool-calls-runtime-and-tokens-as-agent-diagnostics

The path to the answer reveals inefficiency before users notice the bill or latency.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- Agent evaluation records only final pass/fail.

### Avoid when

- Lower cost or fewer calls are not automatically better if they reduce robustness or coverage.

### Explanation

Alongside task success, record number of tool calls, tool errors, runtime, token use and repeated calls. These metrics help detect confused tool selection, bloated responses, loops and regressions that final accuracy can hide.

### Checklist

- Count tool calls by tool.
- Count validation/tool errors.
- Track total runtime and major tool latency.
- Track token/context consumption.
- Flag repeated or redundant calls on successful tasks too.

### Example

Two agents both pass, but one needs 7 tool calls and the other 48 with five schema errors; that difference deserves investigation.

### Check

Efficiency and failure-path regressions are visible even when final success stays constant.

### Limits

- Lower cost or fewer calls are not automatically better if they reduce robustness or coverage.

### Evidence and sources

- supports: Anthropic recommends tracking runtime, tool-call count, token consumption and tool errors in addition to top-level accuracy. — RS-6E5D62426C731E4C. Lower cost or fewer calls are not automatically better if they reduce robustness or coverage. (See source record)
- RS-6E5D62426C731E4C: Writing effective tools for AI agents—using AI agents — https://www.anthropic.com/engineering/writing-tools-for-agents

No review details supplied.

---

## Monitor the whole agent trajectory, not only individual allowed actions

ID: MHC-D-RESEARCH-0959 · Version: 0.1.0 · Kind: protocol
Source: https://vedokrok.com/knowledge/monitor-the-whole-agent-trajectory-not-only-individual-allowed-actions

A safe-looking step can participate in an unsafe-looking trajectory.

Knowledge source release: MHC-RPUB-20261011-9e4b62c5
Source corpus commit: 9e4b62c5648844484b8cc3160f3e168d63a1241b
Source manifest SHA-256: 8cc91f0a764c635a79a18e06e048d3dc7bb1e07ae0fed6bf544c89832c024402
Source projection SHA-256: d03d10dd52b53dec1ed850b7706847ba5b200e60f24c4fbda4518c2004356104

### Use when

- Every individual tool call is allowed, but the sequence may be drifting toward an unwanted outcome.

### Avoid when

- Trajectory monitors can false-positive; users need visibility and a controlled resume path.

### Explanation

For long-running capable agents, review the evolving sequence against user goals, constraints and safety boundaries. Detect patterns of constraint bypass, escalating permissions or goal drift across actions. Give the monitor authority to pause and surface the trajectory for user inspection.

### Steps

1. What outcome is this sequence converging toward?
2. Is the agent repeatedly approaching a boundary through individually allowed steps?
3. Has the original user constraint remained active across the rollout?
4. Can a monitor pause the session for review?

### Example

Several harmless file and network actions can collectively move data toward a destination the user never approved.

### Check

Monitoring can identify unwanted intent or drift that no single action-level rule would catch.

### Limits

- Trajectory monitors can false-positive; users need visibility and a controlled resume path.

### Evidence and sources

- supports: OpenAI's 2026 long-horizon safety report argues that long-running agents require trajectory-level monitoring and user visibility beyond single-action controls. — RS-048BB0497AD64C7C. Trajectory monitors can false-positive; users need visibility and a controlled resume path. (See source record)
- RS-048BB0497AD64C7C: Safety and alignment in an era of long-horizon models — https://openai.com/index/safety-alignment-long-horizon-models/

No review details supplied.
