Files
Rod BoevandJerrettDavis ef7605fdbb fix(plugin): resolve hook CLI through plugin-root launcher (#3053)
## Description

The `headroom` plugin invokes `headroom init hook ensure` through
non-login `/bin/sh`, but both `SessionStart` and `PreToolUse` entries
use a bare executable name. Agent hosts whose PATH omits the default
uv/pipx user bin exit 127 on every matching event. Tool calls continue
because the hook is non-blocking, while Headroom compression remains
inactive and the failure banner repeats.

Both hooks now invoke one launcher bundled under `${CLAUDE_PLUGIN_ROOT}`
through `sh`. The launcher honors `HEADROOM_BIN`, preserves
PATH-resolved installations, covers standard uv and pipx prefixes,
records the Homebrew candidates for macOS, and falls back to an
importable Python module. On the launcher-routed path, an absent
Headroom CLI emits one actionable diagnostic and exits 0. Hosts that do
not expose a readable plugin root retain the existing bare-command tail,
preserving the shared GitHub Copilot CLI manifest behavior.

Reported by [@donnydongchen](https://github.com/donnydongchen), whose
exact non-login `env -i` reproduction, Apple Silicon path detail, and
plugin-root suggestion shaped the fix.

Closes #3039

## 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

- Route both plugin hook entries through a shared
`${CLAUDE_PLUGIN_ROOT}`-anchored `sh` launcher while preserving
matchers, arguments, and 60-second timeouts.
- Require a non-empty plugin root before probing the launcher, so unset
or empty roots always reach the existing bare-command tail.
- Resolve `HEADROOM_BIN`, PATH, standard uv/pipx/Homebrew locations, and
an importable `python -m headroom.cli` fallback in a deterministic
order.
- Preserve the current bare command for hosts without a readable plugin
root, including the shared Copilot CLI manifest path.
- On the launcher-routed path, replace the absent-CLI status-127 banner
with one actionable diagnostic and a non-blocking exit.
- Add real-shell regression coverage for the reported environment,
resolution precedence, supported prefixes, Python fallback, and negative
boundaries.

## Testing

- [x] Unit tests pass (`uv run --extra dev python -m pytest
tests/test_plugin_manifests.py tests/test_plugin_hook_launcher.py
tests/test_cli/test_init_cli.py -q`, `98 passed`)
- [x] Reproduction override passes (`HEADROOM_REPRO_ARTIFACT` can select
the issue fixture, `uv run --extra dev python -m pytest
tests/test_plugin_hook_launcher.py::test_manifest_command_recovers_reported_non_login_environment
-q`, `1 passed`)
- [x] Linting passes (Ruff check and format validation on the changed
Python test files)
- [ ] Type checking passes (`uv run mypy headroom`)
- [x] New tests added for new functionality when applicable
- [ ] Manual testing performed

### Test Output

```text
98 passed
All checks passed!
2 files already formatted
```

## Real Behavior Proof

- Environment: POSIX `sh` with the reporter's sanitized non-login PATH
and a recording Headroom executable only at `$HOME/.local/bin/headroom`
- Exact command / steps: `uv run --extra dev python -m pytest
tests/test_plugin_hook_launcher.py::test_manifest_command_recovers_reported_non_login_environment
-q`; the test preserves the reported PATH and error evidence, executes
both manifest commands with a recorder at `$HOME/.local/bin/headroom`,
and asserts both `home-local init hook ensure` receipts.
- Observed result: `1 passed in 0.41s`; both hooks recovered under the
reported non-login PATH and emitted no command-not-found banner.
- Not tested: live Claude Code plugin-hook execution on a macOS tmux
host

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: plugin hooks resolve Headroom through
the bundled launcher when the plugin root is readable; invalid launcher
roots retain the existing bare-command fallback.
- Kill switch / disable path: none; the existing bare-command fallback
remains available when the plugin root is absent or unreadable.
- Unsafe override required: none.
- Qualification impact: none.
- Rollback path: revert the implementation 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
- [x] 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

## Screenshots (if applicable)

Not applicable; this PR changes plugin hook startup behavior without a
rendered UI.

## Additional Notes

The launcher does not source shell profiles, install packages, access
the network, change deployment/profile selection, or modify plugin
versions.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3053"
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 -->

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-05 08:35:35 -05:00
..