Safe configuration changes

Plan before modifying

The installer detects supported user configuration locations and versions without recursive full-disk scanning. It builds a concrete change plan showing the exact before/after content, affected files, owned hook entries, and backup locations.

The user chooses integrations and explicitly consents. TraceRook must not alter managed corporate policies, silently disable other hooks, or treat executable discovery alone as support verification.

Backups and source-hash checks

Create timestamped, permission-preserving backups in an app-owned directory before modification. Preserve unknown fields and unrelated hooks in meaning. Parsing and targeted changes must respect the actual JSON or TOML structure.

Hash the original source used for the preview. If it changes before the write, abort and create a fresh plan. This optimistic-concurrency guard prevents overwriting a user’s intervening edit or another installer’s change.

Verify and write atomically

1. Verify the signed bridge and its version before wiring a hook.
2. Copy it by verified, atomic replacement to a stable user path.
3. Write the modified configuration to a temporary file in the same directory.
4. Synchronize and rename atomically, retaining intended permissions.
5. Validate parsing and host support after the change.
6. Verify an actual callback and blocking behavior before claiming coverage.

Stable bridge path: ~/Library/Application Support/TraceRook/bin/tracerook-hook. Host shell-form commands use an absolute, correctly quoted path.

Idempotent ownership and repair

TraceRook tracks its own hooks with a stable command/argument fingerprint or a schema-permitted marker. It must not add unrecognized properties just to mark ownership. Reinstalling should not duplicate handlers.

Monitor hashes, missing helpers, disabled hooks, trust, and callbacks. If repair is needed after an update or app move, show the change plan again. Codex may need renewed human trust for changed definitions.

Remove only owned entries

Uninstall removes TraceRook-owned entries and leaves unrelated settings and hooks. Restore an old full file only when there are no structural conflicts; a backup must not overwrite newer user changes.

Helper registration, history retention, and Keychain deletion are independent choices. All work remains user-level and nonprivileged; MVP1 does not require root or sudo. Safe Claude Code and Codex installation is planned for MVP2.2 and MVP2.3.