cli: stamp agent hook configs and warn when they fall behind

[gtrrz-victor]

Summary

Adds CLI version tracking to every agent's installed hook configuration, then surfaces a clear "your hooks are out of date" warning the next time the user runs any visible entire command.

Until now there was no signal anywhere — when a CLI release changed hook wiring, existing users kept running stale hooks silently until something failed cryptically. This PR closes that loop.

Example

Claude code settings:

Warning shown on every entire command:

What it does

1. Stamp every agent hook config with the CLI version that wrote it.

entire enable (and entire configure) now writes a top-level entireMeta.cli_version field into each installed agent's config:

• .claude/settings.json
• .cursor/hooks.json
• .codex/hooks.json
• .github/hooks/entire.json (Copilot CLI)
• .factory/settings.json
• .gemini/settings.json
• .opencode/plugins/entire.ts (as a // entireMeta: {...} comment line — TS, not JSON)

A new agent.HookVersionSupport capability lets drift.go read the stamp back without knowing the concrete config format. JSON agents share WriteJSONHookMeta / ReadJSONHookMeta; OpenCode's TS plugin uses TSHookMetaCommentLine / ReadTSHookMeta.

2. Detect drift against a single global floor.

agent.CheckHookDrift(ctx) walks every registered agent with hooks installed and reports any whose stamp normalizes below agent.MinCompatibleCLIVersion. Missing/unreadable stamps are treated as v0.0.0, which collapses the "no stamp at all" and "stamp older than floor" cases through the same semver.Compare gate.

The floor is one package-level constant in cmd/entire/cli/agent/hook_command.go, seeded at "0.0.0" so no drift warnings fire today. Bump it exactly when a hook-contract change in any agent warrants forcing users to re-run entire enable --force.

Dev builds (versioninfo.Version == versioninfo.DevVersion) short-circuit drift detection entirely.

3. Surface the warning broadly and clearly.

A root-level PersistentPreRun (cli.driftWarningPreRun) prints a yellow two-line warning on stderr before every visible subcommand:

Action required: agent hooks need updating (claude-code)
  Run: entire enable --force

Action-first wording — no "stale", no abstract "hooks". The user knows what to run.

The sessions command defines its own PersistentPreRunE, which Cobra does not chain to root's, so sessions.go calls driftWarningPreRun explicitly after its git-repo guard.

Skip rules

The warning is suppressed when any of:

• The target command (or any ancestor) has Hidden: true. Covers internal / machine-invoked commands (entire hooks, entire migrate, dev helpers).
• The target is the root command itself (bare entire prints help or runs first-time setup; neither is the right surface).
• The target is entire enable / entire configure invoked with --force=true. The user is already running the exact remediation the warning would suggest. The check inspects the resolved boolean (Flags().GetBool), not just flag.Changed, so a wrapper that passes --force=false explicitly still gets the warning.
• The current directory is outside a git worktree. Otherwise a non-repo dir with a stray .claude/ could warn and then the command itself would bail with "not a git repository".
• Stderr is not a TTY. Scripted / CI callers shouldn't have their stderr polluted.
• The CLI is a dev build (covered by CheckHookDrift's own short-circuit).

Forcing a re-stamp

Two ways to upgrade an old install:

• entire enable --force — explicit, the message tells the user this.
• entire enable against a config with no stamp at all (a pre-stamp install) is automatically promoted to a force-reinstall, so the first enable after this lands re-stamps without ceremony.

Test plan

• go test ./cmd/entire/cli/... -race — unit tests cover the skip predicate, the renderer, and driftWarningPreRun with stubbed drift / TTY / git-repo so every gate is exercised including the positive emit path.
• mise run lint — 0 issues.
• Manual drift cycle via pty in a fixture repo:
  • built CLI with Version=1.0.0 via ldflag, bumped MinCompatibleCLIVersion to 0.9.0, edited .claude/settings.json to stamp entireMeta.cli_version = "0.0.1-stale".
  • visible commands (entire rewind, entire status, entire sessions list): yellow two-line warning on stderr.
  • hidden commands (entire hooks claude-code pre-task): silent.
  • non-TTY stderr (entire rewind 2>/tmp/x): silent.
  • entire enable --force: re-stamps to 1.0.0, subsequent entire status is clean.
• E2E canary (mise run test:e2e:canary) — kicked off when this comes out of draft.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Broadens hook-drift (“stale hooks”) visibility across the Entire CLI by adding a root-level warning path and a shared renderer, while extending hook config stamping/reading to support drift detection across agents (including OpenCode’s TS plugin).

Changes:

• Wire a root PersistentPreRun (driftWarningPreRun) to emit a TTY-only stale-hooks warning for visible commands, and ensure entire sessions * still triggers it.
• Add a shared warning renderer (staleHooksWarningLines / emitStaleHooksWarning) and integrate the warning into entire status output.
• Introduce/extend hook metadata stamping + drift detection utilities (entireMeta.cli_version) across multiple agents, plus tests.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cmd/entire/cli/root.go	Adds root PersistentPreRun to run drift warning logic broadly.
cmd/entire/cli/sessions.go	Ensures sessions subtree still runs drift warning despite its own PersistentPreRunE.
cmd/entire/cli/status.go	Integrates stale-hooks warning lines into status short output.
cmd/entire/cli/drift_warning.go	Implements skip predicate, renderer, and pre-run emission logic.
cmd/entire/cli/drift_warning_test.go	Adds unit tests for skip predicate, renderer, and pre-run behavior with injectable TTY/drift stubs.
cmd/entire/cli/agent/drift.go	Adds drift detection across installed agents based on stamped CLI versions.
cmd/entire/cli/agent/drift_test.go	Adds tests for semver normalization and dev-build short-circuit.
cmd/entire/cli/agent/hook_command.go	Adds hook metadata types/helpers and the global compatibility floor constant/interface.
cmd/entire/cli/agent/hook_command_test.go	Adds tests for JSON/TS hook meta read/write round-trips.
cmd/entire/cli/agent/capabilities.go	Adds AsHookVersionSupport capability helper.
cmd/entire/cli/agent/claudecode/hooks.go	Forces reinstall on missing stamp, stamps meta on install, adds ReadHookMeta.
cmd/entire/cli/agent/claudecode/hooks_test.go	Adds tests asserting stamping/backfill/forced reinstall behavior.
cmd/entire/cli/agent/cursor/hooks.go	Forces reinstall on missing stamp, stamps meta, adds ReadHookMeta.
cmd/entire/cli/agent/copilotcli/hooks.go	Forces reinstall on missing stamp, stamps meta, adds ReadHookMeta.
cmd/entire/cli/agent/codex/hooks.go	Preserves top-level keys while stamping meta; adds ReadHookMeta.
cmd/entire/cli/agent/geminicli/hooks.go	Forces reinstall on missing stamp, stamps meta in writer, adds ReadHookMeta.
cmd/entire/cli/agent/geminicli/hooks_test.go	Updates a test fixture to include a current stamp to keep focus on legacy cleanup.
cmd/entire/cli/agent/factoryaidroid/hooks.go	Forces reinstall on missing stamp, stamps meta, adds ReadHookMeta.
cmd/entire/cli/agent/opencode/plugin.go	Adds TS template placeholder for entireMeta JSON.
cmd/entire/cli/agent/opencode/entire_plugin.ts	Adds // entireMeta: __ENTIRE_META_JSON__ stamp line to plugin header.
cmd/entire/cli/agent/opencode/hooks.go	Substitutes meta placeholder during install; adds ReadHookMeta for TS plugin.

[gtrrz-victor]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c179401. Configure here.}