feat(v3): pin plugin to CLI v3.0+ · SessionStart enforcement hook#183
Merged
Conversation
- plugin.json: bump 2.4.14 → 3.0.0 (major break) + add requires.cli ">=3.0.0". Restores the pin from PR #180 (reverted in #181 pending CLI GA); CLI v3.0.0 shipped today (2026-05-22). - hooks/hooks.json + hooks/check-cli-version.sh: SessionStart hook that blocks the session when `onebrain --version` is < v3.0.0 or absent. Emits decision:block JSON with platform-specific install/update paths (brew tap on macOS, GitHub Releases for Linux/Windows, `onebrain update` for in-place refresh). - Version comparison strategy: grep MAJOR.MINOR.PATCH (drops prerelease suffixes) then sort -V. Practical effect: v3.0.0-alpha.x users pass (they're on the Rust binary already), only v2.x Bun-era is blocked. - PLUGIN-CHANGELOG: v3.0.0 entry (max 8 bullets per repo style). NOT in this PR (bundled into the Saturday plugin trim PR): plugin README rewrite · repo trim to plugin-only · PLUGIN-CHANGELOG.md → CHANGELOG.md rename. Scoped strictly to the pin + runtime enforcement. Tested locally: - alpha.9 (current local CLI) → silent pass, exit 0, no JSON - missing onebrain on PATH → decision:block with install paths - mock v2.3.3 CLI → decision:block with update paths
Round-1 review consensus (Reviewer A+B) flagged `sort -V` as a GNU coreutils extension that may be absent from older macOS BSD `sort` builds — on those hosts the comparison falls through (LOWEST="") and the hook would block EVERY session on macOS regardless of installed CLI version. Live test on macOS Darwin 25.4 showed `sort -V` works there, but the fix is cheap defensive coding: replace `sort -V` with a pure-bash MAJOR.MINOR. PATCH integer compare. Works on every POSIX shell, no dependency on GNU extensions. Also Reviewer C (MED): - hooks/hooks.json: add `timeout: 10` so a slow `onebrain --version` (e.g. network-mounted binary) can't hang Claude Code session startup indefinitely. Matches the `hookify` marketplace pattern. - PLUGIN-CHANGELOG: softened "blocks any session" claim — script can only emit decision:block JSON; actual session refusal depends on Claude Code honoring the payload. The CHANGELOG now reflects that contract. - PLUGIN-CHANGELOG: removed the specific "Saturday 2026-05-23" date from the follow-up commitment — references the work generically since calendar promises rot if the PR slips. Tested locally with 4 scenarios: - alpha.9 (current) → silent pass - missing CLI → decision:block with install paths - mock v2.3.3 → decision:block with update paths - mock v10.0.0 → silent pass (integer compare handles 10 > 3 correctly)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Pairs with the OneBrain CLI v3.0.0 GA released earlier today (2026-05-22):
plugin.json: bump2.4.14→3.0.0(major break) + re-addrequires.cli: ">=3.0.0". Restores the pin from PR feat: pin plugin to CLI v3.0 (Rust) #180, which was reverted in PR chore: revert PR #180 (pin plugin to CLI v3.0) — redo after CLI GA #181 pending CLI GA.hooks/hooks.json+hooks/check-cli-version.sh: new SessionStart hook that blocks any Claude Code session running this plugin alongside anonebrainCLI older than v3.0.0 (or absent entirely). The plugin'srequires.clifield is metadata for tooling; this hook is the runtime enforcement.PLUGIN-CHANGELOG.md: v3.0.0 entry (max 8 bullets per repo style).What's NOT in this PR
Bundled into the Saturday 2026-05-23 plugin trim PR per single-responsibility:
CHANGELOG.mdout)PLUGIN-CHANGELOG.md→CHANGELOG.mdSessionStart hook design
Practical effect:
decision: blockwith platform-specific update pathsonebrainnot on PATH →decision: blockwith install pathsThe block reason copy points at the Homebrew tap (
onebrain-ai/homebrew-onebrain, shipped earlier today), GitHub Releases, and theonebrain updateself-installer.Local tests
Hook script also handles the edge case where
onebrain --versionexists but the output can't be parsed (emits a "could not parse" block).Test plan
onebrain vault-syncin this vault to apply the new plugin, then restart Claude Code session and confirm the hook is registered (no block since current CLI is alpha.9 → passes)