ClaudeWatch AGENTS.md

AGENTS.md — Working on ClaudeWatch

This is the build philosophy and key constraints document for ClaudeWatch. The contract lives in SPEC.md; this document captures the how to think about it. Every Claude Code session should read this before making non-trivial changes.

What ClaudeWatch is

A Claude Code plugin that wraps every shell invocation — Bash and Monitor, which runs its command in the same shell — in a PreToolUse hook and applies regex-based safety rules. The core safety advantage over Claude Code's built-in deny rules is that patterns match anywhere in the command string (re.search()), so compound commands (git add . && git push --force), heredocs, and reordered flags are not bypassable by syntactic tricks.

Core contracts (don't break these)

1. Determinism. Given the same command, the same cwd and project root, the same watches/ tree, and the same on-disk state of the paths those name, the engine must always produce the same decision. No clocks, no randomness, no network on the decision path. cwd and CLAUDE_PROJECT_DIR enter the decision only as the deterministic per-invocation inputs the is_in_project_tree predicate ([RL-15], [RL-16]) resolves rm targets against — pure string work, no filesystem access. CLAUDE_PROJECT_DIR is the one environment variable on the decision path; CLAUDEWATCH_LOG governs a side channel only. The one predicate that does read the filesystem is is_recoverable ([RL-18]), which asks git whether a delete target could be restored — a question with no textual answer. Its calls are read-only, bounded, and fail closed, so the decision stays a function of the command, the roots, and the on-disk state those name; a second predicate wanting filesystem access is a spec change, not a local call. Decision logging (on by default, see [LOG-01]–[LOG-04]; CLAUDEWATCH_LOG=off opts out) is a side channel: it stamps a timestamp and writes a file after the decision is computed, never feeding back into it. Keep it that way — the clock stays in _log_event, not in evaluate_rules.
2. Exit code is always 0. A non-zero exit blocks the host (Claude Code) from getting a useful decision. All errors are surfaced as deny decisions with explanatory messages.
3. Single coalesced decision per invocation. Multiple matching rules across multiple rule sets aggregate into one deny (preferred) or one ask. Never emit more than one decision.
4. The engine ships self-contained. scripts/watchdog.py and everything on the decision path use only the Python standard library (with a minimal built-in YAML parser), so the plugin installs cleanly and evaluates rules fast in any environment Claude Code runs in — no pip step on the hot path. Build- and release-time tooling that never runs on the decision path (e.g. shipyard's gen-plugin-json, run by CI's project job) may use PyYAML; it never runs in the hook.
5. Allow-by-default. When no rule matches, the engine produces no stdout output. Silence is allow.