mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(learn): run the claude-cli analysis with hooks disabled (#3926)
## Description
`headroom learn`'s claude-cli backend runs `claude -p` as the user, so
the user's hooks (from settings files and installed plugins) run inside
the analysis session. #3892 took the session's tools away; this takes
its hooks away. A blocking Stop hook makes Claude take a second turn
whose reply becomes the final `result`, replacing the analysis, so learn
finds no rules and prints "No actionable patterns found." with exit 0
and no error.
The fix passes `--settings '{"disableAllHooks":true}'`. `--settings` is
merged on top of the user's own settings, which still load, so env
routing (`ANTHROPIC_BASE_URL` in settings) and OAuth keep working.
`--bare` would also skip hooks but never reads OAuth or the keychain.
Closes #3925
## 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`: add `--settings
'{"disableAllHooks":true}'` to the claude-cli entry in `_CLI_BACKENDS`,
with a comment on why hooks must be off and why `--bare` is not used.
- `tests/test_learn/test_analyzer.py`:
`test_claude_cli_streams_and_parses_result_event` pins the new argv.
## 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
Ran on the changed files only (`ruff check`/`ruff format --check` on the
two changed files, `mypy headroom/learn/analyzer.py`), not the whole
tree. The existing argv test was updated rather than a new one added.
### Test Output
Before the fix (updated test against upstream/main's analyzer):
```text
$ pytest tests/test_learn/test_analyzer.py -q -x -k test_claude_cli_streams_and_parses_result_event
E AssertionError: assert ['claude', '-...essages', ...] == ['claude', '-...essages', ...]
E Right contains 2 more items, first extra item: '--settings'
FAILED tests/test_learn/test_analyzer.py::TestCallCliLlm::test_claude_cli_streams_and_parses_result_event
======================= 1 failed, 96 deselected in 3.35s =======================
```
After:
```text
$ pytest tests/test_learn/test_analyzer.py tests/test_learn/test_error_classification.py -q
============================= 101 passed in 4.19s ==============================
$ ruff check headroom/learn/analyzer.py tests/test_learn/test_analyzer.py
All checks passed!
$ ruff format --check headroom/learn/analyzer.py tests/test_learn/test_analyzer.py
2 files already formatted
$ mypy headroom/learn/analyzer.py
Success: no issues found in 1 source file
```
## Real Behavior Proof
- Environment: macOS 27, Python 3.12, Claude Code 2.1.287 logged in with
a subscription (OAuth), upstream/main d5318ac2 vs this branch.
- Exact command / steps: a temp project whose `.claude/settings.json`
has a Stop hook that logs each firing and blocks the first stop (script
in the linked issue). From that directory, a script takes the claude-cli
argv from `_CLI_BACKENDS` and calls the real
`_call_claude_cli_streaming(cmd, prompt, ...)` against the real `claude`
binary, with the prompt `Reply with exactly this JSON and nothing else:
{"context_file_rules": [{"section": "Proof", "content": "analysis
survived"}], "memory_file_rules": []}`.
- Observed result: before the fix the Stop hook ran twice and its forced
second turn replaced the analysis; with it the hook never ran and the
analysis came back intact (output below).
Before (upstream/main): the hook ran twice and its forced second turn
replaced the answer.
```text
argv: ['claude', '-p', '--output-format', 'stream-json', '--verbose',
'--include-partial-messages', '--tools', '', '--strict-mcp-config']
parsed result: {'context_file_rules': [], 'memory_file_rules': []}
stop-hook-fired.log: fired (blocked) 15:11:48
fired (allowed) 15:11:50
```
After (this branch): the hook never ran and the analysis came back
intact.
```text
argv: ['claude', '-p', '--output-format', 'stream-json', '--verbose',
'--include-partial-messages', '--tools', '', '--strict-mcp-config',
'--settings', '{"disableAllHooks":true}']
parsed result: {'context_file_rules': [{'section': 'Proof', 'content':
'analysis survived'}], 'memory_file_rules': []}
stop-hook-fired.log: (absent: hook never ran)
```
Settings still load: with `"model": "haiku"` added to the same project
`settings.json`, the same argv's `system/init` event reports the model
from that file while the file's Stop hook stays silent, and auth is the
subscription login (`apiKeySource: none`):
```text
init: {'model': 'claude-haiku-4-5-20251001', 'apiKeySource': 'none',
'tools': [], 'mcp_servers': []}
result: {"ok": true}
stop-hook-fired.log: (absent: hook never ran)
```
- Not tested: a hook defined by an installed plugin (as opposed to a
settings file) in this exact setup; `disableAllHooks` is documented to
cover both and the field report was a plugin hook. Managed (enterprise
policy) hooks: a user-level `disableAllHooks` is not expected to
override managed hooks, so those may still run. Did not run a full
`headroom learn` end to end against real session history; the proof
drives the analyzer's claude-cli runner directly with a tiny prompt.
Windows and Linux not tested.
## Runtime Rollout Safety
- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a, not rollout-managed.
- Stable/default behavior changed: yes, for the claude-cli learn backend
only: the analysis `claude -p` session no longer runs the user's hooks.
Nothing outside `headroom learn` is affected.
- Kill switch / disable path: none added. The analysis session has no
tools and returns one JSON object, so no hook has a legitimate job in
it; auth and routing come from settings, which still load.
- Unsafe override required: no.
- Qualification impact: none; learn analysis only, no proxy, compression
or cache 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 doc lists the claude-cli argv, so there is nothing
to update.
- Follow-up to #3892, which added `--tools ""` and `--strict-mcp-config`
to the same command.
- Headroom Desktop has shipped this flag as a downstream patch to the
pinned wheel; this upstreams it.
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3926"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
JD Davis
parent
e0e41cd2f5
commit
2a4d34c476
@@ -67,6 +67,11 @@ _MIN_DIGEST_TOKENS = 10_000
|
||||
# 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.
|
||||
# --settings '{"disableAllHooks":true}' turns off hooks from settings and
|
||||
# plugins alike. A blocking Stop hook otherwise forces a second turn whose reply
|
||||
# replaces the analysis as the final result, so learn finds no rules and reports
|
||||
# "No actionable patterns found" with no error. The user's own settings still
|
||||
# load (env routing, auth), which --bare would not do: it skips OAuth.
|
||||
_CLI_BACKENDS: list[tuple[str, str, list[str]]] = [
|
||||
(
|
||||
"claude",
|
||||
@@ -81,6 +86,8 @@ _CLI_BACKENDS: list[tuple[str, str, list[str]]] = [
|
||||
"--tools",
|
||||
"",
|
||||
"--strict-mcp-config",
|
||||
"--settings",
|
||||
'{"disableAllHooks":true}',
|
||||
],
|
||||
),
|
||||
("gemini", "gemini-cli", ["gemini", "-p"]),
|
||||
|
||||
@@ -795,6 +795,8 @@ class TestCallCliLlm:
|
||||
"--tools",
|
||||
"",
|
||||
"--strict-mcp-config",
|
||||
"--settings",
|
||||
'{"disableAllHooks":true}',
|
||||
]
|
||||
|
||||
def test_claude_cli_progress_callback_is_throttled(self):
|
||||
|
||||
Reference in New Issue
Block a user