feat(config-health): add runtime config integrity monitor with hook contract tests

Deterministic read-only non-blocking monitor (--startup/--pretool/--check):
hook wiring audit, rule reference audit, guard staleness. Never echoes
hook input or secrets; always exits 0. Wired as a Claude-only install
module (SessionStart/PreToolUse), added to full profile, package files,
and agent.yaml. Includes 9 hook-contract tests.
This commit is contained in:
YuhaoLin2005 committed 2026-08-12 23:42:10 +08:00
1 parent 569b1d5b32
commit 2f454e7561
7 files changed
+567 -1

No files matched your search

+1
View File
@@ -36,6 +36,7 @@ skills:
- codebase-onboarding
- coding-standards
- compose-multiplatform-patterns
- config-health
- configure-ecc
- contract-first
- content-engine
+17
View File
@@ -951,6 +951,23 @@
"cost": "medium",
"stability": "stable"
},
{
"id": "config-health",
"kind": "skills",
"description": "Runtime configuration integrity monitoring for Claude Code (Claude-only hooks: SessionStart/PreToolUse).",
"paths": [
"skills/config-health",
"scripts/config-health.py"
],
"targets": [
"claude",
"claude-project"
],
"dependencies": [],
"defaultInstall": false,
"cost": "light",
"stability": "beta"
},
{
"id": "docs-ja-jp",
"kind": "docs",
+2 -1
View File
@@ -97,7 +97,8 @@
"devops-infra",
"machine-learning",
"supply-chain-domain",
"document-processing"
"document-processing",
"config-health"
]
}
}
+2
View File
@@ -88,6 +88,7 @@
"scripts/catalog.js",
"scripts/ci/scan-supply-chain-iocs.js",
"scripts/ci/supply-chain-advisory-sources.js",
"scripts/config-health.py",
"scripts/consult.js",
"scripts/auto-update.js",
"scripts/claw.js",
@@ -161,6 +162,7 @@
"skills/code-tour/",
"skills/coding-standards/",
"skills/compose-multiplatform-patterns/",
"skills/config-health/",
"skills/configure-ecc/",
"skills/contract-first/",
"skills/connections-optimizer/",
+296
View File
@@ -0,0 +1,296 @@
#!/usr/bin/env python3
"""
config-health — runtime configuration integrity monitoring for Claude Code.
Deterministic, read-only, non-blocking monitor. Complements delivery-gate:
delivery-gate blocks at session end (missing growth-log = not retroactively
fixable); config-health warns during the session (config drift = fixable).
Modes:
--startup SessionStart: audit hook wiring, rule references, guard staleness.
--pretool PreToolUse: re-verify matched hook scripts exist and are wired.
Reads tool_use JSON on stdin but NEVER echoes it to stdout.
--check Manual: tri-color health overview on stdout.
Contract (from the ECC config-health skill):
- read-only — never writes to disk
- non-blocking — always exits 0, even on malformed input
- no leak — --pretool never prints raw hook input, commands, or secrets
- deterministic — same inputs → same findings (missing script = fact, not heuristic)
Config path resolution:
- user settings: $CONFIG_HEALTH_USER_HOME/.claude/settings.json
(defaults to ~/.claude/settings.json)
- project settings: $CLAUDE_PROJECT_DIR/.claude/settings.json
(defaults to <cwd>/.claude/settings.json)
Install: cp to ~/.claude/scripts/config-health.py
Wire (in your settings.json hooks — merge, don't replace):
SessionStart: python3 ~/.claude/scripts/config-health.py --startup
PreToolUse: python3 ~/.claude/scripts/config-health.py --pretool
"""
from __future__ import annotations
import json
import os
import re
import sys
# Windows GBK console can't encode emoji — force UTF-8 on stdout/stderr.
# This script's warnings may be captured by hook logs, so reconfigure to
# prevent UnicodeEncodeError on non-UTF-8 consoles.
try:
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
sys.stderr.reconfigure(encoding='utf-8', errors='replace')
except (AttributeError, OSError):
pass # Python <3.7 or stdout is not a TTY/stream
WARN_PREFIX = '[config-health] WARN: '
# Sessions of rule-health history to look back for guard staleness.
STALENESS_WINDOW = 5
# Minimum tool calls for a session to be "complex enough" to expect rule markers.
MIN_TOOL_CALLS_FOR_CHECK = 5
# Rule-health log written by the earlier Stop-hook monitor (read-only here).
RULE_HEALTH_LOG = '.claude/session-data/rule-health.jsonl'
# Metadata keys in each rule-health record, not rule counters.
NON_RULE_KEYS = {'ts', 'date', 'time', 'tool_calls', 'edits'}
# Matches a script path in a hook command: ~/.claude/scripts/x.py, scripts/x.js,
# C:/path/x.py, ./hooks/x.py. Misses inline shell one-liners, which is fine —
# we only audit references that look like files on disk.
SCRIPT_TOKEN = re.compile(r'([^\s"\']+\.(?:py|js|mjs|cjs|sh))')
def resolve_dirs():
"""Return (user_home, project_dir) honoring env overrides for determinism."""
user_home = os.environ.get('CONFIG_HEALTH_USER_HOME') or os.path.expanduser('~')
project_dir = os.environ.get('CLAUDE_PROJECT_DIR') or os.getcwd()
return user_home, project_dir
def read_text(path):
"""Read a file defensively; return None on any read/decode error."""
if not os.path.exists(path):
return None
try:
with open(path, 'r', encoding='utf-8') as f:
return f.read()
except (OSError, UnicodeDecodeError):
return None
def read_json(path):
"""Parse a JSON file defensively; return None if missing or malformed."""
text = read_text(path)
if text is None:
return None
try:
return json.loads(text)
except (ValueError, TypeError):
return None
def resolve_script_path(raw, project_dir):
"""Turn a token from a hook command into an absolute path.
`~` resolves against CONFIG_HEALTH_USER_HOME when set (the same override
used for the user settings path), else the real home — so tests stay
deterministic without affecting real users.
"""
if raw.startswith('~'):
override = os.environ.get('CONFIG_HEALTH_USER_HOME')
if override:
return os.path.join(override, raw[1:].lstrip('/\\'))
return os.path.expanduser(raw)
if os.path.isabs(raw):
return raw
return os.path.join(project_dir, raw)
def iter_hook_commands(settings):
"""Yield (event, command) for every command hook in a parsed settings.json.
Handles both the grouped form
{"hooks": {"PreToolUse": [{"matcher": "...", "hooks": [{"command": ...}]}]}}
and the flat form
{"hooks": {"PreToolUse": [{"command": ...}]}}.
"""
if not isinstance(settings, dict):
return
hooks = settings.get('hooks')
if not isinstance(hooks, dict):
return
for event, groups in hooks.items():
if not isinstance(groups, list):
continue
for group in groups:
if not isinstance(group, dict):
continue
inner = group.get('hooks')
if isinstance(inner, list):
for hook in inner:
if isinstance(hook, dict) and isinstance(hook.get('command'), str):
yield event, hook['command']
elif isinstance(group.get('command'), str):
yield event, group['command']
def audit_hook_wiring(settings, project_dir):
"""Verify every script referenced by a hook command exists on disk.
A referenced-but-missing script is a fact, not a heuristic — this is the
core deterministic check. Never prints the full command (may hold secrets);
only the missing path is reported.
"""
findings = []
for event, command in iter_hook_commands(settings):
for token in SCRIPT_TOKEN.findall(command):
path = resolve_script_path(token, project_dir)
if not os.path.exists(path):
findings.append(
f'hook "{event}" references missing script: {token}'
)
return findings
def audit_rule_references(project_dir):
"""Verify rule files referenced by CLAUDE.md exist on disk."""
findings = []
for base in ('CLAUDE.md', os.path.join('.claude', 'CLAUDE.md')):
content = read_text(os.path.join(project_dir, base))
if content is None:
continue
for ref in re.finditer(r'(?:\.claude/)?rules/[A-Za-z0-9_.-]+\.md', content):
rel = ref.group(0)
fp = os.path.join(project_dir, rel)
if not os.path.exists(fp):
findings.append(f'CLAUDE.md references missing rule file: {rel}')
return findings
def audit_guard_staleness(user_home):
"""Flag rules that stopped firing in recent sessions.
Only fires when a rule-health.jsonl log exists (written by the earlier
Stop-hook monitor). No log → no staleness judgment (avoids false positives).
"""
log_path = os.path.join(user_home, RULE_HEALTH_LOG)
content = read_text(log_path)
if content is None:
return []
records = []
for line in content.splitlines():
line = line.strip()
if not line:
continue
try:
records.append(json.loads(line))
except (ValueError, TypeError):
continue
if not records:
return []
recent = records[-STALENESS_WINDOW:]
if len(recent) < STALENESS_WINDOW:
return [] # Not enough history yet
rule_keys = set()
for rec in recent:
rule_keys.update(k for k in rec if k not in NON_RULE_KEYS)
findings = []
for rule in sorted(rule_keys):
complex_sessions = [
rec for rec in recent if rec.get('tool_calls', 0) >= MIN_TOOL_CALLS_FOR_CHECK
]
if not complex_sessions:
continue
if all(rec.get(rule, 0) == 0 for rec in complex_sessions):
findings.append(
f'rule "{rule}" last fired {STALENESS_WINDOW}+ sessions ago → may be dead'
)
return findings
def run_startup_audit(user_home, project_dir):
"""SessionStart audit: hook wiring + rule references + guard staleness."""
findings = []
user_settings = read_json(os.path.join(user_home, '.claude', 'settings.json'))
project_settings = read_json(os.path.join(project_dir, '.claude', 'settings.json'))
# Both settings may be absent or malformed — each is handled independently
# and never blocks. A malformed file yields no findings (nothing to audit)
# rather than a crash.
if user_settings is not None:
findings.extend(audit_hook_wiring(user_settings, project_dir))
if project_settings is not None:
findings.extend(audit_hook_wiring(project_settings, project_dir))
findings.extend(audit_rule_references(project_dir))
findings.extend(audit_guard_staleness(user_home))
return findings
def startup_mode():
user_home, project_dir = resolve_dirs()
findings = run_startup_audit(user_home, project_dir)
for finding in findings:
print(WARN_PREFIX + finding)
# Non-blocking by contract: never gate on process monitoring.
sys.exit(0)
def pretool_mode():
# Consume tool_use JSON without ever writing it to stdout. We only need the
# fact that a hook fired, not its contents. Raw hook input / secrets are
# never echoed — enforced by the hook-contract tests.
sys.stdin.read()
user_home, project_dir = resolve_dirs()
findings = []
user_settings = read_json(os.path.join(user_home, '.claude', 'settings.json'))
project_settings = read_json(os.path.join(project_dir, '.claude', 'settings.json'))
if user_settings is not None:
findings.extend(audit_hook_wiring(user_settings, project_dir))
if project_settings is not None:
findings.extend(audit_hook_wiring(project_settings, project_dir))
# PreToolUse keeps stdout clean — warnings go to stderr so a non-empty
# stdout can never be misread as a block/allow decision.
for finding in findings:
print(WARN_PREFIX + finding, file=sys.stderr)
sys.exit(0)
def check_mode():
"""Manual tri-color overview. Read-only."""
user_home, project_dir = resolve_dirs()
findings = run_startup_audit(user_home, project_dir)
if findings:
print('config-health: 🟡 attention')
for finding in findings:
print(' ' + WARN_PREFIX + finding)
else:
print('config-health: 🟢 normal — hook wiring, rules, and guards OK')
sys.exit(0)
def main():
args = sys.argv[1:]
if '--pretool' in args:
pretool_mode()
elif '--check' in args:
check_mode()
else:
# --startup (also the default): least surprising for a SessionStart hook.
startup_mode()
if __name__ == '__main__':
main()
+71
View File
@@ -0,0 +1,71 @@
---
name: config-health
description: Runtime configuration integrity monitoring for Claude Code. Detects config drift, rule staleness, and hook wiring gaps during sessions. Complements delivery-gate with session-duration soft monitoring.
metadata:
origin: ECC
---
# Config Health
A real-time monitoring layer. delivery-gate blocks at session end; config-health catches problems during the session — when cheap to fix.
## When to Activate
- After installing delivery-gate and wanting defense in depth
- When hooks silently stop firing
- When config rules accumulate but you're unsure which still work
- At session startup for config integrity scan
- Before high-risk Edit/Write operations
## How It Works
Session Start → config-health scans rules/hooks (soft warnings, never blocks)
Session Work → config-health monitors hook wiring (PreToolUse guard)
Session End → delivery-gate verifies (hard block, exit 2)
Boundary: "Can this be fixed retroactively?" Config drift → config-health warns. Missing growth-log → delivery-gate blocks (hard exit 2).
## What It Monitors
1. Rule Health: scans rules, checks hook wiring, detects dead rules
2. Hook Wiring Audit: verifies scripts exist and are wired before high-risk calls
3. Guard Script Staleness: checks maintenance windows
## Examples
Catching silent hook failure:
SessionStart → health-check.py referenced in 3 docs, wired 0 times → WARN: dead references
PreToolUse guard:
three-questions-guard.py: referenced in BODY.md, exists on disk, wired in settings.json → Allow
Rule staleness:
rule "双池强制触发" last fired 15 sessions ago → WARN: may be dead
## Install
**ECC users:** install the `config-health` module (`npx ecc-install --modules config-health` or the `full` profile). It is a **Claude-only** module (SessionStart/PreToolUse hooks) — it does not target other harnesses, so it stays isolated from shared 13-harness modules.
**Standalone:** copy `scripts/config-health.py` to `~/.claude/scripts/config-health.py` and verify it exists before enabling.
**Important:** Merge these hook entries into your existing `hooks` object — do not replace it, or you will lose hooks like delivery-gate.
```json
{
"hooks": {
"SessionStart": [{"hooks": [{"type": "command", "command": "python3 ~/.claude/scripts/config-health.py --startup", "timeout": 5000}]}],
"PreToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "python3 ~/.claude/scripts/config-health.py --pretool", "timeout": 3000}]}]
}
}
```
## Design Principles
1. Never block on process monitoring — config-health warns; delivery-gate blocks
2. Check what delivery-gate can't — config behavior vs filesystem state
3. Zero false positives on hook wiring — missing script = fact, not heuristic
## Files
| File | Purpose | Hook |
|------|---------|------|
| scripts/config-health.py | Rule health, hook audit, staleness | SessionStart + PreToolUse |
+178
View File
@@ -0,0 +1,178 @@
/**
* Hook-contract tests for scripts/config-health.py
*
* Verifies the contract haelyra asked for: present & missing scripts,
* malformed & absent settings, absent rule dirs, and warning behavior —
* every diagnostic must stay non-blocking (exit 0), exit cleanly, and never
* echo raw hook input or secrets.
*
* Run with: node tests/hooks/config-health.test.js
* (also picked up by `node tests/run-all.js`)
*/
'use strict';
const assert = require('assert');
const { spawnSync } = require('child_process');
const fs = require('fs');
const os = require('os');
const path = require('path');
const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'config-health.py');
// Resolve a working python. On Windows, missing interpreters surface as
// status 9009 (not a spawn error), so probe both name and exit status.
function resolvePython() {
const probe = (name) => {
const r = spawnSync(name, ['--version'], { stdio: 'ignore' });
return !r.error && r.status === 0;
};
if (process.env.CONFIG_HEALTH_PYTHON) return process.env.CONFIG_HEALTH_PYTHON;
if (probe('python3')) return 'python3';
if (probe('python')) return 'python';
throw new Error('No python interpreter found (tried CONFIG_HEALTH_PYTHON, python3, python)');
}
const PYTHON = resolvePython();
// ---- helpers ---------------------------------------------------------------
function test(name, fn) {
try {
fn();
console.log(` ✓ ${name}`);
return true;
} catch (err) {
console.log(` ✗ ${name}`);
console.log(` Error: ${err.message}`);
return false;
}
}
function makeFixture() {
// Returns { home, proj, root } — a throwaway sandbox under os.tmpdir().
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'config-health-'));
const home = path.join(root, 'home');
const proj = path.join(root, 'proj');
fs.mkdirSync(path.join(home, '.claude'), { recursive: true });
fs.mkdirSync(path.join(proj, '.claude'), { recursive: true });
return { root, home, proj };
}
function run(mode, { home, proj }, stdin = '') {
return spawnSync(PYTHON, [SCRIPT, mode], {
env: { ...process.env, CONFIG_HEALTH_USER_HOME: home, CLAUDE_PROJECT_DIR: proj },
input: stdin,
encoding: 'utf8',
});
}
function writeSettings(home, content) {
fs.writeFileSync(path.join(home, '.claude', 'settings.json'), content, 'utf8');
}
const HOOKS_JSON = (scriptPath) => JSON.stringify({
hooks: {
SessionStart: [{ hooks: [{ type: 'command', command: `python3 ${scriptPath} --start`, timeout: 5000 }] }],
PreToolUse: [{ matcher: 'Edit|Write', hooks: [{ type: 'command', command: `python3 ${scriptPath} --pretool`, timeout: 3000 }] }],
},
});
// ---- suite -----------------------------------------------------------------
function runTests() {
console.log('\n=== Testing config-health.py hook contract ===\n');
let passed = 0;
let total = 0;
const t = (name, fn) => { total += 1; if (test(name, fn)) passed += 1; };
// Absent settings → clean, non-blocking.
t('startup with absent settings exits 0 and is silent', () => {
const fx = makeFixture();
const r = run('--startup', fx);
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.strictEqual(r.stdout.trim(), '', 'expected no findings with no settings');
});
// Missing referenced script → WARN, still exit 0 (never blocks).
t('startup warns on a missing referenced script but exits 0', () => {
const fx = makeFixture();
writeSettings(fx.home, HOOKS_JSON('~/.claude/scripts/nope-guard.py'));
const r = run('--startup', fx);
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.ok(r.stdout.includes('missing script'), 'expected a missing-script warning');
assert.ok(r.stdout.includes('nope-guard.py'), 'warning should name the missing file');
});
// Script present → no warning.
t('startup is silent when referenced scripts exist', () => {
const fx = makeFixture();
fs.mkdirSync(path.join(fx.home, '.claude', 'scripts'), { recursive: true });
fs.writeFileSync(path.join(fx.home, '.claude', 'scripts', 'ok-guard.py'), '', 'utf8');
writeSettings(fx.home, HOOKS_JSON('~/.claude/scripts/ok-guard.py'));
const r = run('--startup', fx);
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.ok(!r.stdout.includes('missing script'), 'expected no missing-script warning');
});
// Malformed settings → clean, non-blocking, no crash.
t('startup tolerates malformed settings (exit 0, no crash)', () => {
const fx = makeFixture();
writeSettings(fx.home, '{ not valid json');
const r = run('--startup', fx);
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.ok(!/Traceback|Error/.test(r.stdout + r.stderr), 'should not crash');
});
// Absent rule dir / absent CLAUDE.md → clean.
t('startup with absent rules dir and CLAUDE.md is clean', () => {
const fx = makeFixture(); // proj has .claude but no CLAUDE.md, no rules/
const r = run('--startup', fx);
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.strictEqual(r.stdout.trim(), '', 'expected no findings');
});
// Dead rule reference → WARN, exit 0.
t('startup warns on CLAUDE.md referencing a missing rule file', () => {
const fx = makeFixture();
fs.writeFileSync(path.join(fx.proj, 'CLAUDE.md'), 'see rules/ghost.md\n', 'utf8');
const r = run('--startup', fx);
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.ok(r.stdout.includes('missing rule file'), 'expected a dead-rule warning');
});
// --pretool must NEVER echo stdin (raw hook input / secrets).
t('pretool never echoes raw hook input or secrets to stdout', () => {
const fx = makeFixture();
const secret = 'ghp_FakeSecretToken_12345';
const input = JSON.stringify({ tool_name: 'Write', tool_input: { file_path: 'x.md' }, api_key: secret });
const r = run('--pretool', fx, input);
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.strictEqual(r.stdout, '', 'stdout must be empty — stdin must not be echoed');
assert.ok(!(r.stdout + r.stderr).includes(secret), 'secret must not appear anywhere');
});
// --pretool with malformed stdin → clean exit.
t('pretool tolerates malformed stdin (exit 0)', () => {
const fx = makeFixture();
const r = run('--pretool', fx, 'garbage{{{{');
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.ok(!/Traceback/.test(r.stdout + r.stderr), 'should not crash');
});
// Warning behavior: pretool warnings go to stderr, stdout stays clean.
t('pretool warns on stderr, keeps stdout clean, stays non-blocking', () => {
const fx = makeFixture();
writeSettings(fx.home, HOOKS_JSON('~/.claude/scripts/missing-again.py'));
const r = run('--pretool', fx, '{"tool_name":"Edit"}');
assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`);
assert.strictEqual(r.stdout, '', 'stdout must stay empty in pretool mode');
assert.ok(r.stderr.includes('missing script'), 'warning should surface on stderr');
});
console.log(`\n ${passed}/${total} passed`);
if (passed !== total) process.exit(1);
}
runTests();