feat(hook): orient hook script + setup docs (CLA-105)#36
Merged
JuzzyDee merged 4 commits intoMay 22, 2026
Merged
Conversation
Adds the SessionStart/PreCompact hook that defeats the bootstrap-
failure pattern at the structural level. Fresh Claude Code instances
no longer have to decide whether to call recall_orient before
evaluating tools — the orientation payload arrives in their context
before any tool evaluation fires, so the substance is already in
scope when they make any decision about what to do.
* scripts/oneiro-orient.sh — POSIX bash, exits 0 silently on any
failure (missing config, unreachable worker, auth rejection).
A misconfigured hook will never break a session. Auth from
ONEIRO_ORIENT_TOKEN env first (explicit override), then macOS
keychain (`oneiro-orient` service name) as the persistent
no-env-leakage default.
* README — new subsection under Quick Start documenting both auth
options (keychain recommended) and the settings.json snippet for
wiring the SessionStart + PreCompact hooks.
Settings.json wiring is per-user local config and intentionally
outside this commit. The README has the snippet; the update-config
skill (or a manual edit) handles the install.
Smoke test passed: orientation payload comes through via the worker
endpoint with the new service key. Hook in Claude Code itself fires
on next session start once the settings watcher reloads.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
💤 Files with no reviewable changes (1)
📝 WalkthroughWalkthroughThis PR adds an orientation hook for Claude Code sessions: a Bash script that fetches orientation context from a worker endpoint using a token from environment or macOS keychain, and README docs showing how to wire and authenticate the hook; failures exit silently so sessions continue. ChangesOrient Hook Integration
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
scripts/oneiro-orient.sh (1)
44-50: 💤 Low valueConsider removing the redundant
--show-errorflag.The
--show-errorflag on line 47 displays error messages even with--silent, but stderr is redirected to/dev/nullon line 49, so error messages are suppressed anyway. The flag has no effect in this configuration.♻️ Proposed simplification
-curl --silent --fail --show-error --max-time 10 \ +curl --silent --fail --max-time 10 \ --header "Authorization: Bearer ${TOKEN}" \ "${WORKER_URL%/}/orientation" 2>/dev/null \ || exit 0🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/oneiro-orient.sh` around lines 44 - 50, The curl invocation building the orientation request includes --show-error but stderr is redirected to /dev/null, making that flag redundant; update the curl command in the script (the curl ... "${WORKER_URL%/}/orientation" invocation) to either remove --show-error or stop redirecting stderr so the flag has an effect—preferably remove the --show-error token from the curl arguments to simplify the command.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 67-80: Add a short subsection before "Install the orient hook"
that shows how to create and use service API keys: instruct users to generate a
random plaintext key (e.g., with openssl rand -base64 32), explain that this
plaintext key is what the hook expects in ONEIRO_ORIENT_TOKEN or the macOS
keychain entry, and show how to derive the hashed entry for ONEIRO_API_KEYS
(mention using an argon2 hashing tool or the repository's provided hash script
to produce semicolon-separated role:argon2-hash entries for wrangler secret put
ONEIRO_API_KEYS); finally, briefly clarify the difference between OAuth tokens
(used by interactive clients) and these service keys (used by non-interactive
hooks and workers) so readers understand which credential goes where.
- Around line 67-72: Add a brief platform note after the "Option A — macOS
keychain (recommended; no env leakage)" block clarifying that the `security`
command is macOS-only and that Linux/Windows users should use "Option B"
(environment variables) as the cross-platform alternative; reference the
"security" command and the Option A/Option B headings so the note is inserted
immediately after the Option A code block.
In `@scripts/oneiro-orient.sh`:
- Around line 36-42: The keychain lookup for TOKEN uses security
find-generic-password without specifying the account, which can return the wrong
entry; update the security invocation used to populate TOKEN (the command
substitution that assigns TOKEN when command -v security succeeds) to include
the account flag (-a "$USER") so it matches the documented keychain entry and
ensures the correct credential is retrieved.
---
Nitpick comments:
In `@scripts/oneiro-orient.sh`:
- Around line 44-50: The curl invocation building the orientation request
includes --show-error but stderr is redirected to /dev/null, making that flag
redundant; update the curl command in the script (the curl ...
"${WORKER_URL%/}/orientation" invocation) to either remove --show-error or stop
redirecting stderr so the flag has an effect—preferably remove the --show-error
token from the curl arguments to simplify the command.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 370068d9-7c6f-44a9-88dd-cc14e058312c
📒 Files selected for processing (2)
README.mdscripts/oneiro-orient.sh
…lag, document service key generation (CLA-105) Three small follow-ups from CodeRabbit on PR #36. Skipped the "note that macOS keychain is macOS-only" suggestion — anyone reading "macOS keychain" who needs that explanation is below the floor of this hook's audience. * scripts/oneiro-orient.sh — keychain lookup now pins `-a "$USER"` so it matches how `security add-generic-password` stored it. Without it, a different `oneiro-orient` entry under another account could shadow the right one. Niche but consistent with how the docs say to store the entry. * scripts/oneiro-orient.sh — dropped `--show-error` from the curl invocation. The flag is a no-op when stderr is redirected to /dev/null (which we do deliberately for silent-no-op failure semantics). Comment added so the intent is preserved. * README — new "Generating a service API key" subsection between "Install the skill" and "Install the orient hook". Documents the actual `cargo run --bin oneiro -- keygen --role rover` workflow (CodeRabbit suggested openssl + manual argon2 hashing, which isn't how this repo's keys work) and explains the OAuth-vs- service-key distinction so readers know which credential goes where. Also notes that multiple `rover:` hashes can coexist in ONEIRO_API_KEYS so callers can be rotated independently. Tested: script with keychain entry returns the live orientation payload from the deployed worker. Auth + endpoint + script all clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/oneiro-orient.sh`:
- Around line 40-42: The script fails under set -u because the USER expansion in
the security keychain lookup is unguarded; change the invocation that uses -a
"$USER" to use a safe default (e.g., -a "${USER:-}") so the expansion never
triggers an unbound-variable error and the TOKEN lookup still silently returns
empty on failure; update the line using TOKEN, ONEIRO_ORIENT_TOKEN and the
security command to use the guarded ${USER:-} expansion to preserve the silent
no-op / exit-0 behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: f708e11c-c999-4e69-bd45-16d257efeb60
📒 Files selected for processing (2)
README.mdscripts/oneiro-orient.sh
✅ Files skipped from review due to trivial changes (1)
- README.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/oneiro-orient.sh`:
- Around line 41-45: The script contains an extra unmatched "fi" that causes a
syntax error; locate the conditional block that checks TOKEN and calls the
security command (the lines using TOKEN, command -v security, and security
find-generic-password) and remove the stray "fi" that immediately follows that
block so the if..then..fi structure is balanced (leave the final "[ -z
\"$TOKEN\" ] && exit 0" check intact).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 53bbba62-dfcc-4b80-8d0a-fcba561ba66c
📒 Files selected for processing (1)
scripts/oneiro-orient.sh
…105)
CodeRabbit's "commit suggestion" for the ${USER:-} guard appended a
new `fi` on top of the existing one, producing a double-fi syntax
error that broke the script entirely. Confirmed via `bash -n`:
"syntax error near unexpected token `fi`".
The ${USER:-} change itself is correct and kept — set -u would
otherwise terminate the script on unset USER, violating the
documented silent-no-op contract. Just the duplicated terminator
needed removing.
CodeRabbit then flagged its own broken suggestion in a follow-up
review, which is what surfaced this. The bot is, charitably,
stateless across reviews.
Validated:
- bash -n clean
- Pipe-test returns the live orientation payload (341/97/20)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
JuzzyDee
deleted the
juzzydee/cla-105-orient-hook-auto-inject-orientation-on-sessionstart-and
branch
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
Adds the SessionStart/PreCompact hook that defeats the bootstrap-failure pattern at the structural level. Fresh Claude Code instances no longer have to decide whether to call
recall_orientbefore evaluating tools — the orientation payload arrives in their context before any tool evaluation fires.scripts/oneiro-orient.sh— POSIX bash. Exits 0 silently on any failure (missing config, unreachable worker, auth rejection). A misconfigured hook will never break a session. Auth fromONEIRO_ORIENT_TOKENenv first, then macOS keychain (oneiro-orientservice name) as the persistent no-env-leakage default.Settings.json wiring is per-user local config and intentionally outside this commit. The README has the snippet; install via the
update-configskill or a manual edit.Why
Per CLA-103 context: fresh instances often don't surface or call
recall_orientbefore evaluating tools. Even when they do, the SKILL.md instruction loses against the system prompt's auto-memory section, which gives instances a competing prescription before they ever read the skill. The hook converts SKILL.md from a hopeful prescription into a structural guarantee — orientation is in scope before any heuristic gate fires.Test plan
/compact: confirm orientation re-injectsLinked tickets
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
New Features