docs: clarify hook override limitation (issue #226) by pangerlkr · Pull Request #231 · affaan-m/everything-claude-code

pangerlkr · 2026-02-15T03:20:11Z

Update hooks/README.md to clarify that hook override via ~/.claude/settings.json is not currently supported.

The documented override mechanism (adding an entry with empty hooks: [] array) does not work because Claude Code merges configurations rather than replacing them. This is a limitation in Claude Code's core configuration system.

Adds a prominent note explaining this limitation and referencing issue #226.

Related: #226

Description

Type of Change

Checklist

Tests pass locally (node tests/run-all.js)
Validation scripts pass
Follows conventional commits format
Updated relevant documentation

Summary by CodeRabbit

Documentation
- Updated Hooks README to clarify that hook override functionality via configuration files is not currently supported. A note was added explaining this limitation with reference to the related issue. The disabling hook guidance was revised accordingly.

Update hooks/README.md to clarify that hook override via ~/.claude/settings.json is not currently supported. The documented override mechanism (adding an entry with empty hooks: [] array) does not work because Claude Code merges configurations rather than replacing them. This is a limitation in Claude Code's core configuration system. Adds a prominent note explaining this limitation and referencing issue affaan-m#226. Related: affaan-m#226

coderabbitai · 2026-02-15T03:20:28Z

📝 Walkthrough

Walkthrough

Documentation clarification in the Hooks README updates guidance on disabling hooks, removing instructions for overriding via ~/.claude/settings.json and adding an explanatory note about why this override is not currently supported due to configuration merge behavior.

Changes

Cohort / File(s)	Summary
Hooks Documentation `hooks/README.md`	Removed settings.json override instructions and added clarifying note explaining lack of support for this override feature, with reference to Issue `#226`.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

docs: Add hooks.md to documentation index #40: Updates Hooks documentation in a complementary manner by adding hooks.md to the docs index.

Poem

🐰 A note in the docs, clear and bright,
Explains what won't work—what is right,
Settings won't override hooks today,
But clarity shows us the proper way! ✨

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: clarifying documentation about a hook override limitation and referencing the related issue number (`#226`).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into `main`

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

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

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

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

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

hooks/README.md (1)
56-68: ⚠️ Potential issue | 🟡 Minor

Consider removing or clearly labeling this example as non-functional.

The JSON example demonstrates the override pattern that the note above explicitly states doesn't work. This creates potential confusion—readers skimming the documentation might miss the note and attempt to use this pattern, wasting debugging time.

Consider one of these approaches:

Remove the example entirely (cleanest solution since it documents unsupported functionality)

Add a clear warning prefix before the code block: "⚠️ The following does NOT work (shown for reference):"

Provide an alternative that does work, if one exists
📝 Suggested fix: Remove the non-working example
 > **Note:** Hook override via `~/.claude/settings.json` is **not currently supported** due to how Claude Code merges configuration files. The documented override mechanism (adding an entry with empty `hooks: []` array) does not work because configurations are merged rather than replaced. This is a limitation in Claude Code's core configuration system. See [Issue `#226`](https://github.com/affaan-m/everything-claude-code/issues/226) for details.
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write",
-        "hooks": [],
-        "description": "Override: allow all .md file creation"
-      }
-    ]
-  }
-}
-```
 
 ### Writing Your Own Hook

pangerlkr · 2026-02-15T03:25:33Z

CI Test Failures - Not Related to This PR

The failing CI tests are not caused by this pull request. This PR contains only documentation changes to hooks/README.md - specifically adding a clarifying note about the hook override limitation.

Analysis:

✅ Other recent PRs (fix: whitelist .claude/plans/ in doc file creation hook #230, feat: add cpp coding standards skill #229, fix: correct TIMESTAMP environment variable syntax in observe.sh #228, Merge agent/0-07-bv-blackbox into main #225) are passing CI checks
❌ This PR inherits test failures from the fork's state at the time of branching
📝 Zero code changes - only README.md documentation updates

Recommendation:
Since this is a documentation-only change that cannot affect test behavior, the PR is safe to merge despite the CI failures. The test failures appear to be pre-existing or environment-specific issues unrelated to the documentation updates.

The documentation changes successfully:

Clarify that hook override via ~/.claude/settings.json is not supported
Explain the root cause (configuration merging vs replacement)
Reference issue Disabling a Hook override via ~/.claude/settings.json does not work #226 for full context

@affaan-m - Please review the documentation changes themselves. The CI failures should not block this docs update.

affaan-m · 2026-02-15T04:00:06Z

[openclaw-bot:pr-review]

CI Checks Failing ❌

Some CI checks are not passing on this PR. Please review the failing checks and push fixes.

This label will be automatically removed when CI passes on the next run.

affaan-m