feat: tiered hook installation — local, global, plugin

Refactor `clens init` to support three installation tiers so hooks no
longer pollute the project's `.claude/settings.json`. Default tier writes
to `.claude/settings.local.json` (gitignored by convention), `--global`
writes to `~/.claude/settings.json`, and `clens init plugin` now installs
both analysis tools and capture hooks in one command.

- Add InitTarget type and resolveInitPaths for multi-tier path resolution
- Default init writes to settings.local.json instead of settings.json
- Add --global flag for user-level hook installation
- Add legacy detection with migration guidance
- Refactor uninit for multi-tier removal (local, global, legacy)
- Update renderStatus to show all tiers with deduplication warnings
- Create agentic/hooks/hooks.json with all 17 hook events
- Enhance installPlugin to merge capture hooks into user settings
- Enhance uninstallPlugin to remove capture hooks from user settings
- Add type guards replacing unsafe `as` casts on untrusted data
- Add try/catch to readSettingsFile for malformed JSON resilience
- 1137 tests (51 new), 0 failures

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: silouone

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.1] - 2026-02-25
+
+### Added
+
+#### Tiered Hook Installation
+- `clens init` now writes hooks to `.claude/settings.local.json` (gitignored) instead of `.claude/settings.json` — no more polluting the repo
+- `clens init --global` installs hooks to `~/.claude/settings.json` for all projects
+- `clens init plugin` now installs both analysis tools AND capture hooks in one command
+- `clens init --status` shows installation state across all tiers (Local, Global, Plugin, Legacy)
+- `clens init --remove --legacy` removes hooks from `.claude/settings.json` (legacy location)
+- Legacy detection: warns when hooks exist in `.claude/settings.json` and suggests migration
+- Multi-tier deduplication warning when hooks are installed in multiple tiers
+- `agentic/hooks/hooks.json` — plugin hooks file with all 17 hook events
+
+### Changed
+- `init()` refactored with `InitTarget` type (`"local" | "global"`) and `resolveInitPaths` helper
+- `uninit` detects and removes hooks from all active tiers
+- `installPlugin` merges capture hooks into user-level settings with backup
+- `uninstallPlugin` removes capture hooks from user-level settings
+- `validatePluginStructure` now checks for `hooks/hooks.json`
+- `readSettingsFile` handles malformed JSON gracefully (try/catch)
+- Type-safe parsing: replaced `as` casts on untrusted data with type guards
+- 1137 tests across 49 test files (was 1086 across 48)
+
 ## [0.2.0] - 2026-02-25
 
 ### Breaking Changes

agentic/hooks/hooks.json

@@ -0,0 +1,22 @@
+{
+	"description": "cLens session capture — records all hook events to .clens/sessions/",
+	"hooks": {
+		"SessionStart": [{ "hooks": [{ "type": "command", "command": "clens-hook SessionStart" }] }],
+		"SessionEnd": [{ "hooks": [{ "type": "command", "command": "clens-hook SessionEnd" }] }],
+		"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "clens-hook UserPromptSubmit" }] }],
+		"PreToolUse": [{ "hooks": [{ "type": "command", "command": "clens-hook PreToolUse" }] }],
+		"PostToolUse": [{ "hooks": [{ "type": "command", "command": "clens-hook PostToolUse" }] }],
+		"PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "clens-hook PostToolUseFailure" }] }],
+		"PermissionRequest": [{ "hooks": [{ "type": "command", "command": "clens-hook PermissionRequest" }] }],
+		"Notification": [{ "hooks": [{ "type": "command", "command": "clens-hook Notification" }] }],
+		"SubagentStart": [{ "hooks": [{ "type": "command", "command": "clens-hook SubagentStart" }] }],
+		"SubagentStop": [{ "hooks": [{ "type": "command", "command": "clens-hook SubagentStop" }] }],
+		"Stop": [{ "hooks": [{ "type": "command", "command": "clens-hook Stop" }] }],
+		"TeammateIdle": [{ "hooks": [{ "type": "command", "command": "clens-hook TeammateIdle" }] }],
+		"TaskCompleted": [{ "hooks": [{ "type": "command", "command": "clens-hook TaskCompleted" }] }],
+		"PreCompact": [{ "hooks": [{ "type": "command", "command": "clens-hook PreCompact" }] }],
+		"ConfigChange": [{ "hooks": [{ "type": "command", "command": "clens-hook ConfigChange" }] }],
+		"WorktreeCreate": [{ "hooks": [{ "type": "command", "command": "clens-hook WorktreeCreate" }] }],
+		"WorktreeRemove": [{ "hooks": [{ "type": "command", "command": "clens-hook WorktreeRemove" }] }]
+	}
+}

src/cli.ts

@@ -195,7 +195,7 @@ const KILLED_COMMANDS: Readonly<Record<string, string>> = {
 const GLOBAL_FLAGS = new Set(["--help", "-h", "--version", "-v"]);
 
 const VALID_FLAGS_BY_COMMAND: Readonly<Record<string, ReadonlySet<string>>> = {
-	init: new Set(["--remove", "--status", "--dev"]),
+	init: new Set(["--remove", "--status", "--dev", "--global", "--legacy"]),
 	list: new Set(["--json"]),
 	distill: new Set(["--last", "--all", "--deep", "--json"]),
 	report: new Set(["--last", "--json", "--detail", "--full", "--intent"]),
@@ -245,9 +245,11 @@ const printHelp = (): void => {
 ${bold("Usage:")} clens <command> [session-id] [options]
 
 ${bold("Setup:")}
-  ${cyan("init")}              Initialize clens hooks
-  ${cyan("init --remove")}     Remove hooks and restore settings
-  ${cyan("init --status")}     Show hook installation status
+  ${cyan("init")}              Initialize clens hooks (local, per-project)
+  ${cyan("init --global")}     Initialize clens hooks (global, all projects)
+  ${cyan("init --remove")}     Remove hooks from all active tiers
+  ${cyan("init --remove --legacy")}  Also remove legacy hooks from .claude/settings.json
+  ${cyan("init --status")}     Show hook installation status across all tiers
   ${cyan("init plugin")}       Install/uninstall analysis plugin
 
 ${bold("Sessions:")}
@@ -277,11 +279,14 @@ ${bold("Options:")}
   ${dim("--intent")}       Filter by reasoning intent type
   ${dim("--all")}          Distill all sessions
   ${dim("--comms")}        Show communication timeline
+  ${dim("--global")}       Install hooks globally (~/.claude/settings.json)
+  ${dim("--legacy")}       Include legacy hooks in --remove
   ${dim("--version")}      Show version
   ${dim("--help")}         Show help
 
 ${bold("Examples:")}
-  clens init                          # Set up hooks
+  clens init                          # Set up hooks (local)
+  clens init --global                 # Set up hooks (global)
   clens list                          # See all sessions
   clens distill --last                # Distill latest session
   clens report --last                 # Summary of latest session
@@ -310,6 +315,8 @@ const flags: Flags = {
 	status: args.includes("--status"),
 	dev: args.includes("--dev"),
 	comms: args.includes("--comms"),
+	global: args.includes("--global"),
+	legacy: args.includes("--legacy"),
 };
 
 const positional = args.filter((a) => !a.startsWith("--") && !a.startsWith("-"));