Claude Code's Advisor Broke, So I Built My Own Subagent

TL;DR

Claude Code's advisor tool, the one that hands a hard call to a stronger model for a blunt second opinion, started returning "unavailable" on me mid-session. Turns out it is a known bug with a handful of causes, all hiding behind the same useless word. So I stopped waiting for a fix and rebuilt it in about twenty minutes from parts Claude Code already ships: a subagent, a slash command, and one line of memory. Here is how, and why I would keep the homemade version even after the tool comes back.

Want a team that builds agent systems this way for a living? Book a scoping call with DestiLabs.

What Actually Broke?

I was mid-refactor, at the point where the next move would be a pain to undo, and I asked for a second opinion. In Claude Code that is the advisor tool. You hand it a decision, it kicks that decision to a second, usually stronger model, and it comes back with a verdict, the exact way your plan falls apart, and the one fact that would change its mind. Closest thing a terminal has to a senior engineer looking over your shoulder for ten seconds.

That day it came back with one word. "Unavailable." I tried again. Same. Smaller context, fresh session. Same. No error, no reason, nothing to act on.

You get two choices when this happens. File a bug and wait, or route around it. I did the first to be polite and the second because I had work to finish.

Why Does the Claude Code Advisor Return "Unavailable"?

First I wanted to know whose fault it was. It is the tool's, and it is not one bug. Several unrelated failures all surface as the same word. These are open, public issues on the Claude Code tracker, not me guessing:

• It dies once a session has loaded any deferred tool through ToolSearch, which stock Claude Code does on its own, routinely.
• It dies when the advisor model is Fable 5 and the transcript crosses roughly 100K tokens.
• It dies on the first call of a session for certain main-and-advisor model pairings, no matter how small the context.
• One transient failure can latch it off for the whole session, so every later call returns "unavailable" without even trying.
• It works in the terminal but not the desktop app, same settings.

The pattern is an experimental feature with a wide failure surface, and every cause flattened into one word with no diagnostics. When something breaks that quietly, filing your sixth duplicate and waiting is not a plan. Rebuilding it from parts you control is.

What Is a Claude Code Subagent?

A subagent is a second Claude you define in a file. Its own system prompt, its own model, its own limited set of tools. Your main agent spawns it, hands it a job, and reads back the answer without cluttering the main session. People already use Claude Code subagents for code review and planning.

An advisor subagent and the advisor tool do the same job anyway: take a decision into a clean context on a strong model and hand back a verdict. The only difference is who owns it. The tool is hosted, so a flag I do not control can switch it off. A subagent is a text file in my repo. But nothing outside my project can make it unavailable.

So I did not fix the advisor. I built my own.

The Advisor Subagent, Field by Field

Subagents live in .claude/agents/. Mine is .claude/agents/advisor.md. Two parts: YAML frontmatter that configures the agent, and a body that is its system prompt. Here is the real frontmatter, verbatim:

• name: advisor - the handle the main agent spawns, and the name behind /advise.
• description: "A stronger-model second opinion for hard decisions - the replacement for the broken built-in advisor tool. Consult it before committing to an approach, when the same error keeps recurring, or before declaring a task done. Runs on Fable 5. Read-only: it judges and advises, it never edits or acts." This is what the main model reads to decide whether to reach for the subagent, so it is written as a trigger, not a summary.
• model: fable - a stronger model than my main loop. The whole point is judgment my main model cannot produce alone. A weaker advisor just agrees with me.
• tools: Read, Grep, Glob - read-only. It can open the files I point it at and check my claims against the code, and it stays physically unable to touch that code.

That last line does the heavy lifting. An advisor that can edit files is not an advisor, it is a second cook in the kitchen.

The body is the job description, and it is short. The real thing opens like this:

You are the advisor. A capable agent is doing real work and has paused to get an independent second opinion from a stronger model at a decision point. You are that stronger model. Your job is judgment, not action.

Then it spells out exactly what to hand back, verbatim from the file:

• A direct verdict. Lead with it. Agree, disagree, or offer a better third option.
• The failure mode: the specific way the path goes wrong and the conditions that trigger it. Not "this might have edge cases" but "this breaks when X because Y."
• The strongest objection it can construct, even when it ends up endorsing the plan.
• A recommendation I can act on, its confidence, and the one piece of evidence that would change its mind.

The rest is behavior: be terse, no preamble, every sentence has to carry judgment I did not already have. And treat my brief as claims to check against the real files, not as the truth, naming anything it could not verify. That is the whole agent, and none of it is clever. It is what a good reviewer does, written down once so I never have to explain it again.

Wiring It In: A Command and a Memory Rule

A file on its own is a capability nobody uses. Two small things turn it into a habit.

First, a slash command. Commands are markdown files in .claude/commands/, and mine is /advise. I type something like /advise should I migrate this schema in place or behind a new table? and the command spawns the advisor subagent with that decision. Its first instruction is the one that matters: do not act on the decision until the reply is incorporated, because a consult that arrives after you have already acted is theater. Then it forces the brief, verbatim from the command file:

• My ask quoted verbatim. Never paraphrase it, because a paraphrase hides the exact misreading the advisor exists to catch.
• The options I considered and the ones I rejected, with why.
• What has already been tried and failed, and the key constraints.
• The exact evidence the leading option rests on, and the file paths the advisor should read to check my claims.

When it returns, the command tells me to relay its verdict and strongest objection unsummarized, rather than filtering the second opinion through my own.

Second, a memory rule. Claude Code memory is just text the agent reads every session. Mine sets the bar for when to consult the advisor, and the bar is deliberately high: only when a decision is both consequential, meaning expensive or slow to reverse, and I am genuinely stuck and cannot resolve the doubt from the evidence already in front of me. The recurring-error case counts too: same root cause, survived two or more real fix attempts. Everything cheaper than that, I decide and move on. Without the rule, a second-opinion tool quietly turns into a way to stall. I have watched myself do it.

Three files. An agent, a command, a note. That is the whole thing.

Why Keep It After the Bug Is Fixed?

Because the homemade version is better than the one it replaced, in ways the fix will not touch. The model is my pick, one line, swapped the day a stronger one ships. Nothing can quietly disable it. The command makes me write down the decision and the evidence, which is usually the exact moment I realize I already know the answer. And the criteria sit in git, so I sharpen them over time instead of hoping the tool got better.

The bug was the push. Subagents were the lesson. I would run this now even if the advisor came back tomorrow.

The Pattern Worth Stealing

The same move works almost anywhere. A hosted feature turns flaky, and you can usually rebuild what it did from three parts you already have: a subagent for the isolated context and the model you want, a command for a repeatable way in, and a memory rule for when to use it. A flaky review tool becomes a review subagent. A slow search becomes a search subagent aimed at the two directories you actually care about. When your agents and your guardrails are text in git, they survive model updates and outages, and you are not one vendor incident away from losing something you lean on.

That is the discipline we bring at DestiLabs. We do not hand over a demo that worked the day we recorded it. We build custom AI agents, then audit and harden them until they survive real users and the fact that the tools underneath keep changing. If that is the kind of engineering you need, let's talk or see what we do. For the longer version, here is how we take AI-generated codebases to production: Preparing a Vibe-Coded App for Production.

Frequently Asked Questions

Why does Claude Code's advisor return "unavailable"?

Several different bugs share one generic message. The common ones: a session that loaded deferred tools through ToolSearch, a Fable 5 advisor on a transcript over ~100K tokens, certain main-and-advisor model pairings failing on the first call, and one transient failure disabling the tool for the rest of the session. It is experimental, so the surface is wide and the message never tells you which one you hit.

Can a subagent really replace the advisor tool?

For the "judge my decision" job, yes. It runs on a model you choose, with tools you restrict, in a clean context, and hands back the same kind of blunt verdict. Because it is a file you own, nothing outside your project can turn it off.

Where do Claude Code subagents live, and how do I make one?

They are markdown files in .claude/agents/. Each has frontmatter (name, description, model, tools) and a body that is the system prompt. Write the file, describe when the main agent should call it, and it is ready. Match the model to the job: a strong one for an advisor whose value is judgment, a cheaper one for mechanical work like search.

Key Takeaways

1. 1The advisor returning "unavailable" is a known experimental-feature bug with several causes behind one message. It is not your config.

1. 1A custom subagent is a real replacement: same job, on a model you pick, with tools you restrict, in a file no flag can disable.

1. 1The whole thing is three text files: an agent in .claude/agents/, a /advise command, and one memory rule for when to use it.

1. 1Keep the advisor read-only. Read, Grep, Glob lets it check your claims without ever editing your code, and the same three-file pattern rebuilds any other flaky hosted feature.

Want Agent Systems That Don't Fall Over When a Tool Does?

We build custom AI agents, then audit and harden them until they survive real users and shifting tools. If you are running on Claude Code, Cursor, or your own stack and you want it built to be owned, not rented, book a scoping call or see what we do.