fix(codex): survive plugin cache refreshes - #240
Merged
Conversation
…-scoped checkpoint reset The SessionStart-injected identity contract had over-generalized Codex's terminal-fallback danger onto Claude/Gemini, disabling their legitimate session init fallback (their tokens derive from harness env like CLAUDE_CODE_SESSION_ID and are chat-unique). Split every fallback/disable rule in INSTRUCTIONS.md by harness: Claude/Gemini recover via `session init --json` and treat the result as authoritative; Codex keeps checkpoint/wrapup disabled and never mints a replacement token. Also align skill docs with the companion CLI's new `checkpoint reset --session-token <TOKEN>` flag, and apply the same harness split wherever a skill told the agent to recover identity via session init.
Codex and Gemini hook manifests called bare `onebrain hook` with no
version gate. A CLI older than 3.4.25 has no `hook` subcommand, so it
exits 2 (clap usage error) — the blocking exit code in the hook
protocol — contradicting the "every hook is fail-open" and "rollback
disables these hooks" claims. Claude is protected by its
check-cli-version.sh SessionStart gate; Codex and Gemini had neither a
gate nor a fallback.
Wrap each command in a shell-level `|| echo` fallback: SessionStart
echoes a warning additionalContext when `onebrain hook` fails,
PostToolUse/Stop echo `{}`. Update check-lifecycle-hooks.py to assert
the exact wrapped strings and add rollback smoke cases (missing CLI,
CLI without the hook subcommand) pinning that the fallback returns
exit 0 with the expected stdout.
…r; Gemini joins the no-mint rule; wrap Claude hooks
Round-2 review findings:
- Claude's session-identity fallback now re-runs `session init --json` with
ONEBRAIN_HOOK_SESSION_ID set to CLAUDE_CODE_SESSION_ID, so the recovered
session_token is provably the same sha256[..16] token the Stop hook
increments (empirically verified against the CLI resolver). Gemini moves
into the same no-mint bucket as Codex: its resolver has no harness-session
env layer, so a terminal/process/day-scoped fallback token could merge
chats.
- hooks.json's Claude SessionStart generic hook is now wrapped in the same
`onebrain hook || echo '{}'` fail-open fallback Codex and Gemini already
use, so a pre-3.4.25 or missing CLI degrades gracefully instead of exiting
2 (Claude's check-cli-version.sh gate remains the messaging layer).
check-lifecycle-hooks.py updated in lockstep, its Gemini commandWindows
absence now asserted explicitly, and the Windows-string limitation is
documented near the commandWindows constants.
- Stale "bare onebrain hook" / "no wrapper needed" prose in GEMINI.md and
CONTRIBUTING.md corrected to describe the fail-open wrapper.
- Skills now spell the preserved `{resolved executable}` placeholder instead
of bare `onebrain` for session init / checkpoint reset recovery commands,
and the stale `SESSION_TOKEN` key reference is corrected to `session_token`.
CHANGELOG.md's existing v3.4.12 bullets updated in place (same count) to
match.
… scope wrapper claims accurately
Round-3 audit fixes:
- Mid-session Claude token recovery (INSTRUCTIONS.md Auto Checkpoint section,
pause/wrapup/AUTO-SUMMARY SKILL.md, session-formats.md) now calls the
resolve-only `session token --json` instead of `session init --json`.
`session init` deletes the Stop-hook cadence state file whenever it runs
mid-session, so recovery must not use it; Step 1's startup fallback keeps
`session init` on purpose since a fresh session needs that state-clean
side effect and the full startup metadata.
- Corrected the inverted fail-open description: the `|| echo` wrapper is
inert once the installed CLI is 3.4.25+, and degrades to a harmless
stand-in payload when the CLI is missing or older (INSTRUCTIONS.md).
- Rescoped "all three harnesses wrapped" claims (CHANGELOG.md, CONTRIBUTING.md,
INSTRUCTIONS.md): only Codex's and Gemini's entries plus Claude's
SessionStart are plugin-shipped and wrapped in `|| echo`. Claude's
PostToolUse/Stop entries are CLI-registered into the vault's
.claude/settings.json in exec form and can't carry a shell `||`; those
are covered by the check-cli-version.sh SessionStart gate instead.
- Dropped stale "bare" wording in migration-steps.md's /update hook
registration step, mirroring the corrected CONTRIBUTING.md phrasing.
- Quoted the `{resolved executable}` placeholder in every recovery/reset
one-liner (POSIX and PowerShell forms) so paths with spaces don't break.
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
ONEBRAIN_HOOK_SESSION_IDlayer using the resolve-onlysession token --jsonverb mid-session (leaves the Stop-hook cadence counter untouched; startup fallback keepssession init), Gemini and Codex never mint one, and everycheckpoint resetpasses--session-token {session_token}via the preserved executableonebrain hookcommands in a shell-level|| echofail-open fallback (Claude'scheck-cli-version.shgate stays the user-facing message), pinned by missing-CLI and old-CLI rollback smokes in check-lifecycle-hooks.pyVerification
Dependency and rollout
Depends on onebrain-ai/onebrain-cli#396.
Release CLI v3.4.25 through supported installation channels before merging or releasing plugin v3.4.12. Rolling the CLI back below 3.4.25 degrades Codex/Gemini lifecycle hooks to an inert SessionStart warning (the shell fallback, verified by the rollback smokes), while Claude blocks at session start via check-cli-version.sh — restore CLI >= 3.4.25 to re-enable.