fix(cli): tell a switched-off capability apart from an unconfigured one

`is_configured` answered the credential gate while its own docstring
claimed to answer whether the tool "would be offered to the model right
now". Those come apart: `tools.disabledTools` is applied after
registration, in `AgentLoop._apply_disabled_tools`. A deployment with a
Serper key and `disabledTools: ["web_search"]` therefore got a green
doctor row naming `tools.web.search.apiKey` for a tool the agent does
not hold -- the report claiming a capability is on offer when Raven has
explicitly removed it.

Folding it into `configured` would be the wrong repair. A switched-off
tool usually has its credential set, so calling it unconfigured sends
the deployer to set a key that is already there. It is its own state and
it reads as one: `is_disabled` beside `is_configured`, and `is_offered`
for the question the registry actually answers.

The doctor row says which decision hid the tool, and where that decision
lives, so it can be undone in the one place that made it.

The parametrised test is the guard that matters: every capability,
switched on and then off by name, compared against a real AgentLoop's
final registry. Writing it caught a second thing worth knowing -- the
loop is told what is disabled through an argument, not by reading the
config, so a test that only sets the field proves nothing.

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>

Author: Handsome-wzw

raven/agent/tools/capabilities.py

@@ -150,13 +150,17 @@ def _resolved_media(cap: Capability, config: "Config") -> Any:
 
 
 def is_configured(cap: Capability, config: "Config") -> bool:
-    """Whether this capability would be offered to the model right now.
+    """Whether this capability's credential gate is satisfied.
 
     Delegates to the tool rather than deciding here. The rule for each family
     lives with the tool that owns the credential, so this module cannot become
     a second opinion about configured-ness -- which is the divergence
     ``providers.auth`` exists to prevent on the provider side, and the reason
     an AST invariant guards it there.
+
+    Not the same question as "is it offered", which :func:`is_offered` answers:
+    a deployment can switch a fully credentialed tool off. See
+    :func:`is_disabled`.
     """
     if cap.need is Need.NOTHING:
         return True
@@ -170,6 +174,29 @@ def is_configured(cap: Capability, config: "Config") -> bool:
     return WebSearchTool.is_configured(config.tools.web.search.api_key)
 
 
+def is_disabled(cap: Capability, config: "Config") -> bool:
+    """Whether the deployment has switched this tool off by name.
+
+    A separate state from unconfigured, and reported as one: a switched-off
+    tool usually has its credential set, and calling it unconfigured would send
+    the deployer to set a key that is already there.
+
+    ``tools.disabledTools`` is applied after registration
+    (``AgentLoop._apply_disabled_tools``), so this is the only thing standing
+    between a satisfied credential gate and a tool the agent actually holds.
+    """
+    return cap.tool in (config.tools.disabled_tools or [])
+
+
+def is_offered(cap: Capability, config: "Config") -> bool:
+    """Whether the agent ends up holding this tool: credentialed and not off.
+
+    The predicate that matches the final registry, which is what a report about
+    available capabilities has to agree with.
+    """
+    return is_configured(cap, config) and not is_disabled(cap, config)
+
+
 def has_credential(cap: Capability, config: "Config") -> bool:
     """Whether a credential actually resolves for this capability.
 

raven/cli/doctor_commands.py

@@ -155,6 +155,9 @@ class ToolCapabilityInfo:
     #: the same as ``configured``: a model with no key is registered and fails
     #: on every call.
     has_credential: bool = True
+    #: Switched off by name in ``tools.disabledTools``, which happens after
+    #: registration -- so this row is configured and still not offered.
+    disabled: bool = False
     config_path: str = ""
     #: Where this capability's own credential goes, which for the media family
     #: is not ``config_path`` -- that one names the model.
@@ -337,6 +340,7 @@ def _gather_tools(config: "Config") -> ToolsInfo:
         configured_from,
         has_credential,
         is_configured,
+        is_disabled,
     )
 
     return ToolsInfo(
@@ -348,6 +352,7 @@ def _gather_tools(config: "Config") -> ToolsInfo:
                 configured=is_configured(cap, config),
                 source=configured_from(cap, config),
                 has_credential=has_credential(cap, config),
+                disabled=is_disabled(cap, config),
                 config_path=cap.config_path,
                 key_path=cap.key_path,
                 borrowable=borrowable_credential(cap, config),
@@ -599,13 +604,28 @@ def _render_tool_capabilities(tools: ToolsInfo) -> None:
             # The marker carries the answer too: a green tick above a line
             # saying every call fails is the same misreport in miniature.
             mark = "[green]✓[/green]" if cap.has_credential else "[yellow]![/yellow]"
+            if cap.disabled:
+                # Not a tick and not a fault: switched off is a decision
+                # someone made, and the row says whose decision it was so it
+                # can be undone in the one place that made it.
+                mark = "[dim]x[/dim]"
             console.print(f"{label}{mark} {cap.summary}{where}")
+            if cap.disabled:
+                console.print(f"{indent}[dim]switched off in[/dim] tools.disabledTools")
+                continue
             if not cap.has_credential:
                 console.print(f"{indent}[yellow]no key resolves; calls will fail[/yellow]")
                 console.print(f"{indent}[dim]set:[/dim] {cap.key_path}")
                 console.print(f"{indent}[dim]or env:[/dim] {cap.env_var}")
             continue
-        console.print(f"{label}[dim]-  {cap.summary}[/dim]")
+        glyph = "x" if cap.disabled else "-"
+        console.print(f"{label}[dim]{glyph}  {cap.summary}[/dim]")
+        if cap.disabled:
+            # First, and outside the credential advice below: the two are
+            # independent decisions, and setup instructions that leave the off
+            # switch unsaid send someone to set a key, restart, and find the
+            # tool still gone.
+            console.print(f"{indent}[dim]switched off in[/dim] tools.disabledTools")
         if cap.need == "own_credential":
             console.print(f"{indent}[dim]switch on:[/dim] {cap.config_path}")
             if cap.borrowable:

tests/test_cli_doctor_commands.py

@@ -1040,3 +1040,84 @@ def test_a_config_path_is_never_split_across_lines(healthy_config: Path) -> None
 
     for path in ("tools.web.search.apiKey", "tools.media.image.model", "SERPER_API_KEY"):
         assert path in result.stdout, f"{path} was broken across a line wrap"
+
+
+def _search_config(tmp_path: Path, *, key: bool, off: bool) -> None:
+    """One cell of the web_search state matrix, persisted.
+
+    ``key`` and ``off`` are independent in production -- a deployment can set
+    neither, either, or both -- so they are independent here.
+    """
+    cfg = Config()
+    cfg.agents.defaults.model = "anthropic/claude-sonnet-4-5"
+    cfg.agents.defaults.workspace = str(tmp_path / "workspace")
+    cfg.providers.anthropic.api_key = "sk-fake"
+    if key:
+        cfg.tools.web.search.api_key = "sk-serper"
+    if off:
+        cfg.tools.disabled_tools = ["web_search"]
+    save_config(cfg)
+
+
+def _switched_off_search(tmp_path: Path) -> None:
+    """A credentialed web_search that the deployment has switched off by name."""
+    _search_config(tmp_path, key=True, off=True)
+
+
+def test_doctor_says_a_capability_is_switched_off_rather_than_ticking_it(tmp_config: Path, tmp_path: Path) -> None:
+    """A key plus `disabledTools` used to print a green tick for a tool the
+    agent does not hold -- the report claiming a capability is on offer when
+    Raven has removed it."""
+    _switched_off_search(tmp_path)
+
+    result = runner.invoke(app, ["doctor"])
+
+    assert "tools.disabledTools" in result.stdout
+    # Not the unconfigured path: the key is set, and telling them to set it
+    # again is how a report sends someone in a circle.
+    assert "switch on:" not in result.stdout.split("web_search")[-1][:200]
+
+
+def test_the_switched_off_state_reaches_the_json_output(tmp_config: Path, tmp_path: Path) -> None:
+    _switched_off_search(tmp_path)
+
+    result = runner.invoke(app, ["doctor", "--json"])
+    payload = json.loads(result.stdout)
+
+    row = next(c for c in payload["tools"]["capabilities"] if c["tool"] == "web_search")
+    assert row["configured"] is True, "the key is set; calling it unconfigured is the wrong repair"
+    assert row["disabled"] is True
+
+
+@pytest.mark.parametrize("key", [True, False], ids=["keyed", "keyless"])
+def test_the_off_switch_is_named_whether_or_not_a_key_is_set(key: bool, tmp_config: Path, tmp_path: Path) -> None:
+    """The cell the first version of this rendering got wrong.
+
+    With no key, the row used to print only the credential advice -- so a
+    deployer could set `tools.web.search.apiKey`, restart, and still not have
+    search, because `_apply_disabled_tools` removes it either way.
+    """
+    _search_config(tmp_path, key=key, off=True)
+
+    result = runner.invoke(app, ["doctor"])
+
+    assert "tools.disabledTools" in result.stdout
+
+
+@pytest.mark.parametrize(
+    ("key", "off", "configured", "disabled"),
+    [(True, True, True, True), (True, False, True, False), (False, True, False, True), (False, False, False, False)],
+    ids=["keyed-off", "keyed-on", "keyless-off", "keyless-on"],
+)
+def test_the_json_row_reports_the_two_states_independently(
+    key: bool, off: bool, configured: bool, disabled: bool, tmp_config: Path, tmp_path: Path
+) -> None:
+    """Both flags, all four combinations. Collapsing either into the other is
+    what made the report tell a deployer to set a key that was already set."""
+    _search_config(tmp_path, key=key, off=off)
+
+    payload = json.loads(runner.invoke(app, ["doctor", "--json"]).stdout)
+    row = next(c for c in payload["tools"]["capabilities"] if c["tool"] == "web_search")
+
+    assert row["configured"] is configured
+    assert row["disabled"] is disabled

tests/test_tool_capabilities.py

@@ -21,6 +21,8 @@
     configured_from,
     has_credential,
     is_configured,
+    is_disabled,
+    is_offered,
 )
 from raven.config.loader import load_config
 from raven.providers.base import LLMProvider, LLMResponse
@@ -318,3 +320,49 @@ def test_only_the_media_family_borrows(tmp_path: Path) -> None:
 
     for cap in (c for c in CAPABILITIES if not c.media_attr):
         assert borrowable_credential(cap, config) == "", cap.tool
+
+
+def test_a_switched_off_tool_is_configured_and_still_not_offered(workspace, tmp_path: Path) -> None:
+    """The combination the report used to get wrong.
+
+    A key is set, so the credential gate is satisfied and saying "unconfigured"
+    would send the deployer to set it again. What decides whether the agent
+    holds the tool is `tools.disabledTools`, applied after registration -- so
+    the predicate that has to agree with the registry is `is_offered`, not
+    `is_configured`.
+    """
+    config = _config(tmp_path)
+    config.tools.web.search.api_key = "sk-serper"
+    config.tools.disabled_tools = ["web_search"]
+    # Passed in, the way the CLI entry points do: the loop takes the list as an
+    # argument rather than reading the config.
+    loop = _loop(workspace, config, brave_api_key="sk-serper", disabled_tools=config.tools.disabled_tools)
+    cap = next(c for c in CAPABILITIES if c.tool == "web_search")
+
+    assert loop.tools.has("web_search") is False
+    assert is_configured(cap, config) is True
+    assert is_disabled(cap, config) is True
+    assert is_offered(cap, config) is loop.tools.has("web_search")
+
+
+@pytest.mark.parametrize("cap", CAPABILITIES, ids=lambda c: c.tool)
+def test_being_offered_matches_the_registry_for_every_capability(cap, workspace, tmp_path: Path) -> None:
+    """Every entry, switched on and then off by name, against the real loop.
+
+    Parametrised rather than written for web_search alone: the disabled list
+    covers any tool, and a family that stops agreeing is exactly the drift the
+    rest of this file exists to catch.
+    """
+    config = _config(tmp_path)
+    config.tools.web.search.api_key = "sk-serper"
+    for attr in _media_attrs():
+        getattr(config.tools.media, attr).model = "some/model"
+    config.providers.openrouter.api_key = "sk-or-test"
+
+    on = _loop(workspace, config, brave_api_key="sk-serper")
+    assert is_offered(cap, config) is on.tools.has(cap.tool)
+
+    config.tools.disabled_tools = [cap.tool]
+    off = _loop(workspace, config, brave_api_key="sk-serper", disabled_tools=config.tools.disabled_tools)
+    assert is_offered(cap, config) is off.tools.has(cap.tool)
+    assert off.tools.has(cap.tool) is False