fix(codex): idempotent hooks.json install (stop repeated trust prompts) + README note

[kaghni]

Problem

Recent Codex versions gate hooks behind a "Hooks need review / Trust" prompt, and they fingerprint each hook definition. Our installer rewrote hooks.json unconditionally on every install/update — even when the merged result was byte-identical — which changed the file Codex fingerprints and re-triggered the trust prompt every time. Users had to "Trust all and continue" after every update.

(Evidence it's a definition fingerprint, not script-content: in the field only the 2 hooks whose definitions changed were flagged for review; the 3 with stable definitions stayed trusted across the update.)

Fix

• New writeJsonIfChanged(path, obj) — skips the write when the serialized JSON already matches on disk (returns whether it wrote).
• Codex + Cursor install-time hooks.json writes now use it. Re-installing the same version leaves the file (and its fingerprint) untouched → Codex stops re-asking after the first trust.

Real-world E2E (built bundle/cli.js, sandboxed HOME): install twice → second install leaves hooks.json byte-identical, mtime unchanged, and logs hooks.json unchanged — skipped rewrite (no re-trust prompt).

Docs

Adds a short note to the README Codex section: on first launch, choose "Trust all and continue" or the hooks won't run. (Deliberately does not mention the per-update re-prompt — this PR removes that.)

Tests

• writeJsonIfChanged unit coverage (write / skip / rewrite branches, via mtime pinning).
• Codex-install idempotency guard: a second install does not rewrite hooks.json; plus a guard that the write path still fires when a merge actually changes the file.

Notes

Builds on the merged Windows fix (#221). The first install of a version that genuinely changes a hook definition will still (correctly) prompt once; this only removes the spurious re-prompts from no-op rewrites.

[coderabbitai]

📝 Walkthrough

Walkthrough

README.md documentation has been expanded with a new "First launch — trust the hooks" guidance block explaining that Codex may prompt users to review hooks on first run and after updates. Users are instructed to approve the prompts so Hivemind hooks function, with a note clarifying that declining trust disables Hivemind.

Changes

Codex First Launch Hook Trust Guidance

Layer / File(s)	Summary
First launch — trust the hooks guidance README.md	New section in manual install instructions advises users to trust/approve "Hooks need review" prompts so Hivemind capture/recall/session hooks run on first launch and after hook updates, noting that declining trust keeps Hivemind inactive.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Suggested reviewers

• efenocchi

Poem

🐰 With hooks that whisper, "Please review,"
A rabbit hops to guide you through,
Trust the prompts, let them run,
Hivemind wakes—the work's begun! 🌿✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description comprehensively explains the problem (repeated trust prompts), the fix (idempotent writes), documentation changes, test coverage, and notes. However, it does not include a Version Bump section as required by the template.	Add a Version Bump section indicating the appropriate version bump type (patch for bug fix) and update package.json version accordingly before merging.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The PR title references an idempotent hooks.json install fix and README note, matching the actual changes (README update + fix implementation) described in the summary and description.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/codex-hook-trust-note

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Coverage Report

Scope: files changed in this PR. Enforced threshold: 90% per metric (per file via vitest.config.ts).

Status	Category	Percentage	Covered / Total
🟢	Lines	99.52% (🎯 90%)	208 / 209
🟢	Statements	98.06% (🎯 90%)	253 / 258
🟢	Functions	100.00% (🎯 90%)	49 / 49
🟢	Branches	90.32% (🎯 90%)	140 / 155

File Coverage — 3 files changed

File	Stmts	Branches	Functions	Lines
src/cli/install-codex.ts	🟢 100.0%	🟢 91.2%	🟢 100.0%	🟢 100.0%
src/cli/install-cursor.ts	🟢 96.7%	🔴 86.1%	🟢 100.0%	🟢 100.0%
src/cli/util.ts	🟢 95.5%	🟢 92.8%	🟢 100.0%	🟢 98.0%

_{Generated for commit cf0aba7.}