fix(learn): run the claude-cli analysis with no tools (#3892)

## Description

`headroom learn`'s claude-cli backend runs the analysis as `claude -p`,
and a headless `claude -p` is a full Claude Code agent. With Claude Code
2.1.285, its init event lists 127 tools from 7 MCP servers: Bash, Edit,
Task, cron, every claude.ai connector. They run under the user's own
permissions, hooks and skills. The analysis needs none of them, because
the digest is the whole input and the answer is one JSON object.

When the model decides to go read or verify things, the run turns
multi-turn. Each tool call emits stream events, so the idle cap never
fires, and the run is killed at the hard cap with nothing written. We
saw this in the field as `claude -p --output-format stream-json
--verbose exceeded the 900s hard cap` (Headroom Desktop raises the hard
cap to 900s). A normal analysis finishes in seconds to under a minute in
a single turn.

This adds `--tools ""` and `--strict-mcp-config` to the claude-cli
command, so the session has zero tools and answers in one turn. You need
both flags: `--tools ""` alone removes the built-in tools but still
leaves every MCP server's tools.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/learn/analyzer.py`: the `claude-cli` entry of
`_CLI_BACKENDS` now also passes `--tools "" --strict-mcp-config`, with a
comment explaining why.
- `tests/test_learn/test_analyzer.py`:
`test_claude_cli_streams_and_parses_result_event` pins the new command.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_learn/
======================= 320 passed, 4 skipped in 22.78s ========================
$ uvx ruff check headroom/learn/analyzer.py tests/test_learn/test_analyzer.py
All checks passed!
$ uvx ruff format --check headroom/learn/analyzer.py tests/test_learn/test_analyzer.py
2 files already formatted
$ uv run --frozen --extra dev mypy headroom/learn/analyzer.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS 15 (Darwin 24.6), Claude Code 2.1.285 logged in
with OAuth, user settings with plugins, hooks and claude.ai MCP
connectors, this branch run through `uv run`.
- Exact command / steps: (1) Piped `hi` into the old and the new
claude-cli command and read the `system`/`init` stream event. (2) Called
`_call_cli_llm(<small two-call digest>, "claude-cli")` against the real
CLI.
- Observed result: (1) The old command's init event listed 127 tools and
7 MCP servers; the new command's listed 0 tools and 0 MCP servers. (2)
The analysis returned parsed JSON with `context_file_rules` and
`memory_file_rules` in 8.5s.
- Not tested: Windows (the command is still a list passed to Popen, and
the empty `--tools` value is a separate argv entry); Claude Code
versions without `--tools`, which will fail with `unknown option
'--tools'` and need a `claude update`.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; this only changes the learn
claude-cli command.
- Minimum rollout channel: N/A, not rollout-managed.
- Stable/default behavior changed: yes, the learn analysis session runs
with no tools. The recommendations come from the digest alone, as the
prompt already asks.
- Kill switch / disable path: `--model <litellm-model-name>`, or the
gemini-cli or codex-cli backends, skip this command entirely.
- Unsafe override required: no.
- Qualification impact: none; learn is not in the proxy request path.
- Rollback path: revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

- Documentation: no docs describe the claude-cli argv, so there was
nothing to update.
- The existing command test was updated rather than a new one added; it
asserts the exact argv.
- Stop hooks that block can still make a `claude -p` run multi-turn.
Only Claude Code's `--safe-mode` disables hooks under OAuth (`--bare`
needs an API key), and that flag is too new to pass unconditionally.
- Headroom Desktop carries this as a sitecustomize patch until a wheel
with it ships. The patch does nothing when the wheel already passes
either flag.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
gglucass
2026-10-01 15:53:42 -05:00
committed by GitHub
co-authored by Claude Opus 5.5 JerrettDavis
parent 7df8bd87b5
commit db90b93da9
2 changed files with 13 additions and 0 deletions
+10
View File
@@ -60,6 +60,13 @@ _MIN_DIGEST_TOKENS = 10_000
# --include-partial-messages adds incremental "stream_event" ticks during the
# assistant's response; without it claude only emits ~3 events total (system
# init, one assistant message, result) — too sparse to report live progress.
# --tools "" and --strict-mcp-config leave the analysis session with zero tools:
# the digest is the whole input and the answer is one JSON object, but a
# headless `claude -p` is otherwise a full agent (Bash, Edit, Task, every MCP
# server) under the user's own permissions. A model that goes off to read or
# verify things keeps streaming, so the idle cap never fires and the run dies
# at the hard cap with nothing written. Both flags are needed: --tools "" alone
# leaves the MCP servers' tools.
_CLI_BACKENDS: list[tuple[str, str, list[str]]] = [
(
"claude",
@@ -71,6 +78,9 @@ _CLI_BACKENDS: list[tuple[str, str, list[str]]] = [
"stream-json",
"--verbose",
"--include-partial-messages",
"--tools",
"",
"--strict-mcp-config",
],
),
("gemini", "gemini-cli", ["gemini", "-p"]),
+3
View File
@@ -792,6 +792,9 @@ class TestCallCliLlm:
"stream-json",
"--verbose",
"--include-partial-messages",
"--tools",
"",
"--strict-mcp-config",
]
def test_claude_cli_progress_callback_is_throttled(self):