aether-colony 5.1.0 → 5.3.0

package/.aether/docs/command-playbooks/build-prep.md

@@ -98,7 +98,8 @@ If the command fails (non-zero exit or JSON has ok: false):
 If successful:
 1. Parse the state JSON from result field
 2. Check if goal is null - if so: "No colony initialized. Run /ant:init first." and stop
-3. Extract current_phase and phase name from plan.phases[current_phase - 1].name
+3. Check if `milestone` == `"Crowned Anthill"` - if so: "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+4. Extract current_phase and phase name from plan.phases[current_phase - 1].name
 4. Display brief resumption context:
    ```
    🔄 Resuming: Phase X - Name
@@ -225,7 +226,7 @@ Parse the JSON result (`.result.blockers`):
 
 ### Step 2: Update State
 
-Read then update `.aether/data/COLONY_STATE.json`:
+Update `.aether/data/COLONY_STATE.json` using state-mutate (atomic, locked, validated):
 - Set `state` to `"EXECUTING"`
 - Set `current_phase` to the phase number
 - Set the phase's `status` to `"in_progress"` in `plan.phases[N]`
@@ -234,7 +235,14 @@ Read then update `.aether/data/COLONY_STATE.json`:
 
 If `events` exceeds 100 entries, keep only the last 100.
 
-Write COLONY_STATE.json.
+Run using the Bash tool with description "Updating colony state for build...":
+```bash
+bash .aether/aether-utils.sh state-mutate \
+  --argjson phase "$PHASE_NUMBER" \
+  --arg phase_name "$PHASE_NAME" \
+  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '.state = "EXECUTING" | .current_phase = $phase | .plan.phases |= map(if .id == $phase then .status = "in_progress" else . end) | .build_started_at = $timestamp | .events = ((.events[-99:]) + [$timestamp + "|phase_started|build|Phase " + ($phase|tostring) + ": " + $phase_name + " started"])'
+```
 
 Validate the state file:
 Run using the Bash tool with description "Validating colony state...":
@@ -253,7 +261,7 @@ git rev-parse --git-dir 2>/dev/null
 
 - **If succeeds** (is a git repo):
   1. Check for changes in Aether-managed directories only: `.aether .claude/commands/ant .claude/commands/st .opencode bin`
-  2. **If changes exist**: Run using the Bash tool with description "Creating git checkpoint...": `git stash push -m "aether-checkpoint: pre-phase-$PHASE_NUMBER" -- .aether .claude/commands/ant .claude/commands/st .opencode bin`
+  2. **If changes exist**: Run using the Bash tool with description "Creating git checkpoint...": `git stash push -m "aether-checkpoint: pre-phase-$PHASE_NUMBER" -- .aether .claude/commands/ant .claude/commands/st .opencode bin ":(exclude).aether/data/"`
      - IMPORTANT: Never use `--include-untracked` — it stashes ALL files including user work!
      - Run using the Bash tool with description "Verifying checkpoint...": `git stash list | head -1 | grep "aether-checkpoint"` — warn if empty
      - Store checkpoint as `{type: "stash", ref: "aether-checkpoint: pre-phase-$PHASE_NUMBER"}`

package/.aether/docs/command-playbooks/build-verify.md

@@ -1,3 +1,16 @@
+### Step 5.3.5: Generate Compact Review Context for Review Cycles
+
+Before spawning review agents, generate compact colony context for CI/autopilot agent review cycles.
+
+Run using the Bash tool with description "Generating compact review context...":
+```bash
+REVIEW_CONTEXT=$(bash "$AETHER_UTILS" pr-context --compact 2>/dev/null) || true
+```
+
+- If empty, continue without review context (non-blocking)
+- Provides compact colony context for CI/autopilot agent review cycles
+- Output is available for Watcher and subsequent review agents but does not gate them
+
 ### Step 5.4: Spawn Watcher for Verification
 
 **MANDATORY: Always spawn a Watcher — testing must be independent.**
@@ -403,3 +416,41 @@ bash .aether/aether-utils.sh memory-capture \
 ```
 
 This ensures verification failures are persisted as blockers that survive context resets. Chaos Ant findings are flagged in Step 5.7.
+
+### Step 5.9: Midden Collection for Merged Branches (NON-BLOCKING)
+
+**Per D-04: Wire midden-collect into /ant:run flow (build-verify phase).**
+
+If this build is running on main after a merge (detected via COLONY_STATE or git log), attempt midden collection:
+
+Run using the Bash tool with description "Collecting midden from merged branch...":
+```bash
+# Only runs if merge context is available
+if [[ -n "${last_merged_branch:-}" && -n "${last_merge_sha:-}" ]]; then
+  collect_result=$(bash .aether/aether-utils.sh midden-collect \
+    --branch "$last_merged_branch" --merge-sha "$last_merge_sha" \
+    2>/dev/null || echo '{"ok":false}')
+  collect_ok=$(echo "$collect_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$collect_ok" == "true" ]]; then
+    collect_status=$(echo "$collect_result" | jq -r '.result.status // "unknown"' 2>/dev/null)
+    new_entries=$(echo "$collect_result" | jq -r '.result.entries_collected // 0' 2>/dev/null)
+    if [[ "$collect_status" == "collected" && "$new_entries" -gt 0 ]]; then
+      echo "Midden: collected $new_entries entries from $last_merged_branch"
+    fi
+  fi
+
+  # Run cross-PR analysis after collection (per D-05)
+  analysis_result=$(bash .aether/aether-utils.sh midden-cross-pr-analysis --window 14 \
+    2>/dev/null || echo '{"ok":false}')
+  analysis_ok=$(echo "$analysis_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$analysis_ok" == "true" ]]; then
+    systemic=$(echo "$analysis_result" | jq -r '.result.systemic_categories // [] | length' 2>/dev/null || echo "0")
+    if [[ "$systemic" -gt 0 ]]; then
+      categories=$(echo "$analysis_result" | jq -r '.result.systemic_categories | join(", ")' 2>/dev/null)
+      echo "Midden: cross-PR systemic: $categories"
+    fi
+  fi
+fi
+```
+
+This step is NON-BLOCKING -- build verification proceeds regardless of collection or analysis outcome.

package/.aether/docs/command-playbooks/continue-advance.md

@@ -1,3 +1,16 @@
+### Step 2.0.7: Generate Review Context (pr-context)
+
+After verification passes, generate structured colony context for the review and learning steps that follow.
+
+Run using the Bash tool with description "Generating review context...":
+```bash
+REVIEW_CONTEXT=$(bash "$AETHER_UTILS" pr-context 2>/dev/null) || true
+```
+
+- If REVIEW_CONTEXT is empty or fails, continue without it (non-blocking)
+- This provides structured colony context for review/learning steps
+- Output is available for subsequent steps but does not gate them
+
 ### Step 2: Update State
 
 Find current phase in `plan.phases`.
@@ -285,20 +298,116 @@ Update COLONY_STATE.json:
    - Keep max 30 instincts (remove lowest confidence)
    - Keep max 100 events
 
-Write the updated state through the locked subcommand. Construct the full updated COLONY_STATE.json content as a variable, then pipe it to state-write:
+Write the updated state through targeted `state-mutate` calls. Each call acquires a lock, creates a backup, applies the jq expression, validates, and writes atomically. Do NOT use the Write tool or `state-write` with full JSON content — always use `state-mutate` to avoid stale-context corruption.
 
-Run using the Bash tool with description "Writing colony state...":
+Run using the Bash tool with description "Advancing colony state...":
 ```bash
-cat << 'STATEOF' | bash .aether/aether-utils.sh state-write
-<the full JSON content>
-STATEOF
+# Mark current phase completed
+bash .aether/aether-utils.sh state-mutate --argjson pid "$current_phase" \
+  '.plan.phases |= map(if .id == $pid then .status = "completed" else . end)'
+
+# Append learning (if any — skip if no learnings were extracted in Step 2)
+# bash .aether/aether-utils.sh state-mutate --argjson learning "$learning_json" \
+#   '.memory.phase_learnings += [$learning]'
+
+# Advance to next phase
+bash .aether/aether-utils.sh state-mutate \
+  --argjson pid "$current_phase" \
+  --argjson next "$next_phase" \
+  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '.current_phase = $next | .state = "READY" | .build_started_at = null | .events += [$timestamp + "|phase_advanced|continue|Completed Phase " + ($pid|tostring) + ", advancing to Phase " + ($next|tostring)]'
 ```
 
-This acquires a lock, creates a rolling backup, validates JSON, and writes atomically. Do NOT use the Write tool to write COLONY_STATE.json directly — always go through state-write.
+Run using the Bash tool with description "Enforcing memory caps...":
+```bash
+# Cap enforcement — keep arrays bounded
+bash .aether/aether-utils.sh state-mutate \
+  '.memory.phase_learnings = (.memory.phase_learnings[-20:]) | .memory.decisions = (.memory.decisions[-30:]) | .memory.instincts = (.memory.instincts | sort_by(.confidence) | .[-30:]) | .events = (.events[-100:])'
+```
 
 Validate the state file:
 Run using the Bash tool with description "Validating colony state...": `bash .aether/aether-utils.sh validate-state colony`
 
+### Step 2.0.5: Pheromone Merge-Back (SILENT, NON-BLOCKING)
+
+If a `pheromone-branch-export.json` exists in `.aether/exchange/` (written by seal ceremony on a PR branch and merged to main), run merge-back to collect branch-discovered signals into main's pheromone store. This entire step is silent and non-blocking -- continue proceeds even if merge-back fails.
+
+Run using the Bash tool with description "Checking for pheromone merge-back file...":
+```bash
+# Check if a branch pheromone export was merged into main
+export_file=".aether/exchange/pheromone-branch-export.json"
+if [[ -f "$export_file" ]]; then
+  merge_result=$(bash .aether/aether-utils.sh pheromone-merge-back --export-file "$export_file" 2>/dev/null || echo '{"ok":false}')
+  merge_ok=$(echo "$merge_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$merge_ok" == "true" ]]; then
+    new_count=$(echo "$merge_result" | jq -r '.result.new_signals_written // 0' 2>/dev/null)
+    skipped=$(echo "$merge_result" | jq -r '.result.skipped_count // 0' 2>/dev/null)
+    conflicts=$(echo "$merge_result" | jq -r '.result.conflicts_resolved // [] | length' 2>/dev/null)
+    if [[ "$new_count" -gt 0 || "$conflicts" -gt 0 ]]; then
+      echo "Pheromone merge-back: $new_count new, $conflicts conflicts resolved, $skipped skipped (from merged branch)"
+    fi
+    # Clean up export file after successful merge
+    rm -f "$export_file" 2>/dev/null || true
+  else
+    echo "Pheromone merge-back: failed (non-blocking)"
+  fi
+fi
+```
+
+### Step 2.0.6: Midden Collection (NON-BLOCKING)
+
+After pheromone merge-back, collect failure records from any recently merged branch worktrees. This step is silent and non-blocking -- continue proceeds even if collection fails.
+
+**Per D-04: Wire midden-collect into /ant:continue flow.**
+
+If the colony uses a PR-based workflow and a merge just happened, attempt to collect the branch's midden entries:
+
+Run using the Bash tool with description "Collecting branch midden entries...":
+```bash
+# Check if there's a recently merged branch to collect from
+# The merge info comes from git log or COLONY_STATE context
+last_merge_branch="${last_merged_branch:-}"
+last_merge_sha="${last_merge_sha:-}"
+
+if [[ -n "$last_merge_branch" && -n "$last_merge_sha" ]]; then
+  collect_result=$(bash .aether/aether-utils.sh midden-collect \
+    --branch "$last_merge_branch" --merge-sha "$last_merge_sha" \
+    2>/dev/null || echo '{"ok":false}')
+  collect_ok=$(echo "$collect_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$collect_ok" == "true" ]]; then
+    collect_status=$(echo "$collect_result" | jq -r '.result.status // "unknown"' 2>/dev/null)
+    if [[ "$collect_status" == "collected" ]]; then
+      new_entries=$(echo "$collect_result" | jq -r '.result.entries_collected // 0' 2>/dev/null)
+      echo "Midden: collected $new_entries failure entries from branch $last_merge_branch"
+    fi
+  fi
+fi
+```
+
+This step is NON-BLOCKING -- continue proceeds regardless of collection outcome. If `last_merge_branch` and `last_merge_sha` are not set (e.g., no recent merge), this step is silently skipped.
+
+### Step 2.0.7: Cross-PR Midden Analysis (NON-BLOCKING)
+
+After midden collection (Step 2.0.6), run cross-PR analysis to detect systemic failure patterns across multiple merged branches. Auto-emits REDIRECT pheromones to hub if systemic patterns found.
+
+**Per D-05: Wire midden-cross-pr-analysis into /ant:continue flow.**
+
+Run using the Bash tool with description "Running cross-PR midden analysis...":
+```bash
+analysis_result=$(bash .aether/aether-utils.sh midden-cross-pr-analysis --window 14 \
+  2>/dev/null || echo '{"ok":false}')
+analysis_ok=$(echo "$analysis_result" | jq -r '.ok // false' 2>/dev/null)
+if [[ "$analysis_ok" == "true" ]]; then
+  systemic=$(echo "$analysis_result" | jq -r '.result.systemic_categories // [] | length' 2>/dev/null || echo "0")
+  if [[ "$systemic" -gt 0 ]]; then
+    categories=$(echo "$analysis_result" | jq -r '.result.systemic_categories | join(", ")' 2>/dev/null)
+    echo "Midden: cross-PR systemic pattern detected in: $categories (REDIRECT emitted)"
+  fi
+fi
+```
+
+This step is NON-BLOCKING -- advance proceeds regardless of analysis outcome.
+
 ### Step 2.1: Auto-Emit Phase Pheromones (SILENT)
 
 **This entire step produces NO user-visible output.** All pheromone operations run silently — learnings are deposited in the background. If any pheromone call fails, log the error and continue. Phase advancement must never fail due to pheromone errors.

package/.aether/docs/command-playbooks/continue-full.md

@@ -26,6 +26,7 @@ Extract: `goal`, `state`, `current_phase`, `plan.phases`, `errors`, `memory`, `e
 
 **Validation:**
 - If `goal: null` -> output "No colony initialized. Run /ant:init first." and stop.
+- If `milestone` == `"Crowned Anthill"` -> output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop.
 - If `plan.phases` is empty -> output "No project plan. Run /ant:plan first." and stop.
 
 ### Step 1.5: Load State and Show Resumption Context

package/.aether/docs/command-playbooks/continue-verify.md

@@ -26,6 +26,7 @@ Extract: `goal`, `state`, `current_phase`, `plan.phases`, `errors`, `memory`, `e
 
 **Validation:**
 - If `goal: null` -> output "No colony initialized. Run /ant:init first." and stop.
+- If `milestone` == `"Crowned Anthill"` -> output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop.
 - If `plan.phases` is empty -> output "No project plan. Run /ant:plan first." and stop.
 
 ### Step 1.5: Load State and Show Resumption Context
@@ -404,3 +405,35 @@ Cross-reference worker claims against reality. This step catches fabricated succ
    **CRITICAL:** Do NOT proceed to Step 1.6. Do NOT advance the phase. The verification failure is a hard block just like a test failure.
 
 Continue to Step 1.6.
+
+### Step 2.0.6: Midden Collection (NON-BLOCKING)
+
+After verification passes, collect failure records from any recently merged branch worktrees. This step is silent and non-blocking -- continue proceeds even if collection fails.
+
+**Per D-04: Wire midden-collect into /ant:continue flow.**
+
+If the colony uses a PR-based workflow and a merge just happened, attempt to collect the branch's midden entries:
+
+Run using the Bash tool with description "Collecting branch midden entries...":
+```bash
+# Check if there's a recently merged branch to collect from
+# The merge info comes from git log or COLONY_STATE context
+last_merge_branch="${last_merged_branch:-}"
+last_merge_sha="${last_merge_sha:-}"
+
+if [[ -n "$last_merge_branch" && -n "$last_merge_sha" ]]; then
+  collect_result=$(bash .aether/aether-utils.sh midden-collect \
+    --branch "$last_merge_branch" --merge-sha "$last_merge_sha" \
+    2>/dev/null || echo '{"ok":false}')
+  collect_ok=$(echo "$collect_result" | jq -r '.ok // false' 2>/dev/null)
+  if [[ "$collect_ok" == "true" ]]; then
+    collect_status=$(echo "$collect_result" | jq -r '.result.status // "unknown"' 2>/dev/null)
+    if [[ "$collect_status" == "collected" ]]; then
+      new_entries=$(echo "$collect_result" | jq -r '.result.entries_collected // 0' 2>/dev/null)
+      echo "Midden: collected $new_entries failure entries from branch $last_merge_branch"
+    fi
+  fi
+fi
+```
+
+This step is NON-BLOCKING -- continue proceeds regardless of collection outcome. If `last_merge_branch` and `last_merge_sha` are not set (e.g., no recent merge), this step is silently skipped.

package/.aether/utils/clash-detect.sh

@@ -0,0 +1,239 @@
+#!/bin/bash
+# Clash detection utility -- detects file conflicts across git worktrees.
+#
+# When multiple agents work in parallel worktrees, they could accidentally
+# edit the same file from different worktrees. This script checks for that.
+#
+# Usage: clash-detect --file <path> [--worktree <path>]
+# Returns JSON: {ok:true, result:{conflict:false}} or
+#               {ok:true, result:{conflict:true, conflicting_worktrees:[...]}}
+#
+# Environment:
+#   AETHER_ROOT  - repo root (auto-detected if not set)
+#   WORKTREE_DIR - current worktree path (to exclude self from checks)
+#
+# When sourced by aether-utils.sh, provides _clash_detect function.
+# When run directly, executes _clash_detect with provided arguments.
+
+# Only set strict mode when run directly (not sourced)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    set -uo pipefail
+fi
+
+# Set AETHER_ROOT if not already set (e.g., when sourced)
+: "${AETHER_ROOT:=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+
+# Fallback error constant for standalone execution (when not sourced by aether-utils.sh)
+: "${E_VALIDATION_FAILED:=E_VALIDATION_FAILED}"
+
+# Allowlist of path patterns that bypass clash detection (branch-local state)
+# These files live in .aether/data/ and are unique per worktree/branch
+_CLASH_ALLOWLIST=(
+    ".aether/data/"
+)
+
+# Check if a file path matches the allowlist
+_clash_is_allowlisted() {
+    local file="$1"
+    for pattern in "${_CLASH_ALLOWLIST[@]}"; do
+        if [[ "$file" == "$pattern"* ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Normalize a path for comparison on macOS (handles /var vs /private/var)
+_clash_normalize_path() {
+    local p="$1"
+    if [[ -z "$p" ]]; then
+        echo ""
+        return
+    fi
+    if command -v realpath >/dev/null 2>&1; then
+        realpath "$p" 2>/dev/null && return
+    fi
+    (cd "$p" 2>/dev/null && pwd) || echo "$p"
+}
+
+# JSON output helpers (standalone, for direct execution mode)
+_clash_json_ok() {
+    echo "{\"ok\":true,\"result\":$1}"
+}
+
+_clash_json_err() {
+    echo "{\"ok\":false,\"error\":$1}" >&2
+    exit 1
+}
+
+# Bridge: use aether-utils JSON helpers when sourced, standalone when direct
+_cok() {
+    if type json_ok &>/dev/null; then
+        json_ok "$1"
+    else
+        _clash_json_ok "$1"
+    fi
+}
+
+_cerr() {
+    if type json_err &>/dev/null; then
+        json_err "${2:-$E_UNKNOWN}" "$1"
+    else
+        _clash_json_err "\"$1\""
+    fi
+}
+
+# Main clash detection logic
+_clash_detect() {
+    local file=""
+    local worktree="${WORKTREE_DIR:-}"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --file) file="${2:-}"; shift 2 ;;
+            --worktree) worktree="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$file" ]]; then
+        _cerr "Usage: clash-detect --file <path> [--worktree <path>]" "$E_VALIDATION_FAILED"
+    fi
+
+    # Allowlisted files never clash (branch-local state)
+    if _clash_is_allowlisted "$file"; then
+        _cok '{"conflict":false}'
+        return
+    fi
+
+    # Verify we're in a git repo
+    if ! git -C "$AETHER_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        _cok '{"conflict":false}'
+        return
+    fi
+
+    # Normalize the current worktree path for comparison
+    if [[ -n "$worktree" ]]; then
+        worktree="$(_clash_normalize_path "$worktree")" || worktree=""
+    fi
+
+    # Enumerate all worktrees
+    local conflicting=()
+    while IFS= read -r line; do
+        local wt_path
+        wt_path=$(echo "$line" | awk '{print $1}')
+        [[ -z "$wt_path" ]] && continue
+
+        local abs_wt_path
+        abs_wt_path="$(_clash_normalize_path "$wt_path")" || continue
+
+        # Skip if this is the current worktree (self-check)
+        if [[ -n "$worktree" && "$abs_wt_path" == "$worktree" ]]; then
+            continue
+        fi
+
+        # Check if this worktree has uncommitted changes to the target file
+        local file_status
+        file_status=$(git -C "$abs_wt_path" status --porcelain -- "$file" 2>/dev/null) || continue
+
+        if [[ -n "$file_status" ]]; then
+            local branch_name
+            branch_name=$(git -C "$abs_wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+            conflicting+=("\"$branch_name\"")
+        fi
+    done < <(git -C "$AETHER_ROOT" worktree list 2>/dev/null | tail -n +2)
+
+    if [[ ${#conflicting[@]} -eq 0 ]]; then
+        _cok '{"conflict":false}'
+    else
+        local conflict_list
+        conflict_list=$(printf '%s,' "${conflicting[@]}")
+        conflict_list="[${conflict_list%,}]"
+        _cok "{\"conflict\":true,\"conflicting_worktrees\":$conflict_list}"
+    fi
+}
+
+# _clash_setup
+# Install or uninstall the clash detection PreToolUse hook.
+#
+# Usage: clash-setup [--install] [--uninstall]
+# Returns JSON: {ok:true, result:{hook_installed:true/false}}
+#
+# Environment:
+#   CLASH_SETTINGS_PATH - path to settings.json (default: .claude/settings.json)
+_clash_setup() {
+    local action=""
+    local settings_path="${CLASH_SETTINGS_PATH:-$AETHER_ROOT/.claude/settings.json}"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --install)   action="install"; shift ;;
+            --uninstall) action="uninstall"; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$action" ]]; then
+        _cerr "Usage: clash-setup [--install] [--uninstall]" "$E_VALIDATION_FAILED"
+    fi
+
+    # Ensure settings file exists
+    if [[ ! -f "$settings_path" ]]; then
+        echo '{}' > "$settings_path" 2>/dev/null || {
+            _cerr "Cannot create settings file at $settings_path" "$E_FILE_NOT_FOUND"
+        }
+    fi
+
+    # Read current settings
+    local settings
+    settings=$(cat "$settings_path" 2>/dev/null) || settings='{}'
+
+    local hook_command='node .aether/utils/hooks/clash-pre-tool-use.js'
+    local hook_entry="{\"type\":\"command\",\"command\":\"$hook_command\",\"timeout\":5}"
+
+    if [[ "$action" == "install" ]]; then
+        # Check if hook already exists in PreToolUse
+        if echo "$settings" | jq -e '.hooks.PreToolUse[]?.hooks[]?.command' 2>/dev/null \
+            | grep -q "clash-pre-tool-use"; then
+            # Already installed
+            _cok '{"hook_installed":true}'
+            return
+        fi
+
+        # Add the hook to PreToolUse array
+        settings=$(echo "$settings" | jq --arg entry "$hook_entry" '
+            if .hooks.PreToolUse then
+                .hooks.PreToolUse += [{"matcher": "Edit|Write", "hooks": [($entry | fromjson)]}]
+            else
+                .hooks.PreToolUse = [{"matcher": "Edit|Write", "hooks": [($entry | fromjson)]}]
+            end
+        ' 2>/dev/null)
+
+        if [[ $? -ne 0 ]] || [[ -z "$settings" ]]; then
+            _cerr "Failed to update settings file" "$E_UNKNOWN"
+        fi
+
+        echo "$settings" > "$settings_path"
+
+        _cok '{"hook_installed":true}'
+
+    elif [[ "$action" == "uninstall" ]]; then
+        # Remove the hook from PreToolUse
+        settings=$(echo "$settings" | jq '
+            if .hooks.PreToolUse then
+                .hooks.PreToolUse = [.hooks.PreToolUse[] |
+                    select(.hooks[]?.command | . != "node .aether/utils/hooks/clash-pre-tool-use.js")
+                ]
+            end
+        ' 2>/dev/null)
+
+        echo "$settings" > "$settings_path"
+
+        _cok '{"hook_installed":false}'
+    fi
+}
+
+# Run if executed directly (not sourced)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    _clash_detect "$@"
+fi