Delete the Wrong Door

How removing a choice fixed a broken agent

The situation

When a session breaks, session-analyst is the agent sent in to repair it

In microsoft/amplifier-foundation, session-analyst is the REQUIRED agent for analyzing, debugging, searching, and repairing Amplifier sessions — performing transcript surgery to recover sessions with orphaned tool calls, ordering violations, or incomplete assistant turns.

And the way it was built to do that surgery is where the story turns.

“REQUIRED agent for analyzing, debugging, searching, and REPAIRING Amplifier sessions. Performs transcript surgery to recover sessions with orphaned tool calls, ordering violations, or incomplete assistant turns.” agents/session-analyst.md frontmatter (399 lines)

Proof — verified from the agent file

By design, this repair agent runs deliberately fast

The agent's frontmatter sets model_role to fast, with a Haiku-class model as its top provider preference. It is a quick, cheap model doing delicate surgery — and that speed is the fact the whole story hinges on.

A fast model is fine — until it is handed a choice it can get wrong.

fast

model_role in the agent frontmatter

claude‑haiku‑*

top provider preference (anthropic)

Setup — commit 8d950ae (#115)

When repair first landed, the agent was handed two doors

The repair capability arrived with a transcript parser and a diagnostic engine — but it gave the agent TWO paths: a safe Python repair script, and a documented manual fallback for hand-editing transcript.jsonl.

Two doors. The audience now knows both before the wrong one gets chosen.

1Script path — the safe Python repair tool that runs the diagnosis and rewrite.
2Manual path — a documented “Manual repair fallback” plus “Manual rewind procedure” for hand-editing transcript.jsonl / events.jsonl.

The complication

The fast model kept picking the manual door — and made broken sessions worse

Per the fix commit's own rationale, the Haiku-class fast model was choosing manual JSONL editing instead of the Python tool, which “made broken sessions worse.” The removed guidance admitted it in plain text.

So the tool built to repair sessions was breaking them further. What do you fix?

“Manual JSONL editing by a fast-model agent has proven to break sessions further. The script is the only safe path.” line added in commit 62fde35 to session-analyst.md

The turn — commit 62fde35

The fix wasn't a smarter agent — it deleted the dangerous path

Rather than teaching the model to behave, the fix removed the manual procedures and the “When to Fall Back to Manual Repair” escape hatch outright — a net removal of guidance across two files.

Take capability out of the context, and the wrong choice disappears with it.

87

insertions in the fix commit

196

deletions across 2 files

How it works

One mandatory rule now stands where two doors used to be

With the manual option gone, the guidance leaves a single script-only path and an explicit prohibition. If the script fails, the agent reports the error and stops — it has nowhere wrong left to go.

The correct action became the only available action.

### MANDATORY: Script Only — No Manual Repair

NEVER attempt to manually edit
transcript.jsonl or events.jsonl
for repair or rewind.

# if the script fails:
STOP. Do not attempt manual repair.

The payoff

“We eliminate the decision point entirely.”

By removing the choice, the fix takes the decision away from the fast model. It can no longer pick wrong — because there is nothing wrong left to pick. Safety came from deleting the option, not from a smarter agent.

The pattern

When a fast agent keeps making the same mistake, fix the context, not the model

The leverage was not intelligence — it was what the agent could reach. Remove the wrong door instead of teaching the agent to avoid one, and the mistake becomes impossible by construction.

Delete the option. Keep the outcome.

Don't add guidance telling a fast model to avoid the dangerous path.
Do remove the dangerous path from its context so only the safe one remains.

Sources

Research Methodology

Source repo: microsoft/amplifier-foundation (verified: git remote -v → origin = git@github.com:microsoft/amplifier-foundation.git)

Feature status: Shipped / in main-line agent guidance Shipped

Research performed:

Agent file: wc -l agents/session-analyst.md (399 lines) and sed -n '25,40p' agents/session-analyst.md (model_role: fast; claude-haiku-* top preference)
Pre-fix two paths: git show 62fde35~1:agents/session-analyst.md | grep -n 'Manual repair fallback\|Manual rewind procedure'
Fix rationale: git log -1 --format='%B' 62fde35 ("made broken sessions worse... eliminate the decision point entirely")
Net removal: git show 62fde35 --stat / --numstat (87 insertions / 196 deletions across 2 files)
Added warning line: git show 62fde35 -- agents/session-analyst.md | grep -n 'proven to break sessions'
Post-fix rule: grep -n 'MANDATORY: Script Only\|NEVER attempt to manually edit transcript' agents/session-analyst.md
Timeline: commits 81c05d3 (2025-12-31), 8d950ae/#115 (2026-03-04), 62fde35 & 2679c9b (2026-03-18)

Gaps: No repository artifact quantifies HOW MANY sessions the manual path broke; the "made worse" / "break further" claims are grounded in the fix commit message and the removed guidance text authored by the maintainer. The exact PR number for the enforcement fix (62fde35) is not embedded in its subject. Runtime model may vary by provider selection (haiku-* is the top preference; the commit characterizes it as "Haiku-class").

Primary contributor: Brian Krabach <brkrabac@microsoft.com> — author of commits 81c05d3, 8d950ae, 62fde35, and 2679c9b.