v0.1 W2: ClaudeCodeSurface install/uninstall + settings.json merge

Implements W2 of the v0.1 milestone (#2). Per design.md §3.1, §5, §7:

- klasp-agents-claude::hook_template — three-line bash shim with the
  `# klasp:managed` marker and `KLASP_GATE_SCHEMA=N` export, parameterised
  by schema version so the contract test (W3) can verify the binary and
  fixture stay in lockstep.
- klasp-agents-claude::settings — surgical serde_json-based merge that
  preserves every sibling key in `.claude/settings.json`, idempotent on
  exact `command` match. Inverse `unmerge_hook_entry` cleans up empty
  matchers so install→uninstall round-trips a fresh repo to `{}`.
- klasp-agents-claude::surface — `ClaudeCodeSurface` impl of
  `klasp_core::AgentSurface`. Marker-comment idempotency check, atomic
  writes via tempfile, chmod 0o755 (Unix). `MarkerConflict` unless
  `--force` when an existing hook lacks our marker.
- klasp/src/registry — `SurfaceRegistry` with `ClaudeCodeSurface`
  pre-registered. Lives in the binary crate so klasp-core stays free of
  per-agent dependencies (relevant for the v0.3 plugin model).
- klasp/src/cmd/install + uninstall — CLI wiring per design §5: filter
  surfaces by `--agent` and `detect()`, build `InstallContext`, dispatch.

Tests:
- 19 unit tests in settings.rs (empty-input, sibling preservation,
  idempotency, malformed JSON, shape errors, uninstall round-trip)
- 3 integration tests against a realistic fallow-shaped fixture
  (proves fallow's hook entry survives byte-for-byte)
- 8 integration tests in klasp/tests/install_claude_code.rs (install,
  re-install no-op, dry-run, sibling preservation, marker-conflict
  refusal, --force overwrite, uninstall, uninstall dry-run)
- 2 insta snapshot tests of the rendered hook script (v1 + v7 to
  exercise schema-version interpolation)

The hook entry's `command` resolves `${CLAUDE_PROJECT_DIR}` at hook
execution time, so the same `.claude/settings.json` works regardless of
the cwd Claude is invoked from.

Closes #2.

Author: liam-ai-reality

Cargo.lock

@@ -11,3 +11,10 @@ publish = false
 
 [dependencies]
 klasp-core = { path = "../klasp-core" }
+serde_json = { workspace = true }
+tempfile = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+insta = { version = "1", features = ["yaml"] }
+tempfile = { workspace = true }

klasp-agents-claude/Cargo.toml

@@ -0,0 +1,55 @@
+//! The bash shim klasp drops into `.claude/hooks/klasp-gate.sh`.
+//!
+//! Per [docs/design.md §7], the script is intentionally three lines of work
+//! around a marker comment: the schema-version export is the wire-protocol
+//! handshake, and `exec klasp gate "$@"` hands off to the Rust binary. The
+//! marker substring [`MANAGED_MARKER`] is the idempotency anchor — install
+//! re-greps for it to decide whether the file is klasp's to touch.
+
+/// The literal substring `install` looks for to recognise klasp's managed
+/// hook script. Stable across schema bumps; the version digit follows.
+pub const MANAGED_MARKER: &str = "# klasp:managed";
+
+/// Render the hook script body for the given wire-protocol schema version.
+///
+/// Pure: no filesystem, no env. Used by both `install` (to write the file)
+/// and `--dry-run` (to preview it).
+pub fn render(schema_version: u32) -> String {
+    format!(
+        "#!/usr/bin/env bash\n\
+         {marker} v{ver} — generated by `klasp install`. Do not edit; re-run install instead.\n\
+         export KLASP_GATE_SCHEMA={ver}\n\
+         exec klasp gate \"$@\"\n",
+        marker = MANAGED_MARKER,
+        ver = schema_version,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn render_v1_contains_marker_export_and_exec() {
+        let s = render(1);
+        assert!(s.starts_with("#!/usr/bin/env bash\n"));
+        assert!(s.contains(MANAGED_MARKER));
+        assert!(s.contains("export KLASP_GATE_SCHEMA=1\n"));
+        assert!(s.contains("exec klasp gate \"$@\"\n"));
+    }
+
+    #[test]
+    fn render_parameterises_schema_version() {
+        let s = render(7);
+        assert!(s.contains("# klasp:managed v7"));
+        assert!(s.contains("export KLASP_GATE_SCHEMA=7"));
+    }
+
+    #[test]
+    fn render_ends_with_newline() {
+        // POSIX: text files end with newlines. The script gets `chmod +x`'d
+        // and an interactive editor that does "ensure final newline" should
+        // produce no diff.
+        assert!(render(1).ends_with('\n'));
+    }
+}

klasp-agents-claude/src/hook_template.rs

@@ -1,15 +1,11 @@
 //! `klasp-agents-claude` — Claude Code `AgentSurface` impl.
 //!
-//! W1 ships only the crate skeleton; the real implementation (settings.json
-//! merge, hook script template, idempotency checks) lands in W2 per
-//! [docs/roadmap.md] §"Timeline". The empty struct exists so the workspace
-//! compiles and the `klasp` binary can take this crate as a dependency
-//! today.
+//! See [docs/design.md] §3.1 (trait), §5 (install flow), §7 (hook script).
 
-/// Claude Code agent surface. The `AgentSurface` impl lands in W2 — see
-/// [docs/design.md] §3.1 and §5 for the contract this struct must satisfy.
-pub struct ClaudeCodeSurface;
+pub mod hook_template;
+pub mod settings;
+pub mod surface;
 
-impl ClaudeCodeSurface {
-    pub const AGENT_ID: &'static str = "claude_code";
-}
+pub use hook_template::{render as render_hook_script, MANAGED_MARKER};
+pub use settings::{merge_hook_entry, unmerge_hook_entry, SettingsError};
+pub use surface::ClaudeCodeSurface;